studio-ui-patterns

Studio UI 模式

Design System 文档和演示是权威来源。创建新的 UI 前，务必先查看相关演示文件。

布局

文档：apps/design-system/content/docs/ui-patterns/layout.mdx

使用 PageContainer、PageHeader 和 PageSection 构建页面。

内容类型	size
设置 / 配置	"default"
列表 / 表格	"large"
全屏视图	"full"

• 如果列表页有筛选器 / 搜索，请将表格操作与筛选器对齐（这些操作不要使用 PageHeaderAside/PageSectionAside）
• 如果没有筛选器，操作可以放在 PageHeaderAside 或 PageSectionAside 中

演示：page-layout-settings.tsx、page-layout-list.tsx、page-layout-list-simple.tsx、page-layout-detail.tsx （均位于 apps/design-system/registry/default/example/）

表单

文档：apps/design-system/content/docs/ui-patterns/forms.mdx

• 使用 react-hook-form + zod
• 使用 FormItemLayout，不要手动组合 FormItem/FormLabel/FormMessage/FormDescription
• 使用 FormControl 包裹输入控件；从 ui 导入基础组件

布局选择：

场景	布局	容器
页面（设置 / 配置）	FormItemLayout layout="flex-row-reverse"	Card（每个字段使用 CardContent；操作使用 CardFooter）
侧边面板 — 宽	FormItemLayout layout="horizontal"	SheetSection
侧边面板 — 窄（size="sm" 或更小）	FormItemLayout layout="vertical"	SheetSection

脏状态 / 提交：

• 使用 isDirty 显示取消按钮并禁用保存按钮。仅在拥有 useForm 的组件中从 form.formState 解构该值；其他地方请使用 useFormState({ control }) 订阅（参见 react-hook-form skill）
• 通过 loading 属性显示提交按钮的加载状态
• 如果提交按钮位于 <form> 外部，请设置稳定的 formId，并在按钮上使用 form 属性

演示：form-patterns-pagelayout.tsx、form-patterns-sidepanel.tsx

表格

文档：apps/design-system/content/docs/ui-patterns/tables.mdx

模式	适用场景
Table	简单、静态、语义化的展示
Data Table	基于 TanStack；支持排序、筛选、分页；根据使用场景组合
Data Grid	虚拟化、列宽调整或复杂的单元格编辑

• 操作：置于表格上方，靠右对齐
• 搜索 / 筛选：置于表格上方，靠左对齐
• 如果表格是主要内容且没有筛选器，操作可以放在页面的主要 / 次要操作区域

演示：table-demo.tsx、data-table-demo.tsx、data-grid-demo.tsx

图表

文档：apps/design-system/content/docs/ui-patterns/charts.mdx

• 使用提供的图表构建组件；避免向 ChartContent 传入原始 Recharts 组件
• 使用 useChart 上下文标记处理加载 / 禁用状态
• 保持组合方式简单直接，避免过度抽象

演示（位于 apps/design-system/registry/default/block/）：chart-composed-demo.tsx、chart-composed-basic.tsx、chart-composed-states.tsx、chart-composed-metrics.tsx、chart-composed-actions.tsx、chart-composed-table.tsx

空状态

文档：apps/design-system/content/docs/ui-patterns/empty-states.mdx

场景	模式
初始 / 引导	展示型空状态，包含价值主张 + 明确的下一步操作
数据密集型列表	信息型空状态，与列表 / 表格布局保持一致
搜索无结果	保持与数据状态一致的布局，避免突兀的过渡
路由缺失	居中的 Admonition

演示：empty-state-presentational-icon.tsx、empty-state-initial-state-informational.tsx、empty-state-zero-items-table.tsx、data-grid-empty-state.tsx、empty-state-missing-route.tsx

导航

文档：apps/design-system/content/docs/ui-patterns/navigation.mdx

• 在一致的页面布局中展示一组相关视图的水平列表时，使用 NavMenu
• 激活某个项目必须触发 URL 变更 — 不要仅使用本地标签页状态

卡片

• 使用卡片对相关信息进行分组
• 分区使用 CardContent，操作使用 CardFooter
• 仅当周围内容未提供上下文时，才使用 CardHeader / CardTitle
• 当多张卡片代表不同的分组时（例如多个设置分区），使用标题

提示

• 使用 Admonition 标示重要操作、限制或关键上下文
• 放在页面内容顶部（页面标题下方）或相关分区顶部（分区标题下方）
• 谨慎使用

抽屉（侧边面板）

当切换页面会造成干扰，且用户需要保留当前上下文时（例如从列表中选择一行进行编辑），使用 Sheet。

结构：

• 表单需要水平布局时，使用 SheetContent，并设置 size="lg"
• 使用 SheetHeader、SheetTitle、SheetSection、SheetFooter
• 提交 / 取消操作放在 SheetFooter 中

抽屉中的表单：

• 较宽的抽屉使用 layout="horizontal"
• 较窄的抽屉（size="sm" 或更小）使用 layout="vertical"
• 抽屉包含表单时，使用 useConfirmOnClose + DiscardChangesConfirmationDialog 接入未保存更改时的关闭确认（取消、Escape 和点击背景）。权威来源：apps/design-system/content/docs/ui-patterns/modality.mdx（未保存表单的关闭确认）。另请参阅 react-hook-form 技能中关于解构 isDirty 的说明。

文案

权威来源：apps/design-system/content/docs/copywriting.mdx — 句首字母大写、标题式大小写、专有名词、语气与风格。

更改可见文案时，使用 grep 在 e2e/studio/ 中查找旧字符串。