Ordo UI
组件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——

源码

packages/ui/src/components/async-state.tsx
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 /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

异步状态占位(loading、empty、error),统一加载与失败态;与 Suspense 或查询状态搭配使用。