空状态 · EmptyState

空状态用于内容展示场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

安装与前置条件

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

空状态 · 综合展示 1：首先体验这个示例，再查看代码理解组件的组合方式。
空状态 · 交互示例 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
空状态 · 交互示例 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
空状态 · 交互示例 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

Empty State

EmptyState shows a placeholder when a content area has no data. Use it for empty lists, zero search results, first-time setups, or cleared inboxes. Always include a title and a next step so the user is not stuck.

属性	类型	默认值	说明
title *	string		在空状态内部渲染为 <h3> 标题的主要信息。
description	string		可选的辅助文本，在标题下方提供额外上下文。
icon	ReactNode		可选的图标或插图，显示在标题上方；渲染为装饰性元素（aria-hidden="true"）。
actions	ReactNode		可选的操作按钮，显示在描述下方，默认水平排列，isCompact 为 true 时垂直堆叠。
headingLevel	1 \| 2 \| 3 \| 4 \| 5 \| 6	3	仅控制渲染的 HTML 标题标签（h1-h6），使标题适配文档大纲。这是用于无障碍的语义变化，不会改变标题的视觉大小，标题大小始终固定，与级别无关。
isCompact	boolean	false	启用紧凑变体，减少间距，适用于空间受限的内容区域。
xstyle	StyleXStyles		用于布局自定义（外边距、定位、尺寸）的 StyleX 样式。必须是 stylex.create() 的值，而非内联样式对象如 style={{}}。

使用建议

Include a clear title and a call-to-action button so users know how to proceed.
Use an illustration or icon that reinforces the context of the empty state.
Use the compact variant inside cards or sidebars where space is limited.
避免：Leave an empty state without guidance; always explain what happened and what the user can do next.
避免：Use a generic message like "No data"; be specific about what is empty and why.
避免：Use an EmptyState for error messages that require immediate action; use a Banner instead.

主题 API

{
  "targets": [
    {
      "className": "astryx-empty-state",
      "visualProps": [
        "variant"
      ]
    },
    {
      "className": "astryx-empty-state-title",
      "visualProps": [
        "variant"
      ]
    },
    {
      "className": "astryx-empty-state-description",
      "visualProps": [
        "variant"
      ]
    }
  ]
}

组件结构

Icon: A visual cue above the title that reinforces the context, like a search icon for no results.
Title: Primary message explaining what is empty: "No projects yet" not "No data".
Description: Additional context explaining why it is empty or what the user can do.
Actions: One or two buttons guiding the user to a next step, like "Create project" or "Clear filters".

完整示例的额外依赖

部分示例使用独立图标包。示例清单中的每条安装命令包含该示例实际需要的依赖；若要运行本页全部示例，还需安装：

npm install @heroicons/react@2.2.0