Ordo UI
组件Feedback

EmptyState

@mox-hub/ui 组件 · Feedback · canonical

empty-state@mox-hub/uiFeedbackcanonicalsrc/components/empty-state.tsx
变体演示empty-state

暂无项目

创建第一个项目开始使用。

没有匹配结果

Props API

Prop类型默认值说明
icon*ComponentType<{ className?: string; }>——
visual*ReactNode——
variant*"page" | "card" | "compact""card"—
title*ReactNode——
description*ReactNode——
action*ReactNode——
className*string——

源码

packages/ui/src/components/empty-state.tsx
import type { ComponentType, ReactNode } from "react";
import { cn } from "../lib/utils";

interface EmptyStateProps {
  /** 可选图标:置于 muted 圆块内(design-system「Empty States」规范形态) */
  icon?: ComponentType<{ className?: string }>;
  /** 可选自定义视觉块:整体替换图标圆块(如 IconStack 等距插画),用于整页大空态/引导时刻 */
  visual?: ReactNode;
  /**
   * 应用场景变体:
   * - page:整页主体空态——h-full 撑满父内容区 + min-h-100 兜底,垂直居中(配 visual 插画)。
   *   挂载要求:必须直挂页面的 `flex-1 overflow-auto` 素块容器;中间套 flex-col 包装、
   *   或经 DataList/自动高度容器隔断都会使 h-full 解析失败回落 min-h-100(半屏)
   * - card:分区内/筛选无结果的紧凑形态(默认,min-h-40)
   * - compact:面板/分区内容内的单行空态(右栏 SidebarPanel、详情页分区内容等窄容器)——
   *   无边框无卡底,icon + 一行 muted 文案 + 可选 action,§10.6「禁止内联暂无文案」的合法出口
   */
  variant?: "page" | "card" | "compact";
  title: ReactNode;
  description?: ReactNode;
  action?: ReactNode;
  className?: string;
}

export function EmptyState({
  icon: Icon,
  visual,
  variant = "card",
  title,
  description,
  action,
  className,
}: EmptyStateProps) {
  if (variant === "compact") {
    return (
      <div
        data-slot="empty-state"
        data-variant="compact"
        className={cn(
          "flex items-center gap-2 rounded-md px-2 py-1.5 text-xs text-muted-foreground",
          className
        )}
      >
        {Icon ? (
          <Icon data-slot="empty-state-icon" className="size-3.5 shrink-0" />
        ) : null}
        <span data-slot="empty-state-title" className="min-w-0 flex-1 truncate">
          {title}
        </span>
        {action ? (
          <span
            data-slot="empty-state-action"
            className="flex shrink-0 items-center"
          >
            {action}
          </span>
        ) : null}
      </div>
    );
  }
  return (
    <div
      data-slot="empty-state"
      data-variant={variant}
      className={cn(
        "flex flex-col items-center justify-center rounded-lg border border-dashed border-border p-6 text-center",
        variant === "page" ? "h-full min-h-100" : "min-h-40",
        className
      )}
    >
      {visual ? (
        <div data-slot="empty-state-visual" className="mb-3 flex justify-center">
          {visual}
        </div>
      ) : Icon ? (
        <span
          data-slot="empty-state-icon"
          className="mb-3 flex size-12 shrink-0 items-center justify-center rounded-xl bg-muted text-muted-foreground"
        >
          <Icon className="size-6" />
        </span>
      ) : null}
      <h3
        data-slot="empty-state-title"
        className="font-heading text-heading-4 font-semibold text-foreground"
      >
        {title}
      </h3>
      {description ? (
        <p
          data-slot="empty-state-description"
          className="mt-1 max-w-md text-sm text-muted-foreground"
        >
          {description}
        </p>
      ) : null}
      {action ? (
        <div data-slot="empty-state-action" className="mt-4">
          {action}
        </div>
      ) : null}
    </div>
  );
}

可访问性与 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。

用法说明

空状态插画、文案与操作区;列表或面板无数据时使用。