组件Feedback
AsyncState
@mox-hub/ui 组件 · Feedback · canonical
async-state@mox-hub/uiFeedbackcanonicalsrc/components/async-state.tsx变体演示async-state
加载中…
暂无数据
创建第一条记录后会展示在这里。
加载失败
网络请求失败,请稍后重试。
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| isLoading* | boolean | — | — |
| isEmpty* | boolean | — | — |
| error* | string | — | — |
| onRetry* | () => void | — | — |
| loadingFallback* | ReactNode | — | — |
| labels* | Partial<AsyncStateLabels> | — | — |
| emptyIcon* | ComponentType<{ className?: string; }> | — | — |
| emptyTitle* | string | — | — |
| emptyDescription* | string | — | — |
| emptyAction* | ReactNode | — | — |
| emptyVariant* | "page" | "card" | "compact" | "card" | — |
| emptyVisual* | ReactNode | — | — |
| children* | ReactNode | — | — |
源码
import type { ComponentType, ReactNode } from "react";
import { useMessages } from "../i18n";
import { Button } from "./button";
import { EmptyState } from "./empty-state";
/**
* i18n 去耦(2026-11-08 迁移批):库不依赖 react-i18next,内置中文缺省文案
* (与主仓 i18n 资源 zh-CN 逐字一致;loading 沿用主仓英文缺省「Loading...」),
* 消费方可经 labels prop 覆写。
*/
interface AsyncStateLabels {
loading: string;
loadFailed: string;
retry: string;
noData: string;
}
interface AsyncStateProps {
isLoading?: boolean;
isEmpty?: boolean;
error?: string | null;
onRetry?: () => void;
loadingFallback?: ReactNode;
/** 文案覆写(缺省内置中文,与主仓 i18n 资源逐字一致);i18n 去耦后由消费方注入 */
labels?: Partial<AsyncStateLabels>;
emptyIcon?: ComponentType<{ className?: string }>;
emptyTitle?: string;
emptyDescription?: string;
/** 空态行动按钮(如「新建第一个」):透传 EmptyState action 槽 */
emptyAction?: ReactNode;
/** 空态场景变体透传:page=整页主体空态(撑满内容区),card=分区内紧凑形态(默认),compact=单行内嵌 */
emptyVariant?: "page" | "card" | "compact";
/** 空态自定义视觉块透传(page 变体配 IconStack 插画);错误态恒为 card 简式 */
emptyVisual?: ReactNode;
children: ReactNode;
}
export function AsyncState({
isLoading,
isEmpty,
error,
onRetry,
loadingFallback,
labels,
emptyIcon,
emptyTitle,
emptyDescription,
emptyAction,
emptyVariant = "card",
emptyVisual,
children,
}: AsyncStateProps) {
const M = useMessages();
const L: AsyncStateLabels = { ...M.asyncState, ...labels };
if (isLoading) {
return (
loadingFallback ?? (
<div
data-slot="async-state-loading"
role="status"
className="flex min-h-45 items-center justify-center text-sm text-muted-foreground"
>
{L.loading}
</div>
)
);
}
if (error) {
return (
<div data-slot="async-state-error" role="alert">
<EmptyState
title={L.loadFailed}
description={error}
action={onRetry ? <Button onClick={onRetry}>{L.retry}</Button> : undefined}
/>
</div>
);
}
if (isEmpty) {
return (
<EmptyState
icon={emptyIcon}
visual={emptyVisual}
variant={emptyVariant}
title={emptyTitle ?? L.noData}
description={emptyDescription}
action={emptyAction}
/>
);
}
return <>{children}</>;
}
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
异步状态占位(loading、empty、error),统一加载与失败态;与 Suspense 或查询状态搭配使用。