@moheng-design/ui-skill 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/README.md +227 -0
  2. package/bin/cli.js +35 -0
  3. package/bin/lib/audit.mjs +138 -0
  4. package/bin/lib/feedback.mjs +82 -0
  5. package/bin/lib/install.mjs +61 -0
  6. package/bin/lib/paths.mjs +47 -0
  7. package/bin/lib/upgrade.mjs +86 -0
  8. package/eslint/index.js +94 -0
  9. package/eslint/lib/factories.js +313 -0
  10. package/eslint/lib/match.js +188 -0
  11. package/eslint/lib/tiers.js +27 -0
  12. package/generated/SKILL.md +696 -0
  13. package/generated/contracts.json +9270 -0
  14. package/generated/mappings.schema.json +333 -0
  15. package/generated/plugin-data.js +6994 -0
  16. package/generated/reference.md +5651 -0
  17. package/generated/rules.json +3864 -0
  18. package/generated/skills/moheng-ui-audit/SKILL.md +66 -0
  19. package/generated/skills/moheng-ui-bootstrap/SKILL.md +109 -0
  20. package/generated/skills/moheng-ui-feedback/SKILL.md +65 -0
  21. package/generated/skills/moheng-ui-page/SKILL.md +75 -0
  22. package/generated/skills/moheng-ui-review/SKILL.md +55 -0
  23. package/generated/skills/moheng-ui-upgrade/SKILL.md +40 -0
  24. package/generated/unenforced.json +57 -0
  25. package/handwritten/anti-patterns.md +239 -0
  26. package/handwritten/canvas-model.md +98 -0
  27. package/handwritten/conventions.md +2082 -0
  28. package/handwritten/skills/audit.md +54 -0
  29. package/handwritten/skills/bootstrap.md +99 -0
  30. package/handwritten/skills/feedback.md +63 -0
  31. package/handwritten/skills/page.md +44 -0
  32. package/handwritten/skills/review.md +43 -0
  33. package/handwritten/skills/upgrade.md +38 -0
  34. package/handwritten/unenforced.md +27 -0
  35. package/package.json +66 -0
  36. package/stylelint/index.js +121 -0
@@ -0,0 +1,2082 @@
1
+ # 组合约定
2
+
3
+ <!-- 手写文件。§6.2:类型系统表达不了、也生成不出来的东西才写在这里 ——
4
+ 什么时候用 A 什么时候用 B、哪些组件不能嵌套、间距该由谁负责。
5
+ props 签名、类型、枚举取值、组件清单全部由生成器从契约产出,不要在这里重复。
6
+
7
+ §6.3 的结构约定(generate.mjs 会逐条校验,不满足即以非零退出码结束):
8
+ · 一个 `## 通则` 章节,填充 SKILL.md 的「组合约定」一节
9
+ · 其后每个组件一个 `## <ComponentName>` 章节,章节名与导出名逐字相同
10
+ · 每个组件章节含五个小节,顺序固定:
11
+ **用途。** → **何时使用。** → **何时改用其他组件。** → **组合约定。** → **禁止 / 使用边界。**
12
+ · 「禁止 / 使用边界」是无序列表,至少 3 条,每条以「不得」或「禁止」开头
13
+
14
+ 文体遵守 02 §8:规范文体,明确情态动词,主语是制品不是「你」,Emoji 永不出现。 -->
15
+
16
+ ## 通则
17
+
18
+ ### 三层的取用顺序
19
+
20
+ 组件分三层,选型时**自上而下**试,不要反过来:
21
+
22
+ 1. **Application Module**(26 个)—— 页面级装配件。页面骨架、导航带、指标区、
23
+ 数据控制与数据展示都已在这一层成型,直接用,不要用 Foundation 件自行拼装。
24
+ 2. **Application Atomic**(7 个)—— 应用原子件。语义按钮、搜索框、列表分页等
25
+ 带产品语义的小件。存在稳定语义适配器时**应当**优先于同职责的 Foundation 件。
26
+ 3. **Foundation**(58 个)—— 通用基础件。前两层都没有对应物时才下探到这一层。
27
+
28
+ 反向拼装的代价是可预测性:同一个控件在不同页面长得不一样,规范把这称为
29
+ 「未登记元素」,是明令禁止的。
30
+
31
+ ### token 的两层边界
32
+
33
+ | 前缀 | 定位 | 谁可以用 |
34
+ |---|---|---|
35
+ | `--ds-*` | Foundation 内部实现,可能变动 | 仅 Foundation 组件 |
36
+ | `--application-*` / `--ui-*` | 公共接口,稳定契约 | 应用代码、页面布局 |
37
+
38
+ 业务代码只读 `--application-*` 与 `--ui-*`。下探 `--ds-*` 等于依赖内部实现,
39
+ 小版本即可能失效。唯一的例外是换肤入口 `--ds-color-theme-primary`,
40
+ 应用层可以且应当覆盖它。
41
+
42
+ **任何情况下都不得在业务代码中写字面色值、圆角与间距去对齐组件。**
43
+ 需要与组件对齐时读同一个 token。
44
+
45
+ ### 间距归属
46
+
47
+ 外边距由**父容器**负责,组件自身只管内边距。
48
+
49
+ 组件不带外边距,是为了让它在任何容器里都可预测。需要间隔时由布局容器给
50
+ `gap`,不要给组件加 `margin` —— 那会让同一个组件在不同页面有不同的外观。
51
+
52
+ ### 状态一律由 CSS 表达
53
+
54
+ `:hover` / `:focus-visible` / `:disabled` / `:active` 全部已由组件内部的 CSS 伪类实现。
55
+ 业务代码**不得**用 `useState` 模拟这些状态,也不得传 `onMouseEnter` / `onMouseLeave`
56
+ 去驱动样式 —— 那会让组件强制成为 client component,且拿不到 `:focus-visible`
57
+ 与 hover 可区分这条规范要求。
58
+
59
+ ### 受控与非受控
60
+
61
+ 同时接受 `value` 与 `defaultValue`(或 `open` 与 `defaultOpen`)的组件,
62
+ 两者**互斥**:给了受控 prop 就必须同时给对应的变化回调,否则控件会锁死。
63
+
64
+ 变化回调的命名一律是 `on<X>Change`,不是 `on<X>`。
65
+ 提交语义的回调才叫 `onSubmit` —— 它与变化回调不是一回事,
66
+ `SearchField` 的 `onSubmit` 仅在 Enter 时触发,中途输入不触发。
67
+
68
+ ### 无障碍的两条硬要求
69
+
70
+ - 任何 `iconOnly` 为 true 的控件**必须**给 `aria-label`,因为它没有可见文字。
71
+ - 浮层类组件的焦点陷阱、Esc 关闭与焦点恢复已由内部 Overlay 基座实现,
72
+ 业务代码**不得**自行再挂一层 `keydown` 监听去处理 Esc,那会造成双重关闭。
73
+
74
+ ### 滚动
75
+
76
+ Content Canvas 是页面唯一的主垂直滚动权持有者。
77
+ `ScrollArea` 与 `MessageScroller` 只用于**正交方向**(水平)或**局部有界**的溢出,
78
+ 且必须给出显式高度或最大高度。不得堆叠无界的垂直滚动容器。
79
+
80
+ ### 图标
81
+
82
+ 图标一律走 `Icon` 组件。字形名必须先登记在组件库的 `src/icon/registry.json`,
83
+ 尺寸只取 14 / 16 / 18 / 20 / 24 五档。
84
+ 不得用 Emoji、系统字体符号(`✓ ★ ›`)、逐页手写内联 SVG 或临时换用其他图标库。
85
+
86
+ ### 文案
87
+
88
+ 用户可见标签是 2–4 字裸名词短语(`新建` / `列设置` / `关闭`),动词裸用,
89
+ 不写 `点击新建` 这类祈使句。Loading / Empty / Error / No Permission / Not Found /
90
+ Partial Failure 六种状态的文案各不相同,不得共用。
91
+ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
92
+
93
+ ## Icon
94
+
95
+ **用途。** 已登记字形集中的单色图标,是内容图标在系统内出现的唯一渲染入口。
96
+
97
+ **何时使用。** 凡界面上出现一个图标形状,该图标必须由本组件渲染。字形几何在构建时内联进包,运行时零外部依赖,SSR 直出完整 SVG,不存在首屏空盒子。`name` 接受 kebab 与 Pascal 两种书写形式(`chevron-down` 与 `ChevronDown` 等价)。承载图标槽位的组件(`Tabs` 的 `TabItem.icon`、`SidebarRailButton` 的 `icon`、`ToggleGroupItem` 的 `icon`)应当接收一个本组件的元素作为该槽位的值。
98
+
99
+ **何时改用其他组件。**
100
+
101
+ - 控件自身的指示符字形由控件内联绘制,不经本组件:`Checkbox` 的勾与半选横线、浮层关闭按钮的叉属于控件构件而非内容图标,尺寸也落在登记档之外。
102
+ - 状态提示的图标由 `Alert` 按 tone 自行渲染,调用方不再另传一个。
103
+ - 品牌标识不是图标。应用 logo 缺失时按登记的 mock 规则渲染纯色块,不得用本组件拼一个替代标识。
104
+ - 系统内无其他相邻组件,内容图标的渲染由本组件独占。
105
+
106
+ **组合约定。** `name` 必须已登记在 `src/icon/registry.json`;构建时的双向校验只覆盖库内 `src/`,业务代码里的未登记名字要到运行时才暴露 —— 渲染为等尺寸的隐藏占位盒,开发构建下 `console.warn`,生产构建静默。因此图标位会消失但布局不塌。`size` 取登记档 14 / 16 / 18 / 20 / 24:14 用于 chevron 类指示符,16 用于顶栏,18 用于全局动作与模块字形,20 用于工具与模块触发器,24 用于应用 logo mock 字形;12px 只登记给控件内的清除叉一处,业务代码不得取用。本组件恒为装饰件,渲染 `aria-hidden="true"` 与 `focusable="false"`,可访问名必须由承载它的控件提供 —— `Button` 与 `Toggle` 在 `iconOnly` 为 true 时必须给 `aria-label`。颜色继承 `currentColor`,由父级的 `color` 决定,`color` prop 通常不传。尺寸走 SVG 的 `width` / `height` 属性,图标容器宽度必须稳定,使 active 与 hover 的字重变化不会横向推移标签。图标与文字并排时的间隙由承载控件负责(`Button` 与 `Toggle` 的 4px gap),本组件不带外边距。二级导航的业务标签必须是图标加文字标签,窄屏下也不得丢弃图标。
107
+
108
+ **禁止 / 使用边界。**
109
+
110
+ - 不得用 Emoji、系统字体符号(✓ ★ ›)或临时引入的第三方字形库代替本组件。
111
+ - 禁止在业务代码中手写内联 `<svg>` 图标,也禁止逐页复制字形几何。
112
+ - 不得传入登记档之外的 `size`,不得用 CSS 覆盖 `width` / `height` 缩放图标。
113
+ - 不得传 `color` 覆盖前景色 —— 系统内没有填充式、双色或多色图标,颜色由承载控件的状态决定。
114
+ - 不得在未修改 `src/icon/registry.json` 的前提下引入新字形名。
115
+
116
+ ## Button
117
+
118
+ **用途。** Foundation 按钮,是按钮排版、几何、圆角与基础交互的唯一 Foundation Owner。
119
+
120
+ **何时使用。** 库内组件需要一个按钮时使用本组件。业务页面只在没有稳定应用语义可用时降级到本组件 —— 有稳定语义时一律用 `SystemButton`。已登记契约为 14/20 字号、12px 行内内边距、4px 图标间隙、16px 圆角、32px 默认高度;16px 圆角在 32px 高度下使等宽图标按钮自然成圆,系统内没有独立的 pill 或 circle token。
121
+
122
+ **何时改用其他组件。**
123
+
124
+ - 产品页面的常规动作按钮改用 `SystemButton`,它是整个产品的默认动作按钮,并承载 `loading` 与产品状态。
125
+ - 跳转到另一个 URL 用原生 `<a>`;`variant="link"` 只用于行为是按钮、视觉为行内链接的动作。
126
+ - 表达持续的两态状态改用 `Toggle`,一组互斥的显示选择改用 `ToggleGroup`。
127
+ - 工作台菜单栏条目改用 `SidebarRailButton`,应用入口改用 `SidebarAppLinkButton`。
128
+ - 页面区域内的内容分节切换改用 `Tabs`,不得用一排 ghost 按钮模拟。
129
+ - 原生 `<button>` 一律改用本组件(`mappings.json` · `no-native-button`)。
130
+
131
+ **组合约定。** `size` 与 `iconOnly` 是两根正交的轴(04 · A1):`size` 映射高度 24 / 28 / 32 / 40px,`iconOnly` 把宽度收敛为与高度相等并把行内内边距归零,两者可任意组合。`iconOnly` 为 true 时必须提供 `aria-label`,因为按钮没有可见文字。`children` 是必填的 —— 等宽图标按钮的 `children` 就是那个 `Icon` 元素。一个动作组内至多一个 `variant="primary"`;上下文区的页面动作组由 `ApplicationPageHeader` 的 `actions` 承载,同样至多一个。外边距一律由容器负责:动作对交给 `ButtonGroup`(未拼接态以 8px 分隔),页面动作组交给 `ApplicationPageHeader`,批量动作交给 `ListBatchActionBar` 的 `actions`,按钮自身不得带 margin。图标与文字的 4px 间隙由按钮的 gap 提供,不得再包一层带间距的容器。破坏性动作用 `variant="destructive"`,且必须经 `AlertDialog` 确认,批量场景的标题中写明受影响对象的数量。本组件不持有任何状态,无 `"use client"`,可直接作为 server component 使用。`size` 已从 `ButtonHTMLAttributes` 中 `Omit`,契约的四档尺寸取代原生 `size` 属性。
132
+
133
+ **禁止 / 使用边界。**
134
+
135
+ - 不得写 `size="icon"`、`size="icon-sm"`、`size="icon-lg"` 或 `variant="icon"` —— 这四个值在本库任何版本的契约中都不存在,等宽图标按钮一律走 `iconOnly`。
136
+ - 禁止用 `className` 覆盖按钮的高度、圆角、字号与行内内边距,排版几何由本组件独占。
137
+ - 不得给按下态添加缩放、位移或阴影变化 —— 按下只有颜色变化。
138
+ - 不得在同一个动作组内出现两个 `variant="primary"`。
139
+ - 不得只禁用文字而保留图标可点,禁用作用于整个交互单元。
140
+ - 禁止在业务页面自建第二套基础按钮视觉。
141
+
142
+ ## ButtonGroup
143
+
144
+ **用途。** 把一组相关 `Button` 合并为一个分段控件或间隔簇。
145
+
146
+ **何时使用。** 动作对(`重置` 与 `应用`)与分离式控件(主动作加「更多」触发器)用本组件。该组只负责拼接与分隔,不管理任何选中态。默认 `attached` 为 true,子项拼接为一个整体;`attached` 为 false 时子项以 8px 分隔、各自保留完整圆角。
147
+
148
+ **何时改用其他组件。**
149
+
150
+ - 局部显示选择改用 `ToggleGroup`,该组不持有选中态。
151
+ - 页面模式切换改用 `ApplicationPageHeader` 的 `pageModes` / `pageMode` / `onPageModeChange`。
152
+ - 页面区域内的内容分节切换改用 `Tabs`,Shell 的二级导航改用 `ApplicationSecondaryNavigation`。
153
+ - 翻页控件改用 `Pagination`,列表与表格的翻页改用 `ListTablePagination`。
154
+ - 单个动作不成组,直接用 `Button` 或 `SystemButton`。
155
+
156
+ **组合约定。** `children` 是 slot 而非数据 prop,这与 `ToggleGroup` 的 `items` 形态相反,分工是实质性的(04 · A4):本组只做拼接、不管状态,因此接受任意子节点,包括 Fragment、数组与条件渲染,子组件也不必接受或转发 `style`。拼接态的圆角压平与 1px 边框重叠由 CSS 结构伪类完成,不做属性注入,子组件的 `className` 优先级不受影响。组内按钮的 `size` 必须一致,否则拼接边缘对不齐。拼接态要求子项都有可见边框才对得上,因此不得在拼接态里混入 `variant="ghost"` 与 `variant="link"`。组渲染 `role="group"`,若该组表达的是互斥选择,说明组件选错了。组自身不带外边距,与相邻元素的距离由容器负责。子项中至多一个 `variant="primary"`。
157
+
158
+ **禁止 / 使用边界。**
159
+
160
+ - 不得用于导航。
161
+ - 禁止用于 Page Mode 切换 —— Page Mode Switch 是页面级控件,位于上下文区右侧,属于 `ApplicationPageHeader`。
162
+ - 禁止在组内混用不同 `size` 的按钮。
163
+ - 不得给子按钮加外边距来调整间隔,间隔由 `attached` 决定。
164
+ - 不得用本组表达互斥选择或多选状态。
165
+
166
+ ## Toggle
167
+
168
+ **用途。** 单个两态可按下控件,用于一个独立的格式或显示开关。
169
+
170
+ **何时使用。** 一个孤立的、可开可关的显示或格式状态用本组件,状态通过 `aria-pressed` 上报。选中态为淡强调色洗加强调前景,与分段控件的抬升式选中态有意不同。
171
+
172
+ **何时改用其他组件。**
173
+
174
+ - 在多个选项中择一,或一组同族的分段开关,改用 `ToggleGroup`。
175
+ - 立即生效的设置项(列可见性、通知开关、密度)改用 `Switch`。
176
+ - 等待「应用」或「提交」的表单数据改用 `Checkbox`,列表与表格的行选择改用 `ListSelectionCheckbox`。
177
+ - 触发一次性动作改用 `Button` 或 `SystemButton` —— 本组件表达的是持续状态,不是动作。
178
+ - 页面模式切换改用 `ApplicationPageHeader`。
179
+
180
+ **组合约定。** `pressed` 与 `defaultPressed` 互斥:受控用法传 `pressed` 并配 `onPressedChange`,非受控用法传 `defaultPressed`;`onPressedChange` 在两种用法下都会触发。`iconOnly` 为 true 时必须提供 `aria-label`。纯文字内容下选中不得仅靠颜色表达,须同时有图标或文案上的区分。尺寸轴比 `Button` 少一档 `xs`,只有 `sm` / `default` / `lg`,映射高度 28 / 32 / 40px(04 · A2)—— 需要 24px 高的可按下控件说明取错了组件族。本组件持有非受控状态,带 `"use client"`;受控用法下内部状态不参与,但指令按模块边界生效,客户端边界落在本组件上,父级无须整体转为客户端组件。多个 `Toggle` 并排时的间隔由容器的 gap 负责,本组件不带外边距。图标子节点用 `Icon`,与文字的 4px 间隙由控件的 gap 提供。
181
+
182
+ **禁止 / 使用边界。**
183
+
184
+ - 不得用一排 `Toggle` 模拟单选组,互斥语义一律交给 `ToggleGroup`。
185
+ - 不得用本组件承载立即落库的设置项,那是 `Switch` 的职责。
186
+ - 禁止用于 `pageMode` 切换。
187
+ - 不得在纯文字内容上只用颜色表达选中。
188
+ - 不得省略 `iconOnly` 形态的 `aria-label`。
189
+ - 不得把选中态改写为抬升式白色表面 —— 抬升是分段控件的表达,独立开关用淡色洗(04 · A5)。
190
+
191
+ ## ToggleGroup
192
+
193
+ **用途。** 一组分段式开关,用于一个局部显示选择 —— 密度、对齐方式、局部视图标记。
194
+
195
+ **何时使用。** 一组必须同时可见、立即生效的显示选项用本组件。选项以 `items` 数组声明,顺序即渲染顺序。选中项从浅色轨道上抬起为表面色加强调色文字,这与 Page Mode Switch 是同一套分段控件表达。
196
+
197
+ **何时改用其他组件。**
198
+
199
+ - 表单或筛选面板中的互斥选择,2–5 个选项且需全部可见,改用 `RadioGroup`;6 个及以上改用 `Select`;需要输入筛选改用 `Combobox`。
200
+ - 一个孤立的开关改用 `Toggle`,一组动作按钮改用 `ButtonGroup`。
201
+ - 页面区域内的内容分节切换改用 `Tabs`。
202
+ - 页面模式切换改用 `ApplicationPageHeader` 的 `pageModes` / `pageMode` / `onPageModeChange`;SPLIT 右栏的 View Mode Switch 改的是 `dataPresentation`,绝不改 `pageMode`。
203
+ - 呈现设置的入口按钮按当前呈现方式命名(`列设置` / `卡片设置` / `看板设置`),由 `ApplicationQueryToolbar` 承载,不由本组件表达。
204
+
205
+ **组合约定。** `items` 是数据 prop 而非 slot,与 `ButtonGroup` 的 `children` 形态相反,分工是实质性的(04 · A4):本组管理受控选中态,必须知道有哪些值。每个选项的 `label` 与 `icon` 至少提供其一,只有 `icon` 而无 `label` 时该项收敛为等宽方格。`type` 决定 `value` 的形态与无障碍语义:`single` 渲染 radio 语义、`value` 为 string,`multiple` 上报 `aria-pressed`、`value` 为 string[],两者必须匹配。受控用 `value` 配 `onValueChange`,非受控用 `defaultValue`;`single` 且未提供 `defaultValue` 时默认选中 `items[0].value`,因此单选组永远有一个选中项,不存在空态。整组禁用用 `disabled`,单个选项禁用用 `ToggleGroupItem.disabled`,两者可叠加。容器高度为 28 / 32 / 40px,选项高度是容器高度减去上下各 2px 的轨道内边距,得 24 / 28 / 36px;36px 是派生值而非标尺档位,不得为它新增 token。本组件持有非受控状态,带 `"use client"`。组自身不带外边距,与相邻控件的距离由容器负责。
206
+
207
+ **禁止 / 使用边界。**
208
+
209
+ - 禁止用于 `pageMode` —— Page Mode Switch 是页面级控件,位于上下文区右侧、页面动作组之后,属于 `ApplicationPageHeader`,且绝不能被折叠进「更多」菜单。
210
+ - 不得把 `items` 改写为 children 形态,也不得在组内直接渲染 `Toggle` 充当选项。
211
+ - 不得在 `type="single"` 下传入 string[],也不得在 `type="multiple"` 下传入 string。
212
+ - 不得把本组当作导航使用,切换选项不得改变路由。
213
+ - 不得用本组承载一次性动作,动作组交给 `ButtonGroup`。
214
+ - 不得为「与 `Toggle` 统一」而把选中态改为淡强调色洗,抬升式是分段控件的既定惯例(04 · A5)。
215
+
216
+ ## Input
217
+
218
+ **用途。** 单行文本控件,承担表单行与筛选行内的自由文本、数字与日期录入。
219
+
220
+ **何时使用。** 值由用户自由键入、不来自固定选项集合时,该控件是默认选择。最小高度 32px、圆角 8px、字号 14/20px,宽度撑满父容器。置于 `Field` 内构成标准表单行;置于 `InputGroup` 内构成带前后附加物的单一焦点单元;日期录入由该控件与 `Calendar` 一起放进 `Popover` 组成。
221
+
222
+ **何时改用其他组件。**
223
+
224
+ - 纯文本搜索 → `SearchField`。产品内每一处搜索共用该入口,不得用该控件自行拼装工具栏搜索框。
225
+ - 多行备注、说明与事由 → `Textarea`。
226
+ - 定长验证码 → `InputOTP`。
227
+ - 值来自固定集合 → `Select`;选项极多或密集的行内编辑器 → `NativeSelect`;需要输入筛选 → `Combobox`;2–5 个选项且需全部可见 → `RadioGroup`。
228
+ - 布尔值 → `Checkbox`(等待提交的表单数据)或 `Switch`(立即生效的设置)。
229
+ - 数值区间拖拽 → `Slider`。
230
+ - 只读回显 → `ApplicationRecordDetailBody` 的 `DetailField`。
231
+
232
+ **组合约定。**
233
+
234
+ - 该控件不自带外边距,宽度为父容器的 100%。列宽与行距由 `Field` 与 `ApplicationFormDialog` 的字段网格负责,调用方不得给该控件设 margin 或固定宽度。
235
+ - 置于 `Field` 内时,`Field.htmlFor` 与该控件的 `id` 必须成对设置。`Field` 不生成 id,缺一则标签点击不聚焦控件。
236
+ - `Field.error` 与该控件的 `invalid` 必须同时设置。两者不联动(04 · I5):只设 `error` 时错误文字出现而边框仍为常态色,且没有任何报错。
237
+ - 无可见标签的位置(工具栏、表格单元格编辑器)必须给 `aria-label`。
238
+ - 置于 `InputGroup` 内时必须是壳的直接子元素,一个壳只放一个控件。焦点只在最外层壳表达一次。
239
+
240
+ **禁止 / 使用边界。**
241
+
242
+ - 不得给该控件传 `type="search"` / `type="checkbox"` / `type="radio"` / `type="range"` —— 四者分别由 `SearchField` / `Checkbox` / `RadioGroup` / `Slider` 承担。
243
+ - 不得覆盖该控件的边框、圆角、背景与焦点视觉,`className` 只用于布局宽度与栅格定位。
244
+ - 禁止用 JS state 记录焦点并据以切换样式。焦点态由 `:focus-visible` 表达,调用方传入的 `onFocus` 不得被赋予视觉职责(04 · I2、I3)。
245
+ - 不得在该控件外再套一层自绘边框充当输入框外壳 —— 双层边框与双圈焦点环即为该写法的症状。
246
+ - 不得用禁用态的该控件展示只读内容。
247
+
248
+ ## InputGroup
249
+
250
+ **用途。** 单一焦点壳,把前置与后置附加物和一个录入控件收进同一圈边框与同一圈焦点环。
251
+
252
+ **何时使用。** 控件左右需要图标、单位、文字前缀、清除按钮或提交动作,且这些附加物与控件构成同一个焦点单元时使用。最小高度 32px、圆角 8px、内部间隙 8px,与 `Input` 的外壳几何一致。该组件是 `SearchField` 适配的 Foundation 基座。
253
+
254
+ **何时改用其他组件。**
255
+
256
+ - 纯文本搜索 → `SearchField`。不得把该外壳复制进页面再拼一个搜索框。
257
+ - 控件没有附加物 → 直接用 `Input` / `Textarea` / `NativeSelect`,不得为统一写法而空套一层。
258
+ - 需要标签与校验文字 → `Field`。两者是不同层的壳,可以叠用:`Field` 在外,该组件在内。
259
+ - 一行内并列多个彼此独立的控件 → 由页面容器排布,该组件只管一个焦点单元。
260
+ - 并列多个按钮 → `ButtonGroup`。
261
+
262
+ **组合约定。**
263
+
264
+ - `children` 只放一个控件,且必须是 `Input`、`Textarea`、`NativeSelect` 三者之一并作为壳的直接子元素。剥壳规则按类名匹配直接子元素,中间再包一层 `div` 会使剥壳静默失效,表现为双层边框与双圈焦点环。
265
+ - 附加物一律走 `leading` 与 `trailing`,不得混写进 `children`。
266
+ - 附加物中的图标必须用 `Icon` 组件并取登记尺寸 14 / 16 / 18 / 20 / 24。
267
+ - 该组件的 `disabled` 只改外壳视觉,不会禁用内部控件。整组禁用时该组件的 `disabled` 与内部控件的 `disabled` 必须同时设置,否则外壳呈禁用色而输入框仍可键入。
268
+ - 外边距由父容器负责,该组件不自带 margin。
269
+
270
+ **禁止 / 使用边界。**
271
+
272
+ - 不得依赖内部控件的 `invalid` 表达可见的校验失败态 —— 外壳已把内部控件的边框剥掉,该位置的 `invalid` 只保留 `aria-invalid` 语义。可见失败态由包裹该组件的 `Field` 的 `error` 承担。
273
+ - 不得让内部控件再绘制第二圈焦点环。焦点由外壳的 `:focus-within` 表达一次。
274
+ - 禁止把该组件的外壳样式复制进业务代码,用来自制搜索框、单位输入框或带按钮的输入框。
275
+ - 不得在一个壳内放两个及以上录入控件。
276
+ - 不得依赖「子组件把 `style` 展开在自己样式最后」这类未成文约定来剥壳(04 · I6),剥壳由后代选择器完成。
277
+
278
+ ## InputOTP
279
+
280
+ **用途。** 定长验证码录入,每一位一个独立方框,光标随输入自动前进。
281
+
282
+ **何时使用。** 短信或邮件验证码这类长度固定、逐位对齐的一次性码录入使用该组件。方框 40×40px,间隙 8px,字号 16/24px,`length` 默认为 6。该组件在目录中已登记但尚未在生产业务代码中集成(04 · I20),仅在确有验证码录入需求时选用。
283
+
284
+ **何时改用其他组件。**
285
+
286
+ - 长度不固定的文本或数字 → `Input`。
287
+ - 需要前后附加物的单行录入 → `InputGroup` 包裹 `Input`。
288
+ - 金额、电话、证件号这类需要分段显示的格式化录入 → `Input`。系统内没有分段格式化控件,该需求须作为规范缺口上报,不得用本组件冒充。
289
+
290
+ **组合约定。**
291
+
292
+ - `value` 与 `onValueChange` 必须成对使用。只传 `value` 不传回调,该组件不可输入。非受控用 `defaultValue`,与 `value` 二者不得同时给。
293
+ - 值以空格占位保持「第 i 个字符对应第 i 格」,尾部空格被裁掉。调用方在提交前必须同时判定「不含空格」与「长度等于 `length`」,只比长度会把跳格漏填的码判为已填完。
294
+ - 粘贴由该组件接管:从当前格起依次填入,并把焦点移到最后一个填充位。调用方不得再自行绑定粘贴处理。
295
+ - 每个方框自带中文 `aria-label`(第 N 位),该文案不可覆盖 —— 单语言是既定裁决(04 · I16),不是遗漏。
296
+ - 外边距与整体对齐由父容器负责,该组件不自带 margin。
297
+
298
+ **禁止 / 使用边界。**
299
+
300
+ - 不得用 `Field.htmlFor` 关联该组件 —— 它渲染 `length` 个 `<input>`,没有单一可关联的 id。需要标签时由 `Field.label` 单独承担说明。
301
+ - 不得把该组件放进 `InputGroup` —— 剥壳规则不覆盖它,结果是壳中壳与双圈焦点环。
302
+ - 禁止把该组件当作通用定长输入使用,例如固定位数的编号、金额或年份。
303
+ - 不得在每次 `onValueChange` 时发起校验请求。提交时机由调用方在码填满后决定。
304
+ - 不得覆盖方框的 40px 几何与间隙。
305
+
306
+ ## Textarea
307
+
308
+ **用途。** 多行文本控件,承担备注、说明与事由这类自由描述的录入。
309
+
310
+ **何时使用。** 内容预期跨行、且用户需要看到已输入的整体时使用。默认 4 行,圆角 8px,字号 14/20px,宽度撑满父容器,仅允许垂直方向调整尺寸。该控件与 `Input` 共享边框、焦点与校验失败契约。
311
+
312
+ **何时改用其他组件。**
313
+
314
+ - 单行内容 → `Input`。
315
+ - 纯文本搜索 → `SearchField`。
316
+ - 只读的长文本回显 → `ApplicationRecordDetailBody` 的 `DetailField`,长值自动断行。
317
+ - 富文本、结构化正文或带格式的说明 → 系统内没有对应组件,该需求须作为规范缺口上报,不得用该控件拼装。
318
+
319
+ **组合约定。**
320
+
321
+ - 输入区高度由 `rows` 决定,默认 4 行。需要更高的输入区改 `rows`,不得用 CSS 覆盖高度。
322
+ - `Field.error` 与该控件的 `invalid` 必须同时设置(04 · I5),两者不联动。
323
+ - 置于 `Field` 内时,`Field.htmlFor` 与该控件的 `id` 必须成对设置。
324
+ - 无可见标签的位置必须给 `aria-label`。
325
+ - 置于 `ApplicationFormDialog` 的字段网格中时,跨列由外层 `Field` 承担 —— 契约登记的写法是给 `Field` 传 `style={{ gridColumn: '1 / -1' }}`,该控件本身不参与网格定位。
326
+ - 外边距由父容器负责,该控件不自带 margin。
327
+
328
+ **禁止 / 使用边界。**
329
+
330
+ - 不得把调整方向改为横向或双向 —— 横向拉伸会撑破表单栅格,该控件只许竖向拉。
331
+ - 不得覆盖该控件的边框、圆角、背景与焦点视觉。
332
+ - 禁止用该控件承载代码、表格或任何需要等宽对齐的内容。
333
+ - 不得在该控件外再套一层自绘边框充当输入框外壳。
334
+ - 不得用禁用态的该控件展示只读的长文本。
335
+
336
+ ## Field
337
+
338
+ **用途。** 表单行外壳:标签、一个控件、一行说明或错误,三者共用一套垂直节奏。
339
+
340
+ **何时使用。** `ApplicationFormDialog` 内的标准表单行一律用该组件。凡是「有标签、可能出校验错误、需要与相邻字段对齐」的录入位置都属于它的职责范围。内部间隙 4px,说明与错误文字为 12/16px。该组件只拥有垂直节奏,绝不干预控件自身的边框、高度与圆角。
341
+
342
+ **何时改用其他组件。**
343
+
344
+ - 没有校验信息、也不需要垂直节奏的裸标签 → `Label`,适用于行内筛选器、工具栏控件、表格单元格编辑器。
345
+ - 只读字段的名值对 → `ApplicationRecordDetailBody` 的 `DetailField`。
346
+ - 提交级失败(不属于任何单一字段)→ `ApplicationFormDialog` 的 `error`,渲染为主体顶部的 `Alert`,不得塞进某一行的 `error`。
347
+ - 控件需要前后附加物 → 在该组件之内再嵌 `InputGroup`,两者不是二选一。
348
+
349
+ **组合约定。**
350
+
351
+ - `children` 只放一个控件。一行两个控件(如日期区间的起止)须拆成两个 Field,或由调用方容器自行排布。
352
+ - 标签由 `Label` 渲染,`Label` 是标签视觉的 Foundation Owner。不得在 `children` 里另写一份标签实现(04 · I4)。
353
+ - `htmlFor` 与控件的 `id` 必须成对设置。该组件不生成 id。
354
+ - `error` 存在时取代 `description`,两者不同时显示。因此说明性信息不得成为错误文案的必要补充。
355
+ - `error` 与内部控件的 `invalid` 必须同时设置。该组件不会把控件切到失败态(04 · I5),这是有意保留的不联动,漏写由阶段 5 的 lint 规则拦截。
356
+ - `required` 只渲染标签后的星号,且该星号带 `aria-hidden`。必填语义必须由控件自身的 `required` 承担。
357
+ - 字段之间的间距由 `ApplicationFormDialog` 的网格负责,该组件不自带外边距。跨列写法是给该组件传 `style={{ gridColumn: '1 / -1' }}`,这是 `ApplicationFormDialog` 契约登记的写法。
358
+
359
+ **禁止 / 使用边界。**
360
+
361
+ - 不得用该组件改动内部控件的边框、高度或圆角 —— 控件视觉归控件自己所有。
362
+ - 不得只设 `error` 而不设控件的 `invalid`:错误文字会出现,控件边框仍是常态色,且没有任何报错。
363
+ - 禁止在一个 Field 内放多个录入控件。
364
+ - 不得用该组件包裹只读内容充当详情页布局。
365
+ - 不得让 Loading / Empty / Error / No Permission / Not Found / Partial Failure 六种状态共用同一句 `error` 文案。
366
+
367
+ ## Label
368
+
369
+ **用途。** 独立控件标签,同时是标签视觉的 Foundation Owner —— 必填星号的样式、间距与颜色以该组件为准。
370
+
371
+ **何时使用。** 需要标注控件、但不需要 `Field` 的垂直节奏与校验信息位时使用:行内筛选器、工具栏控件、表格单元格编辑器。字号 14/20px,星号与文字之间的间隙是半档 2px。标准表单行一律用 `Field`,它自带标签。
372
+
373
+ **何时改用其他组件。**
374
+
375
+ - 标准表单行的标签 → `Field`。`Field` 内部已复用该组件,不得在 `Field` 之外再补一个。
376
+ - 只读字段名 → `ApplicationRecordDetailBody` 的 `DetailField.label`。
377
+ - 分节标题 → `ApplicationRecordDetailBody` 的 `DetailSection.title`;页面标题 → `ApplicationPageHeader` 的 `title`。
378
+ - 状态或分类标记 → `Badge`。标签与状态标记是两类东西,不得互相顶替。
379
+
380
+ **组合约定。**
381
+
382
+ - `htmlFor` 与控件的 `id` 必须成对设置。
383
+ - `required` 渲染的星号带 `aria-hidden`,只是视觉标记。必填语义必须由控件自身的 `required` 承担。
384
+ - 该组件是 inline-flex 且不自带外边距,与控件之间的间距由父容器负责。
385
+ - 星号与文字的间隙由容器的 gap 承担,不是星号自己的 margin。调用方不得改写这一处几何 —— 标签有多个子节点时两种写法表现不同(04 · I4)。
386
+ - 一组多选或一组开关在系统内没有组级组件,其分组标题由该组件承担,选项的排布与间距由调用方容器负责。
387
+ - 用户可见的标签文案是 2–4 字裸名词短语,例如 `名称`、`所属模块`、`生效日期`。
388
+
389
+ **禁止 / 使用边界。**
390
+
391
+ - 不得把该组件用作正文、说明文字或分节标题的样式来源。
392
+ - 禁止同时用该组件与 `Field.label` 标注同一个控件 —— 会产生两个无障碍名称。
393
+ - 不得在该组件内嵌入按钮、链接或其他可聚焦元素。
394
+ - 不得只用星号表达必填而不设控件的 `required`。
395
+ - 不得在标签文案里写动词短语或提示语,例如「请输入名称」。
396
+
397
+ ## Checkbox
398
+
399
+ **用途。** 独立的布尔选择,16px 方框、4px 圆角,选中时以强调色填充,并支持父级行的 mixed 半选态。
400
+
401
+ **何时使用。** 等待「提交」或「应用」的表单数据用该组件 —— 这是它与 `Switch` 的唯一区分标准,与视觉偏好无关。多选清单、条款确认,以及「全选」这类父级行的半选表达都属于它的职责范围。指示符字形(勾与横线,10px)是控件构件,内联在组件内而不走 `Icon`。
402
+
403
+ **何时改用其他组件。**
404
+
405
+ - 列表、表格、卡片网格与看板的记录选择 → `ListSelectionCheckbox`。该适配器拥有选择语义,阻止点击冒泡(勾选永远不会顺带打开该行),并唤出 `ListBatchActionBar`。
406
+ - 立即生效的设置,如列可见性、通知开关、密度 → `Switch`。
407
+ - 一组互斥单选 → `RadioGroup`。单选的语义单位是组,不得用多个该组件模拟。
408
+ - 属于显示设置而非表单数据的择一切换 → `ToggleGroup`;单个独立的显示开关 → `Toggle`。
409
+
410
+ **组合约定。**
411
+
412
+ - `checked` 必须与 `onCheckedChange` 配对使用。非受控用 `defaultChecked`,与 `checked` 互斥。
413
+ - `indeterminate` 优先级高于 `checked`,只用于「全选」这类父级行。
414
+ - `className` 与 `style` 作用于外层可见的 `<label>`,其余属性透传给内部 `<input>`(04 · I8)。因此 `id`、`name`、`value`、`aria-*` 会正确落在控件上,而布局类样式必须走 `className`。
415
+ - 未传 `label` 时必须给 `aria-label` 或 `aria-labelledby`,否则该控件没有无障碍名称。
416
+ - `label` 与方框同属一个 `<label>`,点击文字即可切换。放进 `Field` 时不得再用 `Field.label` 标注同一个控件。
417
+ - 该组件是 inline-flex、内部间隙 8px,不自带外边距。多个该组件之间的间距与排布由调用方容器负责。
418
+
419
+ **禁止 / 使用边界。**
420
+
421
+ - 不得用该组件做列表或表格的行选择 —— 冒泡拦截、表头 mixed 语义与批量动作栏联动都不在该组件的职责内。
422
+ - 禁止用该组件表达立即生效的设置项。
423
+ - 不得用 `aria-checked="mixed"` 自行模拟半选,必须用 `indeterminate`:原生 `input.indeterminate` 只能由 DOM property 赋值,自行模拟会让表单序列化与部分辅助技术读到错误状态(04 · I10)。
424
+ - 不得覆盖方框的 16px 尺寸、4px 圆角与选中填充色。
425
+ - 不得把 `className` 期望落到内部 `<input>` 上 —— 它作用于外层 `<label>`。
426
+
427
+ ## Select
428
+
429
+ **用途。** 表单行与筛选行中的默认单选下拉:32px 触发器配自绘浮层,选中项以淡强调色洗与对勾双重标记。
430
+
431
+ **何时使用。** 值域固定、选项数量适中的单选一律用该组件,它是系统内选择控件的默认项。选项在 6–20 条之间,或选项需要富内容标签(前置图标、状态点)时必须选它。表单场景由 `Field` 包裹一层,筛选场景直接落在查询工具栏的控制行上。浮层最高 280px,按 32px 行高完整容纳 8 条,超出部分在浮层内滚动。
432
+
433
+ **何时改用其他组件。**
434
+ - 选项极多,或控件位于密集的表格行内编辑器:`NativeSelect`。
435
+ - 需要输入即筛选:`Combobox`。
436
+ - 2–5 个选项且要求全部可见:`RadioGroup`。
437
+ - 该选择是显示设置而非表单数据:`ToggleGroup`。
438
+ - 该选择是查询工具栏中的常驻筛选维度,需要结果数、需要回写第三行筛选标签:`ApplicationFilterMenu`。
439
+ - 条目是动作而非取值(编辑、删除、导出):`DropdownMenu`。
440
+ - 该维度需要多选:`ApplicationFilterMenu` 或 `ToggleGroup`。该组件只承载单值。
441
+
442
+ **组合约定。** 触发器宽度撑满父容器,浮层与触发器等宽,因此宽度必须由父级布局或 `Field` 决定,组件自身不设宽度、不带外边距。`SelectOption` 的 label 在触发器与选项内均以省略号截断,故标签必须在触发器宽度内读完。受控用法下 `value` 与 `onValueChange` 必须成对出现;只给 `value` 而不给 `onValueChange` 会得到一个永不改变的控件。`invalid` 与包裹它的 `Field` 的 `error` 不联动,校验失败时两者必须同时设置。剩余属性落在根 `<div>` 上而非触发器,因此 `Field.htmlFor` 对该组件无效,可见标签必须由 `Field.label` 或 `Label` 给出。占位文字默认为「请选择」,本库单语言,不接受运行时本地化。
443
+
444
+ **禁止 / 使用边界。**
445
+ - 不得向 `value` 传数组充当多选。
446
+ - 不得在 `SelectOption.label` 中放入按钮、链接、输入框等可交互元素 —— 整行是唯一的选择目标,内部交互无法触达。
447
+ - 不得用该组件承载动作菜单。
448
+ - 禁止手写触发器加浮层复刻同一形态,也禁止覆盖浮层的圆角、阴影与选中态色值。
449
+
450
+ ## NativeSelect
451
+
452
+ **用途。** 平台原生 `<select>` 套用已登记的 32px 外壳,下拉面板交还浏览器绘制。
453
+
454
+ **何时使用。** 仅在原生选择器确实优于自绘浮层的两种场景使用:选项极多,以及密集的表格行内编辑器。这两种场景之外的选择一律用 `Select`。选用它即接受下拉面板不受设计系统浮层样式约束,这是该组件的既定代价。
455
+
456
+ **何时改用其他组件。**
457
+ - 表单与筛选行中的常规单选:`Select`。
458
+ - 需要输入即筛选:`Combobox`。
459
+ - 2–5 个选项且要求全部可见:`RadioGroup`。
460
+ - 该选择是显示设置:`ToggleGroup`。
461
+
462
+ **组合约定。** `NativeSelectOption.label` 必须是纯文本,原生 `<option>` 不接受富内容。`placeholder` 渲染为一个 `value=""` 的首项,受控用法下清空即把 `value` 置为空串。剩余属性透传到原生 `<select>` 上,因此 `id`、`name`、`required` 与原生 `onChange` 全部有效 —— 该组件与 `Slider` 是本组内仅有的两个可用 `Field.htmlFor` 建立标签关联的成员。`invalid` 同时设置 `aria-invalid` 与 danger 边框,与 `Field.error` 不联动,两者必须同时设置。
463
+
464
+ **禁止 / 使用边界。**
465
+ - 不得设置原生 `multiple` 或 `size` 属性 —— 32px 外壳只为单行选择器登记,多行列表框会撑破控件几何。
466
+ - 不得向 `NativeSelectOption.label` 传 JSX。
467
+ - 不得为了视觉统一而在标准表单里用该组件替代 `Select`。
468
+ - 禁止对浏览器绘制的下拉面板做样式覆盖。
469
+
470
+ ## Combobox
471
+
472
+ **用途。** 输入即筛选的单选控件,在一个固定的本地选项集合内按文本收敛后择一。
473
+
474
+ **何时使用。** 选项多到不便逐条扫视,但仍是一份调用方已持有的固定集合时使用。它只做本地筛选,不持有任何业务状态,也不发起任何请求。列表须来自服务端时,请求由调用方 Module 持有,整体替换 `options`。浮层最高 260px,比 `Select` 略矮,因为输入框已占去一行。
475
+
476
+ **何时改用其他组件。**
477
+ - 选项少到可一眼扫完:`Select`。
478
+ - 纯文本搜索且以 Enter 提交,而非从固定集合中择一:`SearchField`。
479
+ - 键盘优先的全局命令入口,条目是动作:`Command`。
480
+ - 从通讯录中选人:`PeoplePickerDialog`。
481
+ - 查询工具栏中的常驻筛选维度:`ApplicationFilterMenu`。
482
+ - 2–5 个选项且要求全部可见:`RadioGroup`。
483
+
484
+ **组合约定。** `ComboboxOption.label` 为非字符串时必须提供 `searchText`,否则该项永远无法被筛选命中,且无任何报错。`searchText` 同时用于收起状态下输入框内的回显,因此必须是完整可读的文本,不得写成匹配用的关键词缩写。该组件不提供 `invalid`,校验失败一律由包裹它的 `Field` 的 `error` 表达。宽度由父容器决定,浮层与输入框外壳等宽。选中后浮层关闭且输入被清空,调用方不得依赖输入内容作为提交值。
485
+
486
+ **禁止 / 使用边界。**
487
+ - 不得把它当搜索框使用 —— 该组件没有提交回调,逐字实时搜索也被规范禁止。
488
+ - 不得用它承载多选。
489
+ - 不得把 `emptyText` 复用为加载中或加载失败的文案 —— 它只表达筛选无结果,六种状态各有各的措辞。
490
+ - 不得在 `ComboboxOption.label` 中放入可交互元素。
491
+
492
+ ## RadioGroup
493
+
494
+ **用途。** 组级互斥择一控件,16px 圆点,选中时为强调色描边加强调色实心点。
495
+
496
+ **何时使用。** 2–5 个选项、要求全部可见、且选项文字短时使用,典型位置是表单行与筛选面板。系统内没有「单个单选项」组件,单选的语义单位就是组,全部选项必须写进 `items` 数组。选项数为 6 个及以上时改用下拉,避免整块表单被选项撑开。
497
+
498
+ **何时改用其他组件。**
499
+ - 选项 6 个及以上:`Select`。
500
+ - 该选择是显示设置而非表单数据:`ToggleGroup`。
501
+ - 单个布尔取值:`Checkbox`。
502
+ - 立即生效的开关:`Switch`。
503
+ - 该维度需要多选:`ApplicationFilterMenu` 或 `ToggleGroup`。
504
+
505
+ **组合约定。** 组内间距由组件自身负责,垂直排列为 `--ds-space-2`、水平排列为 `--ds-space-4`,调用方不得再给选项加外边距。`name` 不传时自动生成且在 SSR 下稳定,仅当该组需参与原生 `<form>` 序列化时才显式设置。整组禁用用 `disabled`,单个选项的禁用用 `RadioGroupItem.disabled`,两者不得互相替代。剩余属性落在 `role="radiogroup"` 的根元素上,因此 `aria-label` 可用于给出组名。每个选项整行是一个 `<label>`,点击行内任意位置都会切换选中。
506
+
507
+ **禁止 / 使用边界。**
508
+ - 不得逐个渲染单选项后手工拼组,那会丢掉分组的键盘导航与 `name` 绑定。
509
+ - 不得在 `RadioGroupItem.label` 中放入按钮、链接或输入框 —— 整行可点击,内部交互会被选中动作吞掉。
510
+ - 不得用它承载多选。
511
+ - 不得用水平排列承载长文案选项,横排间距只有 `--ds-space-4`,长文案会连成一片。
512
+
513
+ ## Switch
514
+
515
+ **用途。** 立即生效的开关控件,36×20 轨道加 16px 滑块。
516
+
517
+ **何时使用。** 改完即生效、无需二次提交的设置一律用该组件 —— 列可见性、通知开关、密度。典型位置是设置面板、呈现设置浮层与列设置浮层。**生效时机是它与 `Checkbox` 的唯一区分标准,与视觉偏好无关。**
518
+
519
+ **何时改用其他组件。**
520
+ - 等待「应用」或「提交」的表单数据:`Checkbox`。
521
+ - 父级行的半选态:`Checkbox`。
522
+ - 单个格式或显示开关,需要 `aria-pressed` 语义或纯图标形态:`Toggle`。
523
+ - 一组互斥的显示选项:`ToggleGroup`。
524
+ - 列表与表格的行选择:`ListSelectionCheckbox`。
525
+
526
+ **组合约定。** `className` 与 `style` 作用于外层可见的 `<label>`,其余属性透传给内部 `<button role="switch">`,这条分流是既定约定,调用方须按此预期传参。可见标签一律走 `label` prop,它与轨道同属一个 `<label>` 因而可点击;没有可见标签时必须提供 `aria-label`。`onCheckedChange` 应直接落库或落配置,回调内不得再排队等待外部提交。成组出现时的行距由容器负责,组件自身不带外边距。
527
+
528
+ **禁止 / 使用边界。**
529
+ - 不得把它放进 `ApplicationFormDialog` 的 `Field` 行充当表单字段 —— 表单行承载的是等待提交的数据,与立即生效语义相反。
530
+ - 不得为它另配「应用」按钮。
531
+ - 不得用它触发不可逆或破坏性操作,那类操作必须先经 `AlertDialog` 确认。
532
+ - 禁止覆盖 36×20 轨道与 16px 滑块的已登记几何。
533
+
534
+ ## Slider
535
+
536
+ **用途。** 单值范围控件,4px 高轨道,已选部分填充强调色。
537
+
538
+ **何时使用。** 近似值比精确值更重要的连续数值选择才用该组件 —— 阈值、透明度、图表区间。该组件在目录中已登记,但尚未在生产业务代码中集成,无明确需求时不得主动选用。选用前必须确认该数值确实允许粗调。
539
+
540
+ **何时改用其他组件。**
541
+ - 需要精确数值:`Input` 配 `type="number"`。
542
+ - 只读的完成度或进度展示:`Progress`。
543
+ - 取值是 2–5 个离散档位:`RadioGroup` 或 `ToggleGroup`。
544
+ - 取值是布尔:`Switch` 或 `Checkbox`。
545
+
546
+ **组合约定。** 剩余属性透传到内部的原生 range 输入上,因此 `id`、`name`、`aria-label` 有效,`Field.htmlFor` 与其 `id` 配对可建立标签关联。没有可见标签时必须提供 `aria-label`。`showValue` 只渲染裸数字,占固定 32px 宽的等宽数字位,单位与量纲由相邻的 `Label` 或 `Field.label` 承担。轨道宽度由父容器决定,组件自身不设宽度。`onValueChange` 在拖动过程中持续触发。
547
+
548
+ **禁止 / 使用边界。**
549
+ - 不得在 `onValueChange` 内直接发起请求或落库,提交时机必须由调用方在拖动结束后控制。
550
+ - 不得用它展示只读进度。
551
+ - 不得并排两个该组件伪造区间控件 —— 它只承载单值。
552
+ - 不得用它选择需要精确到个位的数值。
553
+
554
+ ## Calendar
555
+
556
+ **用途。** 月格日期选择器控件,周一为一周起始(一…日),固定 252px 宽;今日为淡强调色洗,选中为强调色实心填充。
557
+
558
+ **何时使用。** 作为日期字段的取值面板使用,与 `Input` 一同放进 `Popover`。筛选区间由调用方持有起止两个值,各配一个该组件。**该组件是控件,不是承载面** —— `CALENDAR` 页面模式与它同名但不同层,不得混用。
559
+
560
+ **何时改用其他组件。**
561
+ - 整页的日历承载面(`pageMode` 为 `CALENDAR`):由 `ApplicationPageLayoutContainer` 承担。
562
+ - 粒度切换加月格加当日议程栏的工作台面:`ScheduleCollaborationWorkspace`。
563
+ - 查询工具栏中作为 `dataPresentation` 的日历呈现方式:由数据呈现区承担,不是本控件。
564
+ - 日期已知且可直接键入:`Input`。
565
+
566
+ **组合约定。** `onSelect` 收到的是本地零点的 `Date`;落库、比较与按日期匹配一律使用本地时区的 ISO 日期串。`month` 只作用于首次渲染的初始月份,翻月游标由组件内部持有,后续更改 `month` 不会重置视图,调用方不得把它当受控 prop 使用。`selected` 为单值,该组件不表达区间高亮。置于 `Popover` 内时面板宽度不得小于 252px,`Popover` 的默认 320px 已足够容纳。星期名、上一月与下一月的无障碍名称、以及「年」「月」标题为中文常量,本库单语言。
567
+
568
+ **禁止 / 使用边界。**
569
+ - 不得用 `toISOString()` 生成或比较日期串 —— 该写法在 UTC+8 下必然错位一天,今日高亮与选中判断会整体错一格。
570
+ - 不得指望通过 prop 禁用不可选日期,越界日期必须由调用方在 `onSelect` 中拒绝。
571
+ - 不得用该组件拼装 `CALENDAR` 页面模式的整页承载面。
572
+ - 禁止覆盖 252px 宽度与日期格的几何。
573
+
574
+ ## Accordion
575
+
576
+ **用途。** 同一页内的堆叠式渐进披露,多个折叠区以 1px 分隔线相隔,无卡片、无阴影。
577
+
578
+ **何时使用。** 长表单或详情内容需要分组,且分组之间互斥或可并存时,该组件是默认选择。折叠区数量为 2 个及以上时必须使用本组件而非并列多个 `Collapsible`。触发行高 40px、标题 14/20 medium 字重、展开箭头 14px,这套几何由组件持有,调用方不得另行指定。
579
+
580
+ **何时改用其他组件。** 只有一个折叠区、且该区是「更多筛选」这类单一显隐入口时,改用 `Collapsible`。需要在页面区域内切换互斥内容、且切换后内容占满同一块区域时,改用 `Tabs`。业务详情的字段分节改用 `ApplicationRecordDetailBody` 的 `sections`,它已登记标题行、字段网格与分节级动作。原生 `<details>` / `<summary>` 一律不得出现,替换目标见 `mappings.json` 的 `no-native-details` 与 `no-native-summary`。
581
+
582
+ **组合约定。** 该组件根节点自带上边线,每个折叠区自带下边线,因此两个 Accordion 直接相邻时接缝处会出现 2px 线;两者之间必须存在其他内容,或改为合并进同一个 `items`。组件不带任何外边距,与上下内容的间距由容器负责。`type` 为 `single` 时组件只在自身的展开动作中收敛为至多一项,外部通过 `open` 传入的数组原样渲染 —— 受控模式下调用方必须自行保证 `single` 时数组长度为 0 或 1。`open` 与 `onOpenChange` 必须成对提供,只传 `open` 会使全部触发行失效。`title` 已由组件负责渲染展开箭头,调用方不得在 `title` 内再放一个方向字形。
583
+
584
+ **禁止 / 使用边界。**
585
+ - 不得用于页面级或区域级的内容切换,那是 `Tabs` 的职责。
586
+ - 不得只放一个 `items` 元素,单个显隐区域一律用 `Collapsible`。
587
+ - 禁止在 `content` 内再嵌套 Accordion —— 分隔线无法表达两层结构,二级分组改用 `ApplicationRecordDetailBody`。
588
+ - 禁止为折叠区补卡片外壳、边框或阴影,该组件的形态就是「仅分隔线」。
589
+ - 不得在受控模式下省略 `onOpenChange`。
590
+
591
+ ## Breadcrumb
592
+
593
+ **用途。** 真实层级的回溯路径,末项为当前页并带 `aria-current="page"`。
594
+
595
+ **何时使用。** 仅当页面确实处于一条可回溯的层级路径上时才渲染该组件,且只能出现在上下文区。层级数量必须为 2 项及以上,单项路径没有可回溯的对象。中间层级可点击、末项恒为不可点击文本,这一分工由组件持有。
596
+
597
+ **何时改用其他组件。** 表达「当前处于哪个模块」以及模块间切换,改用 `ApplicationModuleSwitcher`。SPLIT 页面模式中表达「当前在目录的哪个位置」,改用 `ApplicationSplitListSidebar`。同层级之间的并列切换改用 `Tabs` 或 `NavigationMenu`。
598
+
599
+ **组合约定。** 该组件只能作为 `ApplicationPageHeader` 的 `breadcrumb` 内容传入,间距与位置由上下文区负责,组件自身无外边距。中间层级按三态渲染:提供 `href` 渲染链接,仅提供 `onClick` 渲染按钮,两者都不提供渲染静态文本 —— 不可点击的层级必须走第三态,不得以空字符串或占位地址伪造链接。使用前端路由时必须同时提供 `href` 与 `onClick`,并在 `onClick` 内自行阻止默认跳转,组件不代为调用 `preventDefault`。末项无论是否提供 `href` 或 `onClick` 都渲染为当前页文本,两者在末项上均无效果。
600
+
601
+ **禁止 / 使用边界。**
602
+ - 不得放进 Shell 的三条导航带 —— `TopNavigationPrimaryBar` 契约已明令禁止在其中添加面包屑。
603
+ - 不得在页面并无真实层级时把面包屑作为装饰渲染。
604
+ - 不得把末项写成链接,当前页不是可跳转目标。
605
+ - 禁止用面包屑承担模块导航或页面动作。
606
+ - 禁止以单个 `items` 元素渲染该组件。
607
+
608
+ ## Command
609
+
610
+ **用途。** 键盘优先的命令面板,本地筛选并执行已登记命令。
611
+
612
+ **何时使用。** 作为全局命令与跳转入口时使用该组件,命令按 `groups` 分组,筛选后为空的分组连标题一起消失。面板宽 420px、列表区最高 320px,自带 1px 边框、12px 圆角与浮层阴影。上下键在跨分组的扁平序列上移动,回车执行当前项。
613
+
614
+ **何时改用其他组件。** 列表页的数据查询改用 `ApplicationQueryToolbar` 的搜索行,独立的纯文本搜索入口改用 `SearchField`(`mappings.json` 的 `no-native-search` 指向它)。表单内「输入即筛选」的单选控件改用 `Combobox`。上下文区或行尾收纳低频动作改用 `DropdownMenu`。
615
+
616
+ **组合约定。** 该组件必须由 `Dialog` 承载,作为 `children` 传入;它自带边框、圆角与浮层阴影,不得再被 `Card`、`Popover` 或任何带边框的容器包裹。承载它的 `Dialog` 不得再传 `title`、`description` 或 `footer` —— 搜索行就是面板的头部。关闭由 `Dialog` 负责,该组件自身不处理关闭。`CommandGroup.label` 是组件的 React key,必须在整个面板内唯一。`CommandItem.label` 为非字符串时必须提供 `searchText`,否则该项永远不会被筛选命中,且不产生任何报错。`shortcut` 仅作展示,真实快捷键必须由应用层自行注册,两处文本必须一致。
617
+
618
+ **禁止 / 使用边界。**
619
+ - 不得把该组件直接放进页面内容流,它是浮层面板。
620
+ - 不得在 `label` 为非字符串时省略 `searchText`。
621
+ - 禁止在 `shortcut` 中声明应用层并未注册的按键组合。
622
+ - 禁止分组标题重名。
623
+ - 不得用该组件替代列表页的数据查询或筛选。
624
+
625
+ ## ContextMenu
626
+
627
+ **用途。** 内容区域上的右键加速器 —— 列表行、卡片、看板块。
628
+
629
+ **何时使用。** 已在别处可达的记录级动作需要一条更快的路径时使用该组件。条目支持图标、禁用、危险色与分隔线;键盘导航跳过禁用项与分隔线,回车确认,Esc 与外部点击关闭。菜单按点击坐标定位,并在打开后按实测尺寸收回视口内。
630
+
631
+ **何时改用其他组件。** 需要一个可见的触发器(上下文区或行尾的「更多」)改用 `DropdownMenu`,它另有 `heading` 字段可渲染分组标题。编辑器型工作面的常驻菜单条改用 `Menubar`。整行可点击的目录或选择器行改用 `Item`,业务记录行改用 `ApplicationRecordList`。
632
+
633
+ **组合约定。** `children` 是右键触发区域,组件会在其外包一层 `position: relative` 的块级元素;在表格行或网格布局内使用时必须确认该额外层不破坏既有布局。任何动作都不得以右键菜单为唯一入口,记录级动作必须同时出现在行尾或详情中 —— 右键是加速器,不是可达性路径。可点击条目必须提供 `value`,缺少 `value` 的非分隔线条目会渲染出来却永不触发 `onSelect`。`destructive` 只把文字转为 danger 色,不改变确认流程,不可逆动作仍须由 `AlertDialog` 二次确认。`separator` 不得作为首项或末项。
634
+
635
+ **禁止 / 使用边界。**
636
+ - 不得把任何动作只放在右键菜单里。
637
+ - 禁止嵌套两层 ContextMenu —— 右键事件会冒泡,内外两个菜单将同时打开。
638
+ - 不得省略可点击条目的 `value`。
639
+ - 禁止用连续的 `separator` 模拟分组标题,需要标题的菜单改用 `DropdownMenu`。
640
+ - 不得把该组件用于触屏为主的界面,右键在其上不可触发。
641
+
642
+ ## Menubar
643
+
644
+ **用途。** 桌面风格的水平菜单条,用于编辑器型工作面 —— 报表设计器、看板配置器。
645
+
646
+ **何时使用。** 一个工作面同时拥有 2 个及以上顶级菜单、且每个菜单内含多条低频命令时使用该组件。菜单条高 32px、顶级菜单项高 24px、自带 1px 边框与 8px 圆角。菜单条已展开时,鼠标划过其他顶级菜单直接切换,这是桌面菜单的既定惯例。
647
+
648
+ **何时改用其他组件。** 只有一个下拉时改用 `DropdownMenu`。页面或区域之间的导航改用 `NavigationMenu`、`Tabs` 或 `Sidebar`。应用二级导航改用 `ApplicationSecondaryNavigation`。右键加速器改用 `ContextMenu`。
649
+
650
+ **组合约定。** 该组件只能位于 Content Canvas 内部,Shell 拥有自己的导航,不承载菜单条。`MenubarMenu.label` 同时是 React key 与展开态标识,必须在菜单条内唯一,重名会导致两个菜单同时展开。组件不接受子元素,顶级菜单只能来自 `menus` 数组 —— 不得在菜单项之间插入其他控件;工具按钮应放在菜单条之外的同一行容器内,间距由该容器负责。可点击条目必须提供 `value`。`shortcut` 仅作展示,真实按键绑定由承载它的工作面自行注册。
651
+
652
+ **禁止 / 使用边界。**
653
+ - 不得用作页面导航,那是 Shell 的职责。
654
+ - 不得放进 `TopNavigationPrimaryBar`、`ApplicationPrimaryNavigation` 或 `ApplicationSecondaryNavigation`。
655
+ - 禁止顶级菜单标题重名。
656
+ - 禁止在只有一个顶级菜单时使用该组件。
657
+ - 不得省略可点击条目的 `value`。
658
+
659
+ ## NavigationMenu
660
+
661
+ **用途。** 水平导航基元,条目可展开一个富内容浮层面板。
662
+
663
+ **何时使用。** 页面区域之间的水平切换,且部分入口需要展开二级内容时使用该组件。激活态是 2px 强调色下划线加 medium 字重,条目高 32px、横向内边距 12px。面板在悬停或聚焦时展开,最小宽 320px,12px 圆角,带浮层阴影。
664
+
665
+ **何时改用其他组件。** 应用二级导航一律改用 `ApplicationSecondaryNavigation` —— 那里每个业务标签强制「图标 + 文字」并由类型强制,本基元不施加该约束。同一页内切换内容区改用 `Tabs`,它另有 `count` 徽标与面板槽位。垂直排列的导航面改用 `Sidebar`。编辑器型工作面的命令菜单改用 `Menubar`。
666
+
667
+ **组合约定。** 面板从条目左边缘向右展开,组件不做视口碰撞翻转,因此带 `panel` 的条目不得放在导航行的最右端。面板的开合是组件内部状态,没有对应的 prop,调用方不得试图从外部控制。鼠标移出条目槽位即收起面板,与焦点无关,因此 `panel` 内不得放置需要多步操作的表单。`NavigationMenuItem` 没有禁用字段 —— 无权限的入口必须从 `items` 中移除,不得渲染成看似可点的项。受控使用时 `value` 与 `onValueChange` 必须成对提供。组件自身无外边距,与相邻内容的间距由容器负责。
668
+
669
+ **禁止 / 使用边界。**
670
+ - 不得用作应用二级导航。
671
+ - 禁止把激活态改成 pill 背景或只用颜色表达。
672
+ - 不得把带 `panel` 的条目放在行末。
673
+ - 不得在 `panel` 内放置输入框、多步表单或分页控件。
674
+ - 不得渲染无权限的条目。
675
+
676
+ ## Pagination
677
+
678
+ **用途。** 裸分页步进器,只承担页码窗口与翻页。
679
+
680
+ **何时使用。** 仅在确实不需要结果总数与每页条数时使用该组件。页码窗口固定为「首页 + 当前页前后各 1 页 + 末页」,跳空处插省略号,最多 7 个槽位,不可配置。当前页带 `aria-current="page"`、强调色描边与淡强调色底,不只靠颜色表达。按钮高 28px,页码使用等宽数字,翻页时按钮不左右跳动。
681
+
682
+ **何时改用其他组件。** 数据展示区的列表与表格页脚一律改用 `ListTablePagination`,它额外承载结果区间、总数与每页条数选择器。两者是替代关系而非包含关系:`ListTablePagination` 的形态是「上一页 · 当前页/总页数 · 下一页」两键步进,不渲染页码窗口。系统内无限滚动不作为分页的替代方案。
683
+
684
+ **组合约定。** 调用方必须保证 `1 ≤ page ≤ pageCount`,组件不对越界值做钳制。`pageCount` 为 1 时组件仍渲染两枚禁用的翻页按钮与单个页码,只有一页时调用方应自行不渲染整个组件。分页状态必须跨 Page Mode 与 Business View 切换存活,从详情返回时也必须还原,该状态由调用方 Module 持有 —— 组件不持有任何页码状态。组件自身无外边距,与数据展示区的间距由容器负责。
685
+
686
+ **禁止 / 使用边界。**
687
+ - 不得在列表或表格的标准页脚使用该组件。
688
+ - 不得把该组件用作步骤指示器、轮播指示器或进度表达。
689
+ - 禁止传入越界的 `page`。
690
+ - 不得依赖该组件表达结果总数或每页条数,它不承载这两项。
691
+ - 不得在同一数据展示区内同时渲染 Pagination 与 `ListTablePagination`。
692
+
693
+ ## Sidebar
694
+
695
+ **用途。** Content Canvas 内部的垂直导航面 —— 设置导航、模块子导航。
696
+
697
+ **何时使用。** 一个工作面需要按分组罗列 5 项及以上的垂直入口时使用该组件。展开宽默认 240px,折叠宽固定 56px,导航项高 36px,分组标题 12/16。选中态是淡强调色洗加强调色文字加 medium 字重,字重是颜色之外的第二信号。
698
+
699
+ **何时改用其他组件。** 工作台左侧 72px 图标栏改用 `GlobalSidebar`,它由 `SidebarRailButton` 构成,是另一个组件,两者不可互相替代。SPLIT 页面模式的左栏改用 `ApplicationSplitListSidebar`,它已登记目录搜索、结果数与目录设置三件事。水平方向的导航改用 `NavigationMenu` 或 `Tabs`。
700
+
701
+ **组合约定。** 该组件不是 Shell —— 应用外层 Shell 是刻意设计的无侧栏四带堆叠,不得因为存在本组件就往 Shell 上加一条全局左栏。组件是 `flex: 0 0 auto` 且高度 100% 的 flex 项,必须置于一个高度确定的横向 flex 容器内。该组件只有受控模式:`value` 与 `onValueChange` 必须成对提供,缺少 `onValueChange` 时点击不产生任何变化。`collapsed` 为 true 时图标是唯一可见内容,因此可能折叠的侧栏中每个 `SidebarItem` 都必须提供 `icon`;`label` 为非字符串时还必须提供 `labelText`,否则折叠态的悬浮提示不可用。折叠态不渲染分组标题与 `badge`,唯一的状态提示不得只放在 `badge` 上。`width` 只作用于展开态,折叠宽固定 56px 不随其变化。`SidebarGroup.label` 用作 React key,应在侧栏内唯一。
702
+
703
+ **禁止 / 使用边界。**
704
+ - 不得把该组件当作应用外层 Shell 的全局左栏。
705
+ - 不得用该组件替代 `GlobalSidebar`。
706
+ - 不得用该组件重建 `ApplicationSplitListSidebar` 已登记的目录搜索、结果数与目录设置。
707
+ - 禁止在可能折叠的侧栏中省略 `icon`。
708
+ - 禁止只传 `value` 而不传 `onValueChange`。
709
+
710
+ ## Tabs
711
+
712
+ **用途。** 页面区域内的局部标签页 —— SPLIT 右栏内容标签、详情分节切换。
713
+
714
+ **何时使用。** 同一块区域内需要在 2 个及以上互斥内容之间切换时使用该组件。标签高 32px、内边距 6/12、文字 14/20,激活态是 2px 强调色下划线加 medium 字重,明确不是 pill 背景。标签行下方有 1px 分隔线,`count` 徽标为 12px 等宽数字。左右方向键在标签之间移动焦点,选中须再按回车或空格。
715
+
716
+ **何时改用其他组件。** Shell 第三带的业务标签改用 `ApplicationSecondaryNavigation`,那里的图标是必填。L3 业务视图标签由 `ApplicationQueryToolbar` 承担,其第一行内部已组合本组件,不得在工具栏之外另起一行 Tabs 表达业务视图。Page Mode Switch 属于 `ApplicationPageHeader`,不得用 Tabs 或 `ToggleGroup` 搭建。密度、对齐这类局部显示选择改用 `ToggleGroup`。带浮层面板的水平导航改用 `NavigationMenu`。
717
+
718
+ **组合约定。** `children` 原样渲染,组件不做面板切换 —— 调用方必须自行依据当前 `value` 渲染对应内容。面板的 12px 上边距由组件负责,调用方不得再补上边距。`items` 为空数组时整个组件渲染 `null`,不渲染空标签行、不画分隔线、不保留高度,因此调用方不得为「暂无标签」另行渲染占位。未提供 `defaultValue` 时组件默认选中 `items[0].value` 且不检查其禁用状态,`items[0]` 为 `disabled` 时必须显式提供 `defaultValue`。受控使用时 `value` 与 `onValueChange` 必须成对提供。`count` 只接受数字。
719
+
720
+ **禁止 / 使用边界。**
721
+ - 不得用作 Shell 的二级导航。
722
+ - 禁止把激活态改成 pill 背景。
723
+ - 不得指望组件按 `value` 切换 `children`,面板内容由调用方自行决定。
724
+ - 禁止为空的 Tabs 预留高度、分隔线或占位文案。
725
+ - 禁止嵌套两级 Tabs —— 两层下划线无法区分层级,二级分组改用 `Accordion` 或 `ApplicationRecordDetailBody`。
726
+
727
+ ## AspectRatio
728
+
729
+ **用途。** 锁定一个固定宽高比的槽位,使其中的内容在加载完成前后不产生布局跳动。
730
+
731
+ **何时使用。** 槽位内容的最终尺寸在渲染时尚不可知、且到达后会撑开容器时,必须先用本组件锁比。典型场景是 `Chart` 之外的图形槽位、`FilesCollaborationWorkspace` 的文件预览栏、以及需要固定比例的嵌入内容。内容尺寸已知或由调用方直接给定像素值时,不使用本组件。
732
+
733
+ **何时改用其他组件。**
734
+ - 加载期需要展示贴近最终结构的占位形状 —— 改用 `Skeleton`,它承担 Loading 系统状态,本组件只锁几何不表达状态。
735
+ - 槽位承载的是折线、面积或柱状图 —— 改用 `Chart`,它自带绘图区高度控制,不需要外层再锁比。
736
+ - 只需要一个有边框、有标题的承载面 —— 改用 `Card`。
737
+ - 需要的是有界滚动而非固定比例 —— 改用 `ScrollArea`。
738
+
739
+ **组合约定。** 本组件不持有外边距,槽位之间的间隙由父级栅格或 `ApplicationPageLayoutContainer` 负责。`ratio` 取数字,写作 `16 / 9` 这类除式,不接受 `"16:9"` 形式的字符串。内部结构以绝对定位铺满整个槽位并裁剪溢出,因此子元素不得依赖自身外边距定位,也不得指望内容把槽位撑高。同一区域内的多个槽位应使用同一个 `ratio`,否则等高排列失效。
740
+
741
+ **禁止 / 使用边界。**
742
+ - 不得用本组件承载正文文本或表单控件 —— 槽位裁剪溢出,超出比例的内容会被静默切掉。
743
+ - 禁止把本组件用作英雄图、插画或渐变背景的容器 —— 系统内不存在这类资产。
744
+ - 不得给 `ratio` 传字符串或百分比,该值是数字。
745
+ - 不得在本组件内部再嵌套一层 `AspectRatio`,两层锁比的结果不可预期。
746
+
747
+ ## Card
748
+
749
+ **用途。** 系统的标准承载面 —— CardList 磁贴、工作台面板、图表容器、表单分节共用的那一张卡。
750
+
751
+ **何时使用。** 一段内容需要与相邻内容用边框明确划界时,必须使用本组件而非自行拼装带边框的容器。CARD 页面模式下的每一张磁贴、工作台的每一个面板、Canvas 内每一个需要标题行的分节都以它为壳。同一区域内的卡片应使用同一档 `density`,混档会破坏区域节奏。
752
+
753
+ **何时改用其他组件。**
754
+ - 承载的是指标 —— 改用 `ApplicationMetricStrip` 与 `ApplicationMetricTrend`、`ApplicationMetricStatus`、`ApplicationMetricChart`、`ApplicationMetricPrimarySecondary`。指标卡有自己的等高与只读约束,不得用 Card 复刻。
755
+ - 承载的是页面级区域划分 —— 改用 `ApplicationPageLayoutContainer`,它拥有页面内容根的内边距与区块间隙。
756
+ - 承载的是就地的、不打断的提示或部分失败 —— 改用 `Alert`。
757
+ - 承载的是可折叠的分节 —— 改用 `Collapsible`;多个互斥折叠项改用 `Accordion`。
758
+ - 承载的是一行可扫视的记录 —— 改用 `Item` 或 `ApplicationRecordList`。
759
+
760
+ **组合约定。** 本组件不持有外边距,卡片之间的间距(Standard 12px、Condensed 10px、Compact 8px)由父级栅格或 `ApplicationPageLayoutContainer` 负责。`title` 与 `extra` 同处标题行,`extra` 只放一个状态 `Badge` 或一个安静的动作。`footer` 自带上边框与一段上内边距,不需要再在它上面放 `Separator`。`interactive` 只是把光标与边框反馈打开,跳转行为仍由调用方自己挂在卡片上 —— 因此 `interactive` 为 true 时必须同时给出真实的跳转处理,只设 `interactive` 而不跳转会得到一个骗人的指针。`interactive` 为 true 时卡内不得再放独立的可点控件,除非该控件自行阻止事件冒泡。
761
+
762
+ **禁止 / 使用边界。**
763
+ - 不得给卡片添加阴影 —— 已登记契约为 16px 圆角、1px 边框、无默认装饰阴影,边框负责分隔。
764
+ - 禁止发明第三档密度:只有 `default`(16px 节奏)与 `sm`(12px)两档。
765
+ - 不得在只读的指标卡语义上设置 `interactive` —— 指标卡必须保持 `cursor: default`,整卡绝不成为导航入口。
766
+ - 不得在 Card 外面再包一层自带 padding 的容器,那会与页面内容根的内边距叠成双重外边距。
767
+
768
+ ## Carousel
769
+
770
+ **用途。** 水平分页内容,一次呈现一页,左右导航首尾相接。
771
+
772
+ **何时使用。** 内容天然成页、且用户一次只需看一页时使用。本系统是密集型应用 UI,轮播极少适用 —— 落笔前必须先确认该场景不属于标签切换或卡片网格。单页时组件自动不渲染左右导航与页点,因此传入单元素数组是安全的。
773
+
774
+ **何时改用其他组件。**
775
+ - 内容是并列的视角或分节,用户需要知道一共有几项并直接跳转 —— 改用 `Tabs`。
776
+ - 内容是同构的记录集合,需要扫视与比较 —— 改用 `Card` 组成的卡片网格,并由 `ApplicationDataDisplay` 承载。
777
+ - 只是一条需要横向滚动的标签条或筛选条 —— 改用 `ScrollArea` 并设 `horizontal`。
778
+ - 内容是消息流 —— 改用 `MessageScroller` 配 `Bubble` 或 `Message`。
779
+
780
+ **组合约定。** `slides` 的每一项占满一页宽度,各项应当结构同构、高度一致,否则翻页会带来容器高度跳动。`index` 与 `defaultIndex` 二选一:给了 `index` 即进入受控模式,此时必须同时提供 `onIndexChange`,否则页索引永远停在初始值。本组件不持有外边距,与相邻区块的间隙由父级负责。左右导航按钮与页点绝对定位在内容之上,因此 `slides` 内容的四角区域不应放置必须可点的元素。页点带 `aria-hidden`,页序信息不由它传达。
781
+
782
+ **禁止 / 使用边界。**
783
+ - 禁止用定时器驱动 `onIndexChange` 模拟自动播放 —— 系统动效只表达状态变化,无入场编排与自动轮转。
784
+ - 不得把必须始终可见的元素放进任何一页,Page Mode Switch 尤其不得被翻页藏起来。
785
+ - 不得把本组件当作 Data Presentation 使用 —— 已登记的呈现方式里没有轮播。
786
+ - 不得在一页内再嵌一个 `Carousel`,两级水平分页无法用键盘或指针区分。
787
+
788
+ ## Item
789
+
790
+ **用途。** 通用列表行 —— 目录、结构化列表复用的那一行,结构固定为前置槽位、标题加描述、尾部槽位。
791
+
792
+ **何时使用。** 一组同构条目需要以行的形式扫视、且不构成表格时使用。行高最小 40px,标题 14/20,描述 12/16,两者均单行省略。整行确实可操作时才挂 `onClick`,此时光标与 hover 反馈随之开启;静态行保持默认光标且不给 hover 底色。
793
+
794
+ **何时改用其他组件。**
795
+ - 条目需要按列对齐、排序或列级优先级 —— 改用 `Table`。
796
+ - 条目是业务记录,需要状态、关键数值与行尾记录级动作 —— 改用 `ApplicationRecordList`。
797
+ - 行属于下拉菜单、右键菜单、菜单栏或命令面板 —— 改用 `DropdownMenu`、`ContextMenu`、`Menubar`、`Command`,它们的条目写在各自的数据数组里。
798
+ - 行属于选择控件 —— 改用 `Select`、`Combobox` 或 `NativeSelect`。
799
+ - 行属于 Canvas 内的垂直导航或 SPLIT 左栏目录 —— 改用 `Sidebar` 或 `ApplicationSplitListSidebar`。
800
+
801
+ **组合约定。** 本组件不持有外边距,行与行之间的间隙由父级列表容器负责;它自带 8px/12px 内边距与 8px 圆角,父容器不得再为单行补内边距。`leading` 通常放 `Avatar`、`Icon` 或选择框,`trailing` 通常放 `Badge`、计数或动作按钮。多选场景的选择框必须使用 `ListSelectionCheckbox` 放进 `leading` —— 它会阻止冒泡,勾选不会顺带触发 `onClick`。`trailing` 内的动作按钮同样必须自行阻止冒泡。`selected` 渲染 `aria-selected` 并同时改变底色与标题色,选中态不只靠颜色承载。
802
+
803
+ **禁止 / 使用边界。**
804
+ - 不得用本组件手工拼搭菜单、选择器或表格行 —— 那几类组件都是数据驱动的,手搭会造成同一形态两套实现。
805
+ - 不得在静态行上挂 `onClick` 只为取得 hover 底色 —— 静态行出现底色会被误读为可操作。
806
+ - 不得指望 `title` 或 `description` 承载多行正文,两者均单行省略。
807
+ - 禁止用 `selected` 表达多选勾选状态,多选由 `leading` 内的 `ListSelectionCheckbox` 承载。
808
+
809
+ ## Resizable
810
+
811
+ **用途。** 带可拖拽分隔条的双栏布局,支撑 SPLIT 工作面的裸分栏能力。
812
+
813
+ **何时使用。** 页面确实需要用户自行调整两栏宽度时使用。左栏默认 360px,与 SPLIT 左栏的已登记宽度一致;未显式设置时最小 240px、最大 720px。分隔条支持指针拖拽与方向键调整,方向键步长 16px,按住 Shift 为 64px,Home 与 End 直接落到 `min` 与 `max`。
814
+
815
+ **何时改用其他组件。**
816
+ - 需要的是已登记的 SPLIT 结构(目录搜索、定位器、目录设置)—— 改用 `ApplicationSplitListSidebar`,本组件只是裸的分栏器。
817
+ - 需要的是 Canvas 内的垂直导航面 —— 改用 `Sidebar`。
818
+ - 需要的是三栏工作台 —— 改用 `ContactsCollaborationWorkspace`、`FilesCollaborationWorkspace`、`ScheduleCollaborationWorkspace`,三栏外壳已在这三者中收敛。
819
+ - 两栏宽度固定、用户无需调整 —— 不使用本组件,直接由页面布局承担。
820
+
821
+ **组合约定。** 本组件不持有外边距,与相邻区块的间隙由父级负责。`size` 与 `defaultSize` 二选一:给了 `size` 即进入受控模式,此时必须同时提供 `onSizeChange`,否则分隔条拖不动。`min` 与 `max` 应成对给出,且必须落在调用方界面真实可用的范围内 —— 组件会把宽度钳制在这两个值之间。两个栏位均裁剪溢出,因此需要滚动的内容必须自带有界滚动容器(`ScrollArea` 或 `MessageScroller`),不得指望栏位自己滚。分隔条是 5px 宽的命中区并带焦点环,其两侧不得再叠加其他绝对定位元素。
822
+
823
+ **禁止 / 使用边界。**
824
+ - 不得让拖动分栏改变 `pageMode` —— 它只是布局调整,与页面模式无关。
825
+ - 禁止靠嵌套本组件拼出三栏或更多栏,三栏形态由三个协作工作台组件承担。
826
+ - 不得把 `min` 设为 0 制造「可完全折叠」的栏 —— 折叠语义不属于本组件。
827
+ - 不得在分隔条上叠加自定义拖拽逻辑,指针捕获与键盘调整已由组件持有。
828
+
829
+ ## ScrollArea
830
+
831
+ **用途。** 有界滚动区域,带细样式滚动条,用于正交方向或局部有界的溢出。
832
+
833
+ **何时使用。** 内容在某一个方向上必然溢出、且该溢出必须被约束在区域内时使用。合法场景是水平方向的溢出(必须单行的标签条、筛选条),以及给定了明确高度的局部列表。垂直方向使用时必须给出 `height` 或 `maxHeight`,否则区域不构成「有界」,本组件也就失去存在理由。
834
+
835
+ **何时改用其他组件。**
836
+ - 滚动的是消息流 —— 改用 `MessageScroller`,它是消息流已登记的有界滚动容器并自带贴底行为。
837
+ - 溢出的是表格的横向内容 —— 不使用本组件,`Table` 自身已持有横向滚动。
838
+ - 需要的是固定比例的槽位而非滚动 —— 改用 `AspectRatio`。
839
+ - 页面主体内容超出视口 —— 不使用本组件,Content Canvas 是页面唯一的垂直滚动持有者。
840
+
841
+ **组合约定。** `height` 与 `maxHeight` 传数字时按 px 解释;两者可同时缺省,但缺省的垂直 ScrollArea 等于没有约束。`horizontal` 为 true 时垂直方向为 `hidden` —— 单个 ScrollArea 只承担一个方向,需要两个方向必须重新设计布局而不是嵌套两层。本组件不持有内边距与外边距,内容的留白由被包裹的内容自身负责。被包裹内容若自带外边距,滚动区末尾会出现视觉上的空白,应改由内容内部处理。
842
+
843
+ **禁止 / 使用边界。**
844
+ - 禁止在 Content Canvas 内堆叠无界的垂直滚动容器 —— Content Canvas 是唯一的垂直滚动权持有者。
845
+ - 不得用本组件包裹 `ApplicationPageLayoutContainer` 或 `ApplicationDataDisplay`,那会制造第二个页面级垂直滚动。
846
+ - 不得在同一个 ScrollArea 上同时开启两个滚动方向。
847
+ - 不得用本组件包裹 `Table` 以求横向滚动 —— 会得到两层横向滚动条。
848
+
849
+ ## Separator
850
+
851
+ **用途。** `--application-divider` 色的 1px 分隔线,承担系统内大量结构划分工作。
852
+
853
+ **何时使用。** 两段内容之间需要一条明确的界线、而又不值得各自成为一张 `Card` 时使用。已登记的典型用途是分隔区域,以及分隔上下文区的页面动作组与 Page Mode Switch。垂直分隔线用于同一行内的功能分组。长列表需要分段标题时,使用带 `label` 的形态,线被文字断开。
854
+
855
+ **何时改用其他组件。**
856
+ - 需要的是把内容划入独立承载面 —— 改用 `Card`,它自带 1px 边框。
857
+ - 需要的是原生 `<hr>` 的语义 —— 系统内一律改用本组件,`<hr>` 带浏览器默认的立体边框与外边距。
858
+ - 需要的是菜单条目之间的分隔 —— 不使用本组件,`DropdownMenu` 的条目数据自带分隔线形态。
859
+ - 需要的是表格行之间的分隔 —— 不使用本组件,`Table` 自带 1px 行分隔线。
860
+
861
+ **组合约定。** 本组件自己持有两侧外边距,默认一档 12px,调用方通过 `spacing` 调整。`spacing` 必须传 token(如 `var(--ds-space-2)`)或数字,不得传字面 px 字符串。因为外边距归本组件所有,相邻元素不得再为分隔线补 margin —— 否则得到双份间距。`orientation` 为 `vertical` 时需要父容器有确定高度,实际做法是把它放进一个 `align-items: stretch` 的 flex 行;父容器高度不确定时垂直线不可见。带 `label` 的形态只用于分段标题,`label` 应是 2–4 字裸名词短语。
862
+
863
+ **禁止 / 使用边界。**
864
+ - 不得用本组件替代 `Card` 的 `footer` 上边框 —— `footer` 已自带上边框与上内边距。
865
+ - 禁止把 Separator 当装饰元素成组使用,它只表达结构划分。
866
+ - 不得在 `Table` 的行之间、`DropdownMenu` 的条目之间手工插入 Separator。
867
+ - 不得给 `spacing` 传字面像素字符串,尺寸一律读 token。
868
+
869
+ ## Table
870
+
871
+ **用途。** DataTable 呈现方式的承载面 —— LIST 页面模式、LEDGER 台账页、SPLIT 右栏共用同一份表。
872
+
873
+ **何时使用。** 数据需要按列对齐、逐列比较、按列排序时,必须使用本组件。它是数据驱动的:列写在 `columns`,行数据写在 `rows`。表头位于 `--application-table-header`,行与行之间用 1px 分隔线而非阴影。密度分 `default` 与 `sm` 两档,只影响单元格内边距。
874
+
875
+ **何时改用其他组件。**
876
+ - 列数过剩、但行仍需扫视 —— 改用 `ApplicationRecordList`,它是非表格形态的结构化列表。
877
+ - 每条记录需要作为磁贴呈现 —— 改用 `Card` 组成的卡片网格。
878
+ - 呈现的是趋势或分布而非逐条记录 —— 改用 `Chart`。
879
+ - 只是一组同构的目录行,无列对齐需求 —— 改用 `Item`。
880
+ - 需要手写 `<table>` / `<tr>` / `<td>` —— 一律改用本组件,手写表格拿不到已登记的表头底色、行分隔线与列宽约定。
881
+
882
+ **组合约定。** 本组件不持有外边距,与相邻区块的间隙由 `ApplicationDataDisplay` 与 `ApplicationPageLayoutContainer` 负责;横向溢出在组件内部消化,外部不得再套横向滚动容器。`selectable` 为 true 时必须同时提供 `selected` 与 `onSelectedChange`,否则勾选框点了没有任何反应;选择框由 `ListSelectionCheckbox` 承担,勾选不会顺带触发 `onRowClick`。任一列设了 `sortable` 时必须同时提供 `sort` 与 `onSortChange`,同列再次点击在 `asc` 与 `desc` 间切换。`rowKey` 必须指向 `rows` 中真实存在且唯一的字段,缺省值是 `id`。每一列都应显式设置 `priority`:`low` 列在 1180px 宽或 720px 高以下整列隐藏,单元格内边距在 1439px 以下先行压缩,顺序即「先压间距,再压列数,再压优先级」。`rows` 为空时必须提供 `empty`,且应当传 `<Empty />`。批量动作条与分页不属于本组件,分别走 `ApplicationDataDisplay` 的 `batchBar` 与 `pagination` 槽位,前者传 `ListBatchActionBar`,后者传 `ListTablePagination`。
883
+
884
+ **禁止 / 使用边界。**
885
+ - 禁止手写 `<tr>` / `<td>` 作为子元素传入 —— 本组件不接受复合子组件,列与行只能来自 `columns` 与 `rows`。
886
+ - 不得把本组件之上的设置按钮写成通用的「视图设置」,当前呈现方式为 DataTable 时该按钮必须写作「列设置」。
887
+ - 不得为 LIST 页面模式与 SPLIT 右栏各写一份近乎相同的表,同一份业务数据只允许一份实现。
888
+ - 不得在单元格内嵌套第二个 `Table`。
889
+ - 不得省略 `priority`,缺省会让窄视口下的降级顺序不可预期。
890
+
891
+ ## Empty
892
+
893
+ **用途。** 结果集或区域的空状态,承载六种系统状态中的 Empty。
894
+
895
+ **何时使用。** 请求成功返回、但当前口径下确实没有数据时使用。文案必须表明是「当前口径下」没有数据,并在权限允许时给出新建、调整筛选或返回的出路。整页空态使用默认形态,面板内嵌使用 `compact`。
896
+
897
+ **何时改用其他组件。**
898
+ - 状态是 Loading —— 改用 `Skeleton`,且骨架必须贴近最终结构;短时的原地等待改用 `Spinner`。
899
+ - 状态是 Error、No Permission 或 Not Found —— 仍可用本组件渲染节点,但文案必须各自独立;`ApplicationDataDisplay` 为这四种状态各留了独立槽位,不得共用同一个节点。
900
+ - 状态是 Partial Failure —— 改用 `Alert`,它就地提示、提供重试,且不阻断主任务。
901
+ - 需要的是不可逆动作的阻塞确认 —— 改用 `AlertDialog`。
902
+
903
+ **组合约定。** `title` 没有默认值,调用方必须自己写出这一句 —— 组件刻意不提供泛化兜底。本组件自带内边距并居中排布,父容器不得再为它补内边距;说明文字限宽 320px,超出部分自动换行。`icon` 应传 `Icon` 组件并取已登记尺寸档,以弱化前景色显示。`action` 只在调用方确有权限创建缺失之物时提供,且按钮文案是 2–4 字裸名词短语(`新建`、`重置`)。用作 `Table` 的 `empty` 或 `ApplicationDataDisplay` 的 `empty` 槽位时,应设 `compact`。
904
+
905
+ **禁止 / 使用边界。**
906
+ - 禁止让 Empty 与 Error、No Permission、Not Found 共用同一句文案 ——「当前口径下无数据」「你没有权限」「未找到该记录」「请求失败」是四句不同的话。
907
+ - 不得写「暂无数据」这类不带口径的泛化措辞。
908
+ - 不得在数据仍在加载时渲染本组件,Loading 有它自己的节点。
909
+ - 禁止在空态中出现 Emoji、插画或装饰图形。
910
+ - 不得在无权限场景下提供 `action` 入口 —— 给不出权限的出路等于制造死路。
911
+
912
+ ## Avatar
913
+
914
+ **用途。** 人员或组织的身份标记,承载头像图片或其文字缩写回退。
915
+
916
+ **何时使用。** 人员选择器、联系人列表、审计轨迹、记录负责人处必须使用该组件表达身份。已登记档位为 24 / 32 / 40px,与控件高度标尺同值,因此该组件与同行的按钮、输入框天然等高。无图片时该组件回退为文字缩写:中文名取首字,拉丁名按空格分词取各词首字母(最多两个)。人员用 `circle`,组织用 `rounded`。
917
+
918
+ **何时改用其他组件。**
919
+ - 应用身份与品牌区不属于本组件,由 `ApplicationPrimaryNavigation` 的 logo 瓦片承担,该瓦片是 8% 强调色混入表面色,绝不是饱和强调色块。
920
+ - 状态或分类标记改用 `Badge`。
921
+ - 纯内容字形改用 `Icon`,字形必须取自已登记清单。
922
+ - 身份加标题加描述构成的整行改用 `Item`,本组件放进它的 `leading` 槽位。
923
+
924
+ **组合约定。** 传 `src` 时必须同时传 `name` —— `name` 同时充当图片替代文本与悬浮提示,缺失即该头像对读屏软件不可读。该组件已自带 `title`,调用方不得再包一层 `Tooltip`(`Tooltip` 的职责是为纯图标控件命名)。外边距由宿主槽位负责:`Item` 的 `leading`、`Message` 的 `avatar`、三栏工作台的成员行;本组件自身不带 margin,也不参与换行。`ContactsCollaborationWorkspace` 与 `PeoplePickerDialog` 的成员行已内置 24px 头像,调用方不再另行渲染。`size` 传任意数字会绕开标尺,仅当确实无法落到 24 / 32 / 40 时使用。同一列表内 `shape` 必须统一。
925
+
926
+ **禁止 / 使用边界。**
927
+ - 不得用 Emoji、系统字体符号或装饰性字形代替头像。
928
+ - 禁止把本组件做成可点击控件;整行可操作时由 `Item` 的 `onClick` 承担。
929
+ - 不得用头像承载在线、逾期一类的业务状态,状态一律交给 `Badge`。
930
+ - 不得在同一列表内混用 `circle` 与 `rounded` 表达「人员 / 组织」以外的区分。
931
+
932
+ ## Badge
933
+
934
+ **用途。** 紧凑的状态或分类标签,20px 高、4px 圆角、12/16 字号。
935
+
936
+ **何时使用。** 列表行、卡片、指标、详情头需要一个短状态词或分类词时,必须使用该组件。`RecordListItem` 与 `WorkspacePerson` 的 `status` 槽位、`Card` 的 `extra` 槽位、`Item` 的 `trailing` 槽位登记的默认内容即为本组件。`tone` 的六档全部来自功能状态色板,一个 tone 在整个产品内只能有一个含义。
937
+
938
+ **何时改用其他组件。**
939
+ - 指标区里的「功能状态 + 计数」改用 `ApplicationMetricStatus`,该卡由圆点、文字、颜色三者共同承载状态。
940
+ - 已生效的筛选条件改用 `ApplicationQueryToolbar` 的 `appliedTags`,它自带逐项移除与重置全部。
941
+ - 需要说明成因并给出重试出路的整段提示改用 `Alert`。
942
+ - 一级导航上的未读提示改用 `ApplicationPrimaryNavigation` 的 `actionBadges` 圆点;消息条目的未读态改用 `Message` 的 `unread`。
943
+ - 键盘按键提示改用 `Kbd`,二者同为 20px 高,语义不同,不得互换。
944
+
945
+ **组合约定。** `tone` 与业务状态的对应关系必须在应用侧集中定义一次,禁止逐页面各写一份。外边距由宿主槽位负责,本组件自身不带 margin 且不换行,内容超长时由宿主决定截断。`variant="outline"` 的边框取 tone 的语义色,而 `warning` 的前景为保证对比度取中性色,这是已裁决的刻意不同构(04 · D3),应用侧不得把前景「修正」回同色系。`children` 必须是 2–4 字裸名词短语。
946
+
947
+ **禁止 / 使用边界。**
948
+ - 不得用图表分类色表达状态 —— 分类色只编码分类。
949
+ - 禁止给本组件绑定点击或做成可移除标签。
950
+ - 不得在不同页面给同一 tone 指派不同含义。
951
+ - 不得用本组件承载多行文字、长句或数值单位说明。
952
+
953
+ ## Bubble
954
+
955
+ **用途。** 会话中的单条消息气泡,按发言人归属左右分侧。
956
+
957
+ **何时使用。** 消息面板、评论流、办理讨论中由「谁说的」驱动阅读的双方对话必须使用该组件。`own` 右对齐并使用强调色实心,`other` 左对齐并使用带边框的表面色。气泡体最大宽度 76%,长词强制换行。
958
+
959
+ **何时改用其他组件。**
960
+ - 活动流、审计流、通知列表的一条改用 `Message`。
961
+ - 目录、选择器、菜单中的通用列表行改用 `Item`。
962
+ - 需要用户确认或提供出路的系统提示改用 `Alert`。
963
+ - 业务记录行改用 `ApplicationRecordList`。
964
+
965
+ **组合约定。** 该组件必须堆叠在 `MessageScroller` 内使用;条目间距由容器承担,本组件自身不带外边距。76% 是相对本组件根宽度计算的,因此 `MessageScroller` 必须是它的直接宽度来源,中间不得再套一层窄容器把气泡挤成竖条。`author` 与 `time` 同行显示在气泡上方;同一发言人的连续多条应只在首条给出 `author`,其余留空。`side` 由业务的发言人身份决定,不得用于视觉交替。
966
+
967
+ **禁止 / 使用边界。**
968
+ - 不得在气泡内嵌套第二个 Bubble,也不得在其中再开滚动容器。
969
+ - 禁止把气泡整体做成导航入口。
970
+ - 不得用气泡承载表格、表单、指标卡等结构化内容。
971
+ - 不得在 `own` 与 `other` 之外发明第三种归属侧。
972
+
973
+ ## Chart
974
+
975
+ **用途。** 折线、面积、柱状三型的示意图基元,用于读趋势形状。
976
+
977
+ **何时使用。** ANALYSIS 分析页、报表摘要,以及关注走势形状而非精确读数的位置,应使用该组件。系列配色按 `series` 的数组顺序取自共享的 20 色分类色板(`hsl(H, 24%, 53%)`,H 每 18 度一步),同亮度设计使整组图表读起来是一家人。该组件是示意图基元,不是精确图表。
978
+
979
+ **何时改用其他组件。**
980
+ - 指标卡内的迷你走势改用 `ApplicationMetricChart`。二者是两个组件:本组件是 Foundation 绘图基元,后者是 Application Module 的只读指标卡,自带卡片壳、指标名与主数值,不得互换。
981
+ - 主数字加拆解改用 `ApplicationMetricPrimarySecondary`;数值加环比改用 `ApplicationMetricTrend`;状态加计数改用 `ApplicationMetricStatus`;确定性进度改用 `Progress`。
982
+ - 需要逐值读数的明细改用 `Table`。
983
+ - 需要坐标轴刻度、交互取值、精确对齐的真实图表时,系统内无对应组件,必须按 02 §9 规则 9 记为规范缺口上报,不得把本基元调准来顶替。
984
+
985
+ **组合约定。** `series` 必填,各系列的 `data` 长度应一致;配色按数组顺序分配,因此跨页面比较同一组数据时系列顺序必须固定,否则同一业务口径会换色。该组件不渲染标题,可访问名称由调用方在根节点以 `aria-label` 给出。作为 Canvas 的 Data Presentation 使用时,图表由 `ApplicationDataDisplay` 承载,其呈现设置按钮属于 `ApplicationQueryToolbar` 且文案必须写作「图表设置」,通用的「视图设置」被明令禁止。Loading / Empty / Error / No Permission / Not Found 五种状态各有各的槽位,全部由 `ApplicationDataDisplay` 承担,本组件自身不渲染任何状态节点。外边距由宿主区域负责;`height` 只控制绘图区,标签行与图例在其下方另占高度。
986
+
987
+ **禁止 / 使用边界。**
988
+ - 不得用分类色表达状态 —— 红色系列不等于危险,状态一律交给 `Badge` 或 `ApplicationMetricStatus`。
989
+ - 不得把 `labels` 当作与数据点一一对齐的刻度:标签沿轴均分排布,这是已裁决接受的限制(04 · D6)。
990
+ - 禁止依赖柱宽的视觉比例做判断,非等比拉伸会使柱宽随容器宽高比变形。
991
+ - 不得给图表添加图例之外的装饰、渐变或阴影。
992
+
993
+ ## Kbd
994
+
995
+ **用途。** 键盘按键提示,20px 高、等宽字族、浅色底。
996
+
997
+ **何时使用。** 需要告知用户按哪个键时必须使用该组件。因为搜索规定通过 Enter 或明确的搜索动作提交,禁止逐字实时搜索作为默认行为,「按 Enter 提交」类提示在本系统中出现频率最高。原生 `<kbd>` 由 `no-native-kbd` 规则禁止。
998
+
999
+ **何时改用其他组件。**
1000
+ - 菜单条目右侧的快捷键回显改用 `Command` 或 `Menubar` 条目自带的 `shortcut` 字段,那是纯文本,由菜单自身排版承担,不再另套本组件。
1001
+ - 状态词或分类词改用 `Badge`,二者同为 20px 高但语义不同。
1002
+ - 与按键无关的等宽内容不属于本组件,系统内无通用等宽文本组件,须记为规范缺口上报。
1003
+
1004
+ **组合约定。** 该组件内联于宿主文本流中使用 —— `Tooltip` 的 `content`、`Field` 的说明、`Empty` 的 `description`、命令面板的帮助文案;外边距由宿主文本流负责。组合键必须写成多个相邻实例,或在单个实例内写完整组合(如 `⌘K`),同一产品内只取一种写法。单字符按键由 `min-inline-size` 撑成方形,不需要补空格对齐。内容保持按键的字面形式与源大小写(`Enter`、`Esc`、`Shift`)。
1005
+
1006
+ **禁止 / 使用边界。**
1007
+ - 不得用本组件承载状态、计数、标签等非按键内容。
1008
+ - 禁止在本组件上绑定点击 —— 它是提示,真实触发一律交给 `Button`。
1009
+ - 不得在其中写「点击」「请按」一类引导语,按键名裸用。
1010
+ - 不得为本组件另行指定字族,等宽字族已由组件固定。
1011
+
1012
+ ## Message
1013
+
1014
+ **用途。** 消息流或活动流中的一条,含来源方、时间、正文与未读态。
1015
+
1016
+ **何时使用。** 「消息」全局动作面板的行、活动流与审计流的条目必须使用该组件。结构固定为头像槽位加作者与时间行加正文。未读态是淡强调色洗加 6px 圆点,圆点是颜色之外的第二信号。
1017
+
1018
+ **何时改用其他组件。**
1019
+ - 双方对话的气泡改用 `Bubble`。
1020
+ - 目录、选择器、菜单中的通用列表行改用 `Item`。
1021
+ - 业务记录行改用 `ApplicationRecordList`;表格行改用 `Table`。
1022
+ - 需要说明成因并提供重试出路的整段提示改用 `Alert`。
1023
+
1024
+ **组合约定。** `avatar` 槽位应传 `Avatar`。一组本组件作为 `ApplicationGlobalActionPanel` 的 `children` 传入,该面板是消息、待办、运行总览、风险预警四个全局动作共享的同一个面板,绝不为每个动作单独造一个弹层。行内边距由本组件自身承担,条目之间不得再加外边距,间距由容器的排列负责。`unread` 为 true 时淡色底与圆点必须同时出现,不得只保留其一。`author` 为 14/20,`time` 为 12/16,二者按基线对齐,因此传入内容应是短文本,不得塞入块级结构。无条目时的空态由 `ApplicationGlobalActionPanel` 的 `emptyState` 承担,应传 `Empty`,其文案须区别于无权限与加载失败。
1025
+
1026
+ **禁止 / 使用边界。**
1027
+ - 不得把本组件当作会话气泡使用。
1028
+ - 禁止只把文字变色来表达未读。
1029
+ - 不得在本组件内嵌套 `MessageScroller` 或任何滚动容器。
1030
+ - 不得让本组件承担批量选择、行内编辑等表格行职责。
1031
+
1032
+ ## MessageScroller
1033
+
1034
+ **用途。** 消息流的有界滚动容器,并按条件贴底。
1035
+
1036
+ **何时使用。** 需要在 Content Canvas 内部开一块有界的、正交的垂直滚动区域时使用该组件 —— 消息面板、评论流、办理讨论。这是 Content Canvas 单一垂直滚动权的合法局部例外,前提是高度有界。
1037
+
1038
+ **何时改用其他组件。**
1039
+ - 长筛选列表、宽表格、必须单行的标签条等通用溢出改用 `ScrollArea`,单个实例只承担一个滚动方向。
1040
+ - 页面级垂直滚动不需要组件,Content Canvas 本身是唯一的主垂直滚动权持有者。
1041
+ - 靠翻页而非滚动浏览的长列表改用 `ApplicationDataDisplay` 配 `ListTablePagination`。
1042
+
1043
+ **组合约定。** `height` 必须显式给出(数字按 px),否则失去「有界」前提;内置的 320px 只是兜底默认值,不是可依赖的版式。`children` 是一组 `Bubble` 或一组 `Message`,条目间距由本容器承担,条目自身不得再加外边距。`stickToBottom` 仅在用户当前已贴近底部(48px 阈值内)时生效(04 · D7),业务侧不得另写「新消息到达即拉到底」的逻辑把它覆盖回去。该组件持有交互状态并带 `"use client"`,在 Server Component 中只能作为子树引入。滚动监听(加载更多历史)挂在透传的 `onScroll` 上,不得另行注册事件监听器。
1044
+
1045
+ **禁止 / 使用边界。**
1046
+ - 不得省略高度,也不得把它挂进本身高度不定的父容器再靠百分比撑开。
1047
+ - 禁止在本容器内嵌套第二个垂直滚动容器。
1048
+ - 不得把本组件用作页面主滚动区。
1049
+ - 不得在其中混排指标卡、表格、表单等非会话内容。
1050
+
1051
+ ## Progress
1052
+
1053
+ **用途。** 确定性进度条,表达分子分母均已知的完成度。
1054
+
1055
+ **何时使用。** 承载 `progress` 指标语义、批处理任务状态、配额使用率时必须使用该组件。原生 `<progress>` 由 `no-native-progress` 规则禁止。该组件只做确定性进度。
1056
+
1057
+ **何时改用其他组件。**
1058
+ - 不确定时长的原地等待改用 `Spinner`,如刷新中的按钮、提交中的对话框。
1059
+ - 结构性加载改用 `Skeleton`。
1060
+ - 可拖拽取值的输入改用 `Slider`,原生 `<input type="range">` 由 `no-native-range` 规则禁止。
1061
+ - 功能状态加计数改用 `ApplicationMetricStatus`;数值加环比改用 `ApplicationMetricTrend`。
1062
+
1063
+ **组合约定。** 百分比由 `value` 与 `max` 得出并钳制在 0–100,`max` 缺省为 100,因此直接传百分比时不必再给 `max`。指标区内使用时,该组件作为 `ApplicationMetricStrip` 的 `children` 之一传入,卡片壳由指标区提供,本组件自身不带卡片;指标卡默认只读,整卡不得成为导航入口。`label` 与 `showValue` 共处同一行左右分列,二者都不给时该行不渲染。`tone` 使用状态色时,其含义必须与该状态在全产品内的含义一致。外边距由宿主承担;`height` 只改轨道厚度,不影响说明行。填充过渡受 `prefers-reduced-motion` 约束,业务侧不得另加动画。
1064
+
1065
+ **禁止 / 使用边界。**
1066
+ - 不得用本组件表达不确定的等待,禁止做成来回往复的假进度。
1067
+ - 禁止把本组件当作可拖拽或可点击的取值控件。
1068
+ - 不得在缺少指标名的上下文中省略 `label`,读者不应猜测这是什么的百分比。
1069
+ - 不得用分类色或字面色值覆盖 `tone` 的语义取值。
1070
+
1071
+ ## Skeleton
1072
+
1073
+ **用途。** 加载占位骨架,Loading 系统状态的结构性表达。
1074
+
1075
+ **何时使用。** 区域或列表的结构性加载必须使用该组件,且骨架必须贴近最终结构,数据到达时布局不得跳动。`lines` 大于 1 时末条自动缩短至 64%,模拟段落尾行。
1076
+
1077
+ **何时改用其他组件。**
1078
+ - 短时的原地等待改用 `Spinner`;`SystemButton` 的 `loading` 已内置 `Spinner`,不得在按钮内塞入骨架。
1079
+ - 确定性进度改用 `Progress`。
1080
+ - 加载完成但结果为空改用 `Empty`,其文案必须点明是当前口径下无数据。
1081
+ - 加载失败改用 `Alert`,或 `ApplicationDataDisplay` 的 `error` 槽位。
1082
+ - 无权限与未找到各有各的槽位与措辞,绝不用骨架代替。
1083
+
1084
+ **组合约定。** 在 Canvas 内该组件应作为 `ApplicationDataDisplay` 的 `loading` 槽位传入,与 `empty` / `error` / `noPermission` / `notFound` 各自独立,六种状态绝不共用同一句话或同一个节点。骨架的条数、宽度、高度、圆角应按目标结构逐处给出:表格骨架按列宽排布,卡片骨架按卡片网格排布,`radius` 应传 token 而非字面值。该组件自带 `aria-hidden`,读屏软件不朗读骨架,因此加载中的可访问性播报必须由外层容器承担。动画在全局样式表中只有一份 keyframes,并受 `prefers-reduced-motion` 约束,业务侧不得再注入 keyframes 或覆盖该动画。
1085
+
1086
+ **禁止 / 使用边界。**
1087
+ - 不得用一个通用色块糊弄整个区域。
1088
+ - 禁止用骨架表达空态、无权限、未找到或加载失败。
1089
+ - 不得在骨架内放置真实文字、数值或图标 —— 该节点对读屏软件不可见。
1090
+ - 不得让骨架尺寸偏离真实内容而在数据到达时造成布局跳动。
1091
+
1092
+ ## Alert
1093
+
1094
+ **用途。** 就地的、不打断的区域内消息,承载 Partial Failure 系统状态 —— 局部失败、缓存数据提示、权限说明。
1095
+
1096
+ **何时使用。** 当失败或提示是局部的、用户仍能完成主任务时,该组件是默认选择。提交失败、部分成功、数据口径受限这三类信息必须就地呈现在受影响区域的顶部。`tone` 决定色条、淡底与状态图标三者,四个语义色调之间不得靠调用方自行区分。用户必须读到并可能需要采取行动的内容,一律走本组件而非转瞬即逝的提示。
1097
+
1098
+ **何时改用其他组件。**
1099
+ - 转瞬即逝的操作确认(已保存、已导出)改用 `Sonner`。
1100
+ - 不可逆动作前的阻塞确认改用 `AlertDialog`。
1101
+ - 整个区域或结果集无数据改用 `Empty`,其文案须区别于无权限与加载失败。
1102
+ - 结构性加载占位改用 `Skeleton`,短时原地等待改用 `Spinner`。
1103
+
1104
+ **组合约定。** 该组件无开合状态,由调用方条件渲染。`action` 槽位应传单个 `Button`,文案为 2–4 字裸名词短语(`重试`)。状态图标由 `tone` 推导,不接受外部传入的图标。`tone="danger"` 时该组件以 `role="alert"` 打断式播报,其余三个 tone 为 `role="status"`,调用方不得再手动覆盖 `role`。该组件不带外边距,与相邻内容的间距由父容器的 `gap` 负责。`ApplicationFormDialog` 的 `error` 槽位必须传 `<Alert tone="danger">`,渲染在表单主体顶部。
1105
+
1106
+ **禁止 / 使用边界。**
1107
+ - 不得用本组件承载必须阻断的确认,那是 `AlertDialog` 的职责。
1108
+ - 禁止 Loading / Empty / Error / No Permission / Not Found / Partial Failure 六种状态共用同一句文案。
1109
+ - 不得在本组件内嵌套第二个 `Alert`,也不得嵌套任何浮层。
1110
+ - 不得把提交级失败放进 `Sonner`,该类失败一律用本组件呈现在主体顶部。
1111
+
1112
+ ## AlertDialog
1113
+
1114
+ **用途。** 后果严重或不可逆动作前的阻塞式确认 —— 删除、撤回、批量办结。
1115
+
1116
+ **何时使用。** 当动作不可撤销、或影响多个对象时,该组件是唯一合规的确认载体。`title` 必须写明后果与受影响对象的数量(`删除 3 条记录?`),泛化的「确认删除?」不合规。`confirmText` 必须是具体动词(`删除`、`撤回`),不得留用默认的「确定」。不可逆动作为 destructive 时须同时传 `destructive`,确认按钮转为 danger 色。
1117
+
1118
+ **何时改用其他组件。**
1119
+ - 需要用户填写内容的一律改用 `Dialog`;完整业务表单改用 `ApplicationFormDialog`。
1120
+ - 可撤销的已完成事实改用 `Sonner`,并把撤销放进它的 `action`。
1121
+ - 不阻断主任务的失败提示改用 `Alert`。
1122
+
1123
+ **组合约定。** 该组件宽度固定为 420px,不接受尺寸调整。点击遮罩不关闭 —— 破坏性确认必须是显式选择;Esc 仍然可用,等同于取消,不会误触发确认。`onCancel` 同时承担取消按钮、右上角关闭按钮与 Esc 三条路径,缺省它会使该组件无法关闭。`cancelText` 同时作为右上角关闭按钮的无障碍名称,因此必须是 2–4 字裸名词短语,不得写成句子。确认与取消按钮由该组件内部渲染,调用方不得再在 `children` 中放置一组按钮;`children` 只用于列出受影响对象。
1124
+
1125
+ **禁止 / 使用边界。**
1126
+ - 不得在 `children` 中放置输入控件或表单字段。
1127
+ - 禁止把标题写成不含数量与后果的泛化问句。
1128
+ - 不得在本组件之上再叠加第二层模态浮层。
1129
+ - 不得依赖点击遮罩关闭,该路径已按契约关闭。
1130
+
1131
+ ## Collapsible
1132
+
1133
+ **用途。** 单个显隐区域,由一个触发器控制 —— 查询工具栏里的「更多筛选」模式。
1134
+
1135
+ **何时使用。** 当低频能力需要收进入口、但能力本身必须保留时,该组件是默认选择。查询工具栏内常驻 2–3 个高频筛选维度,其余维度一律收进本组件。触发器文字通过 `label` 传入,写作 2–4 字裸名词短语(`更多筛选`)。
1136
+
1137
+ **何时改用其他组件。**
1138
+ - 多个并列或互斥的折叠区改用 `Accordion`。
1139
+ - 页面级的区域切换改用 `Tabs`。
1140
+ - 需要锚定浮出而非就地展开的「更多筛选」改用 `Popover`,两者都可填入 `ApplicationQueryToolbar` 的 `moreFilters` 槽位。
1141
+ - 辅助性内容的侧滑面板改用 `Sheet`。
1142
+
1143
+ **组合约定。** 折叠只改变入口,绝不移除能力 —— 被收起的筛选项仍然存在、仍可使用,调用方不得在收起时把它们从状态中移除。「更多筛选」通过「应用」提交,生效的条件必须回写到 `ApplicationQueryToolbar` 第三行的筛选标签行。受控模式下 `open` 与 `onOpenChange` 必须成对出现,只传 `open` 会得到一个永不展开的区域。内容区的上边距由该组件自身声明,调用方不得再叠加外边距。触发器沿用 32px 高度与 16px 圆角的按钮几何,但它不是 `Button`,不接受 `variant` 一类的按钮属性。
1144
+
1145
+ **禁止 / 使用边界。**
1146
+ - 不得用本组件承载多个并列折叠区,那是 `Accordion` 的职责。
1147
+ - 禁止在折叠收起时清空或禁用其中的筛选条件。
1148
+ - 不得把本组件用作页面级区域切换。
1149
+ - 不得嵌套本组件超过一层。
1150
+
1151
+ ## Dialog
1152
+
1153
+ **用途。** 模态容器,用于用户必须完成或放弃的聚焦任务 —— 新建、编辑、导入映射。
1154
+
1155
+ **何时使用。** 当任务需要用户在离开前完成或明确放弃、且不适合占用整页时,该组件是默认的物理容器。已登记宽度为 `small` 720px、`large` 960px;`size` 也接受任意数字,但无论取值如何都受 `max-width: 100%` 与视口边距约束。命令面板(`Command`)作为全局搜索与执行入口时放进本组件。
1156
+
1157
+ **何时改用其他组件。**
1158
+ - 完整业务表单改用 `ApplicationFormDialog`,它拥有已登记的字段网格与提交语义。
1159
+ - 不可逆动作的确认改用 `AlertDialog`。
1160
+ - 业务对象详情改用 `Drawer` 或独立详情页。
1161
+ - 辅助性内容(设置、帮助、附件预览)改用 `Sheet`。
1162
+ - 无需阻断背景的锚定面板改用 `Popover`。
1163
+
1164
+ **组合约定。** 该组件与 `AlertDialog`、`Drawer`、`Sheet` 共用同一个模态基座,因此自带遮罩、Esc 关闭、焦点陷阱、关闭后焦点恢复与背景滚动锁定,调用方不得再自行实现这五件事,也不得自行设置 `z-index`。`onClose` 同时承担遮罩点击与关闭按钮两条路径。`footer` 右对齐,取消在左、主操作在右,其中至多一个 `Button` 用 `variant="primary"`。主体区域内部滚动而标题与页脚固定,调用方不得在 `children` 外层再套一个滚动容器。`open` 为 false 时该组件渲染 null,内部状态随之丢失 —— 需要保留草稿的调用方必须自行持有该状态。
1165
+
1166
+ **禁止 / 使用边界。**
1167
+ - 不得在本组件内改变 `pageType` 或 `pageMode` —— 浮层只是物理容器,绝不创造新的页面类型或页面模式。
1168
+ - 禁止在本组件内嵌套第二个模态浮层。
1169
+ - 不得为完整业务表单手工拼装本组件的字段布局。
1170
+ - 不得传入使面板超出有效视口的宽度。
1171
+
1172
+ ## Drawer
1173
+
1174
+ **用途。** 侧边面板,保持列表上下文可见 —— DETAIL 的抽屉形态。
1175
+
1176
+ **何时使用。** 当用户需要查看或处理单条记录、同时身后的列表上下文必须保持可见时,该组件是默认选择。推荐宽度 680px,底部动作区固定不随内容滚动。`side` 的 `right` 与 `left` 两个方向均实际生效。
1177
+
1178
+ **何时改用其他组件。**
1179
+ - 已登记的业务详情结构改用 `ApplicationDetailDrawer`,其主体须传 `ApplicationRecordDetailBody`。
1180
+ - 辅助性内容(帮助、附件预览)改用 `Sheet`,它在结构上更轻,不承载业务记录。全局设置是例外,它由 `ApplicationPrimaryNavigation` 的 settings 动作以 `kind='drawer'` 打开,本组件与 `Sheet` 均可承载。
1181
+ - 需要用户完成或放弃的聚焦任务改用 `Dialog`。
1182
+ - 需要深链接指向的详情改用独立详情页,不得用抽屉承接。
1183
+
1184
+ **组合约定。** 抽屉说「关闭」,独立详情页说「返回」—— 这不是文案偏好,是结构区分:深链接永远只指向独立详情页。关闭时必须还原来源页面的筛选条件、分页位置、页面模式、当前对象与滚动位置,这五项由调用方在 `onClose` 中完成,该组件只保证不替调用方跳转。标题栏高度对齐内容区标题栏,因此抽屉打开时上沿与页面结构齐平。`footer` 固定在底部,右对齐;主体区域内部滚动,调用方不得再套滚动容器。
1185
+
1186
+ **禁止 / 使用边界。**
1187
+ - 不得把深链接指向抽屉状态。
1188
+ - 禁止把关闭动作的文案写成「返回」。
1189
+ - 不得在抽屉内再打开第二个抽屉或对话框。
1190
+ - 不得承载帮助、附件预览一类辅助性面板 —— 那些走 `Sheet`;全局设置是唯一例外,它由 `ApplicationPrimaryNavigation` 的 settings 动作以 `kind='drawer'` 打开。
1191
+
1192
+ ## DropdownMenu
1193
+
1194
+ **用途。** 触发器加菜单面板,低频动作的收纳处 —— 上下文区或行尾的「更多」按钮。
1195
+
1196
+ **何时使用。** 当一组低频动作需要收进单一入口、且每一项都是一次性动作而非取值时,该组件是默认选择。行尾动作用 `align="end"`,左侧触发器用 `align="start"`。条目支持前置图标、禁用、危险色、分隔线与分组标题五种形态。
1197
+
1198
+ **何时改用其他组件。**
1199
+ - 内容区域上的右键加速器改用 `ContextMenu`,且它绝不能是某个动作的唯一入口。
1200
+ - 编辑器型工作面的水平菜单条改用 `Menubar`,且只能位于 Content Canvas 内部。
1201
+ - 表单或筛选行中的取值选择改用 `Select`;需要输入筛选改用 `Combobox`。
1202
+ - 查询工具栏中的筛选维度改用 `ApplicationFilterMenu`。
1203
+ - 面板内需要放置任意内容而非条目清单时改用 `Popover`。
1204
+
1205
+ **组合约定。** `trigger` 通常是 `iconOnly` 的 `Button`,此时必须同时提供 `aria-label`。该组件向 `trigger` 注入 `aria-expanded` 与 `aria-haspopup`,因此 `trigger` 必须是单个能接收这两个属性的 React 元素;传入纯字符串时属性不会注入,读屏用户无从得知此处有菜单。`separator` 与 `heading` 条目不需要 `value`,其余每个条目的 `value` 必填 —— 缺失时该条目不可选中且不触发 `onSelect`。面板与条目样式与 `ContextMenu`、`Menubar`、`Command` 共用同一套,最小宽度 168px。
1206
+
1207
+ **禁止 / 使用边界。**
1208
+ - 不得把 Page Mode Switch 折叠进本组件 —— 它必须始终可见,这是 Shell 契约的硬性要求。
1209
+ - 禁止把页面主操作或常驻的 2–3 个高频筛选收进菜单。
1210
+ - 不得给 `separator` 或 `heading` 条目传 `value` 并期望它可点击。
1211
+ - 不得在菜单条目内放置输入框、复选框或其他需要持有状态的控件。
1212
+
1213
+ ## HoverCard
1214
+
1215
+ **用途。** 悬停时展示的富预览 —— 人员、机构、关联记录。
1216
+
1217
+ **何时使用。** 当额外信息能加速判断、但缺少它不影响任务完成时,该组件是默认选择。默认宽度 280px,默认延迟 220ms,用于避免指针划过时闪烁。密集列表中应提高延迟而非降低。
1218
+
1219
+ **何时改用其他组件。**
1220
+ - 为纯图标控件命名改用 `Tooltip`。
1221
+ - 需要在面板内执行动作或提交内容改用 `Popover`。
1222
+ - 完整的记录详情改用 `Drawer` 或独立详情页。
1223
+
1224
+ **组合约定。** 该组件永远只是补充。悬停对键盘用户与触屏用户不可用,因此同样的信息必须能通过点击或详情视图获得 —— 这条由调用方保证,组件本身无法约束。`content` 只放只读预览,动作入口留在行尾或详情中。`trigger` 应是行内元素,该组件的锚点包装为 `inline-flex`,不改变所在文本行的排版。宽度由 `width` 控制,超出高度时面板内部滚动。
1225
+
1226
+ **禁止 / 使用边界。**
1227
+ - 不得让本组件成为某项信息的唯一入口。
1228
+ - 禁止在 `content` 内放置按钮、输入框或任何需要点击的控件。
1229
+ - 不得用本组件替代 `Tooltip` 为图标按钮命名。
1230
+ - 不得在触屏优先的界面上依赖本组件传达必要信息。
1231
+
1232
+ ## Popover
1233
+
1234
+ **用途。** 锚定式浮层面板 —— 筛选器、呈现设置、日期选择器。
1235
+
1236
+ **何时使用。** 当面板内容需要贴近触发器、且背景仍应保持可交互时,该组件是默认选择。默认宽度 320px,空间不足时自动翻转到对侧并限制高度,永不超出有效视口。呈现设置面板必须按当前呈现方式命名 —— 列设置 / 卡片设置 / 看板设置 / 日历设置 / 图表设置 / 时间轴设置。
1237
+
1238
+ **何时改用其他组件。**
1239
+ - 条目清单式的低频动作改用 `DropdownMenu`。
1240
+ - 表单与筛选行中的取值改用 `Select`,需要输入筛选改用 `Combobox`。
1241
+ - 查询工具栏的筛选维度改用 `ApplicationFilterMenu`。
1242
+ - 消息 / 待办 / 运行总览 / 风险预警四个全局动作共享的弹层改用 `ApplicationGlobalActionPanel`,其 720px 宽、20px 圆角、680px 最高的几何已登记。
1243
+ - 用户必须完成或放弃的任务改用 `Dialog`。
1244
+
1245
+ **组合约定。** 该组件是非模态浮层:不锁背景滚动、不陷阱焦点,Esc 与外部点击都会关闭并触发 `onOpenChange`。受控模式下 `open` 与 `onOpenChange` 必须成对出现。触发器包装元素已带 `aria-expanded`,调用方不得在 `trigger` 上再写一个。`radius` 应传 token 而非字面值。作为「更多筛选」入口时,生效条件必须回写到 `ApplicationQueryToolbar` 第三行的筛选标签行。层级由已登记的浮层 z-index 承担,调用方不得自行设置。
1246
+
1247
+ **禁止 / 使用边界。**
1248
+ - 不得用本组件手工拼装四个全局动作的共享弹层。
1249
+ - 禁止在呈现设置面板内改变搜索、筛选、业务视图或页面模式 —— 它只调整当前呈现方式的展示细节。
1250
+ - 不得把呈现设置按钮命名为通用的「视图设置」。
1251
+ - 不得在本组件内嵌套第二个浮层或模态对话框。
1252
+
1253
+ ## Sheet
1254
+
1255
+ **用途。** 从任意边缘滑出的面板,用于辅助性内容 —— 从一级导航打开的「设置」面板、帮助面板、附件预览。
1256
+
1257
+ **何时使用。** 当内容是全局性的辅助配置或参考信息、不属于任何一条业务记录时,该组件是默认选择。四个 `side` 方向均实际生效:左右向时 `size` 为宽度,上下向时为高度,正交方向一律铺满。默认尺寸 420px。
1258
+
1259
+ **何时改用其他组件。**
1260
+ - 业务对象详情改用 `Drawer`(680px)或独立详情页 —— 本组件在结构上比抽屉更轻,不承载业务记录。
1261
+ - 已登记的业务详情结构改用 `ApplicationDetailDrawer`。
1262
+ - 需要用户完成或放弃的聚焦任务改用 `Dialog`。
1263
+ - 消息 / 待办 / 运行总览 / 风险预警四个全局动作改用 `ApplicationGlobalActionPanel`;设置不走该面板,走本组件或 `Drawer`。
1264
+
1265
+ **组合约定。** 该组件与 `Dialog`、`AlertDialog`、`Drawer` 共用同一个模态基座,因此自带 Esc 关闭、焦点陷阱、焦点恢复与背景滚动锁定。该组件没有固定底部动作区 —— 需要提交按钮常驻底部的载体改用 `Drawer`。主体区域内部滚动,标题栏高度对齐内容区标题栏。全局设置在整个产品中只能有一个入口,该入口打开本组件或 `Drawer`,不得同时存在第二处。
1266
+
1267
+ **禁止 / 使用边界。**
1268
+ - 不得用本组件承载业务对象详情。
1269
+ - 禁止在本组件内放置需要固定在底部的提交动作。
1270
+ - 不得为「设置」建立第二个入口。
1271
+ - 不得在本组件之上再叠加抽屉或对话框。
1272
+
1273
+ ## Sonner
1274
+
1275
+ **用途。** 转瞬即逝的提示堆栈,用于确认某件事已经发生 —— 已保存、已导出、3 条已办结。
1276
+
1277
+ **何时使用。** 当结果是已完成的事实、用户无需据此采取任何行动时,该组件是默认选择。判据是单一的:如果用户错过了这条提示会有损失,它就不该是 toast。`title` 应是已完成事实的陈述。未指定 `duration` 时单条停留 5000ms,指针停在堆栈上时暂停计时。
1278
+
1279
+ **何时改用其他组件。**
1280
+ - 用户必须读到并处理的失败改用 `Alert`,就地呈现在受影响区域顶部。
1281
+ - 需要用户确认的不可逆动作改用 `AlertDialog`。
1282
+ - 需要用户填写或选择的内容改用 `Dialog`。
1283
+ - 结果集为空改用 `Empty`。
1284
+
1285
+ **组合约定。** 整个应用只挂一个本组件,位置固定在应用根,`position` 决定四个角中的一个,默认 `bottom-right`。`toasts` 由调用方持有并维护;`onDismiss` 必须真的把该 `id` 从数组中移除,否则计时到期后提示不会消失。`action` 只放可选的加速器(`撤销`),错过它不得造成损失。`SonnerToast.id` 必须稳定唯一,复用同一个 id 会使计时错乱。四个 `tone` 决定左侧色条,单条宽度约束在 280–420px。
1286
+
1287
+ **禁止 / 使用边界。**
1288
+ - 不得用 toast 承载提交失败或任何用户必须处理的信息。
1289
+ - 禁止在同一页面挂载第二个本组件实例。
1290
+ - 不得把 `duration` 设为 0 使提示常驻 —— 不会自己消失的提示不是 toast。
1291
+ - 不得在单条提示内放置表单、多步动作或需要滚动的内容。
1292
+
1293
+ ## Spinner
1294
+
1295
+ **用途。** 不确定时长的原地等待 —— 刷新中的按钮、提交中的对话框。
1296
+
1297
+ **何时使用。** 当等待发生在单个控件或很小的局部、且时长不可预知时,该组件是默认选择。默认尺寸 16px,与按钮内图标同档。`label` 为 12/16 label 色的伴随文字,写作 2–4 字裸名词短语(`加载中`)。
1298
+
1299
+ **何时改用其他组件。**
1300
+ - Loading 系统状态改用 `Skeleton`,且骨架必须贴近最终结构,使数据到达时布局不跳动。
1301
+ - 确定进度的等待改用 `Progress`。
1302
+ - 需要说明失败原因的等待结果改用 `Alert`。
1303
+
1304
+ **组合约定。** 该组件自带 `role="status"` 与 `aria-live="polite"`,调用方不得在其外层再套一个播报容器。`SystemButton` 的 `loading` 已内含行内转圈,不得在其内再放一个本组件。尺寸应与所在控件的图标尺寸一致 —— 按钮内取 16px。旋转动画由全局样式表提供单一份 keyframes,并在系统开启减少动效偏好时自动停止,调用方不得自行注入动画定义。该组件不带外边距,与相邻文字的间距由其自身的行内间隙负责。
1305
+
1306
+ **禁止 / 使用边界。**
1307
+ - 不得用本组件承载 Loading 系统状态。
1308
+ - 禁止用本组件表示确定的进度。
1309
+ - 不得在整页或整个区域中央只放一个本组件充当加载态。
1310
+ - 不得在同一个控件内叠加两个转圈指示。
1311
+
1312
+ ## Tooltip
1313
+
1314
+ **用途。** 悬停或聚焦时出现的短标签,用于为纯图标控件命名 —— 五个全局动作触发器、工具栏图标按钮。
1315
+
1316
+ **何时使用。** 当控件没有可见文字、需要一个名称时,该组件是默认选择。28px 高、8px 圆角、背景为 92% 文字色。显示延迟 220ms,避免在密集工具栏上划过时连闪一串;悬停与聚焦两种方式都会触发。
1317
+
1318
+ **何时改用其他组件。**
1319
+ - 富预览内容改用 `HoverCard`。
1320
+ - 需要在面板内执行动作改用 `Popover`。
1321
+ - 需要长期可见的说明改用 `Field` 的说明文字或 `Alert`。
1322
+
1323
+ **组合约定。** 工具提示不是可访问名称 —— 被提示的控件必须同时带真实的 `aria-label`,纯图标 `Button`(`iconOnly` 为 true)尤其如此,且两者文案应一致。`content` 是控件的名称而非操作说明,写作 2–4 字裸名词短语(`列设置`、`关闭`)。`children` 应是单个可聚焦控件;该组件的锚点包装为 `inline-flex`,不改变所在行的排版。提示面板不接收指针事件,因此它绝不会挡住刚刚触发它的按钮,但也意味着其中的任何内容都不可点击。
1324
+
1325
+ **禁止 / 使用边界。**
1326
+ - 不得用本组件替代控件自身的 `aria-label`。
1327
+ - 禁止在 `content` 内放置链接、按钮或任何需要点击的内容。
1328
+ - 不得用本组件承载多行说明、帮助文本或错误原因。
1329
+ - 不得给已有可见文字的按钮再挂一个重复其文字的工具提示。
1330
+
1331
+ ## ApplicationFilterMenu
1332
+
1333
+ **用途。** 查询工具栏主控制行中的常驻快捷筛选触发器,承载**一个**高频筛选维度的取值。
1334
+
1335
+ **何时使用。** 该维度在结果集上高频使用、取值为短词且数量有限时,必须选用本组件。面板已登记 180px 最小宽与 280px 最高,取值控制在 8 项以内方能一屏读完。工具栏内至多常驻 2–3 个,其余维度一律下沉到「更多筛选」。触发器高 32px、圆角 16px,与同排的 `SearchField` 读作一行。
1336
+
1337
+ **何时改用其他组件。**
1338
+ - 低频维度、或需要一次性提交多个维度:改用 `ApplicationFilterList`,它是「更多筛选」的面板主体,持有草稿并由「应用」提交。
1339
+ - 表单中等待提交的选择数据:改用 `Select`。
1340
+ - 选项极多、或密集的表格行内编辑器:改用 `NativeSelect`。
1341
+ - 需要输入即筛选:改用 `Combobox`。
1342
+ - 局部显示选择(密度、对齐方式、局部视图标记):改用 `ToggleGroup`。
1343
+ - 键盘优先的全局搜索与执行:改用 `Command`,且必须放进 `Dialog`。
1344
+
1345
+ **组合约定。** 该组件必须作为 `ApplicationQueryToolbar` 的 `commonFilters` 内容出现,传 2–3 个;不得独立散落在页面其他位置。该组件只持有本维度的取值,已生效条件必须由调用方回写到 `ApplicationQueryToolbar` 的 `appliedTags`,并实现 `onRemoveTag` 与 `onResetTags`;筛选状态只存在于菜单内部是不合规的。`ApplicationFilterOption.label` 传入非字符串时,必须同时提供 `labelText`,否则触发器回显退化为 `[object Object]`。`multiple` 为 true 时 `value` 与 `defaultValue` 必须是数组,为 false 时必须是字符串;单选状态下再次点选当前值会清空该维度,`onValueChange` 必须能接收空字符串。面板自带定位、碰撞翻转与外点击关闭,调用方不得再包一层 `Popover` 或 `DropdownMenu`。`count` 必须与数据展示区当前口径下的结果数一致。该组件不自带外边距,横向间距由工具栏的 `--ui-control-gap` 负责。
1346
+
1347
+ **禁止 / 使用边界。**
1348
+ - 不得在一个查询工具栏内常驻超过 3 个筛选菜单。
1349
+ - 禁止让已生效的筛选条件停留在菜单内部而不回写筛选标签行。
1350
+ - 不得放进 `ApplicationPageHeader` —— 上下文区禁止出现搜索、筛选、排序。
1351
+ - 不得用它切换 `pageMode` 或 `dataPresentation`,这两者各有专属控件。
1352
+ - 不得覆盖触发器的高度、圆角与已生效态的三重信号(描边、淡底、回显)。
1353
+
1354
+ ## ListSelectionCheckbox
1355
+
1356
+ **用途。** 结果集内的记录选择框,拥有选择语义,并承载表头的 mixed(半选)态。
1357
+
1358
+ **何时使用。** 列表、表格、卡片网格与看板中的记录选择必须使用本组件。表头的「全选」框用 `scope="all"`,单条记录用 `scope="row"`,二者决定无障碍名称。该组件自带 Space / Enter 触发与 `role="checkbox"`,禁用时移出 tab 顺序,调用方无须补键盘处理。
1359
+
1360
+ **何时改用其他组件。**
1361
+ - 表单中等待提交的独立布尔数据:改用 `Checkbox`。
1362
+ - 立即生效的设置(列可见性、通知开关、密度):改用 `Switch`。
1363
+ - 结果集本身由 `Table` 或 `ApplicationRecordList` 渲染:改用它们的 `selectable` 与 `selected` / `onSelectedChange`,二者内部已经渲染本组件。
1364
+
1365
+ **组合约定。** 该组件阻止点击冒泡,勾选永远不会顺带打开该行;调用方不得依赖冒泡触发 `onRowClick` 或 `onOpen`,也不必再自行调用 stopPropagation。勾选后必须唤出 `ListBatchActionBar`,并放进 `ApplicationDataDisplay` 的 `batchBar` 槽位;`count` 为 0 时该条自行渲染 null,调用方不得额外加条件包裹。`indeterminate` 仅供表头使用,优先级高于 `checked`,其取值必须由「部分行已选」实时派生,不得作为第三种业务值持久化。方框视觉与 Foundation `Checkbox` 同源,调用方不得覆盖边框、底色与指示符字形。该组件不自带外边距,选择列的列宽与对齐由 `Table` 或 `ApplicationRecordList` 负责。
1366
+
1367
+ **禁止 / 使用边界。**
1368
+ - 不得在 `Table` 或 `ApplicationRecordList` 的行内额外手工渲染一个选择框。
1369
+ - 禁止用于表单中的布尔字段。
1370
+ - 不得在 `scope="row"` 上设置 `indeterminate`。
1371
+ - 不得为了打开详情而移除它的冒泡拦截。
1372
+
1373
+ ## ListTablePagination
1374
+
1375
+ **用途。** 数据展示区的标准页脚 —— 结果区间、结果总数、每页条数与翻页步进。
1376
+
1377
+ **何时使用。** 结果集同时具备总数与每页条数需求时必须使用本组件,它是 LIST 页面模式的默认配置。形态固定为「第 X–Y 条 / 共 Z 条」加每页条数选择器加上一页 / 位置 / 下一页三件。每页条数默认档为 20 / 50 / 100,业务确有别的档位时通过 `pageSizeOptions` 覆盖。
1378
+
1379
+ **何时改用其他组件。**
1380
+ - 既无总数也无每页条数需求:改用 `Pagination`,它是裸页码步进器,带首页 + 当前页 ±1 + 末页的页码窗口。
1381
+ - 两者是替代关系而非包含关系:同一个数据展示区内只能出现其中一个。
1382
+
1383
+ **组合约定。** 该组件必须放进 `ApplicationDataDisplay` 的 `pagination` 槽位,固定在区域底部;该槽位不随 `state` 隐藏,因此 `state` 不为 `ready` 时调用方不得传入分页。分页语义必须跨 `pageMode` 与 `businessView` 切换存活,从详情返回时也必须还原 —— 该组件是全受控的,这份状态由调用方持有。`onPageSizeChange` 之后通常应重置到第 1 页,调用方必须显式再调一次 `onPageChange`,组件不代劳。`total` 与 `ApplicationQueryToolbar` 的 `resultSummary` 必须取自同一口径的同一个数,否则页脚与摘要会互相打脸。每页条数选择器内部已复用 `NativeSelect`,调用方不得在旁边再挂一个 `Select`。该组件不自带外边距,与上方结果集的间距由数据展示区负责。
1384
+
1385
+ **禁止 / 使用边界。**
1386
+ - 不得在同一数据展示区内出现两处分页控件。
1387
+ - 禁止把分页放进 `ApplicationPageHeader` 或 `ApplicationQueryToolbar`。
1388
+ - 不得在 `loading` / `empty` / `error` / `no-permission` / `not-found` 状态下继续渲染分页。
1389
+ - 不得自造「加载更多」或无限滚动替代分页 —— 系统内没有对应组件。
1390
+
1391
+ ## SearchField
1392
+
1393
+ **用途。** 产品内每一处纯文本搜索的共享紧凑入口,32px 最小高度、16px 圆角,焦点只在外壳表达一次。
1394
+
1395
+ **何时使用。** 查询工具栏、目录搜索、人员与文件选择器中的文本搜索必须使用本组件。该组件只在 Enter 时提交,规范禁止逐字实时搜索作为默认行为。该组件刻意没有形态变体 —— 全产品只有这一种紧凑工具栏形态。
1396
+
1397
+ **何时改用其他组件。**
1398
+ - 普通单行文本录入:改用 `Input`。
1399
+ - 带前后缀或附加按钮的组合输入:改用 `InputGroup`;它是本组件适配的 Foundation 基座,页面不得把它的外壳复制一份充当搜索框。
1400
+ - 在已知选项集合内做本地筛选、且不构成一次数据查询:改用 `Combobox`。
1401
+ - 键盘优先的全局搜索与命令执行:改用 `Command`,放进 `Dialog`。
1402
+
1403
+ **组合约定。** `ariaLabel` 是必填项,且必须写明搜索范围(如「搜索监管对象」),不得写成泛泛的「搜索」。`onSubmit` 仅在 Enter 时触发,调用方不得在 `onChange` 里发起查询 —— `onChange` 只用于受控回显。清除按钮同样触发 `onChange`,其事件对象只保证 `target.value` 一个字段,处理函数不得访问其他事件属性。`ApplicationQueryToolbar` 内部已经渲染了一个 `SearchField`,工具栏场景必须走 `searchValue` / `onSearchChange` / `onSearchSubmit` / `searchPlaceholder`,不得再往 `commonFilters` 或 `moreFilters` 里塞第二个;`PeoplePickerDialog` 同理,其搜索由组件自身持有。`ApplicationFilterList` 的 `search` 槽位应当传入本组件。需要提示提交方式时,配一个 `Kbd` 写「Enter」。调用方拥有搜索范围、提交时机与查询数据;布局宽度可以设,颜色、边框、圆角、背景与焦点视觉不得覆盖。该组件不自带外边距。
1404
+
1405
+ **禁止 / 使用边界。**
1406
+ - 不得把逐字输入直接接到查询上,实时搜索禁止作为默认行为。
1407
+ - 不得省略 `ariaLabel`,也不得把它写成不含范围的「搜索」。
1408
+ - 禁止用 `Input` 或 `InputGroup` 自行拼装搜索外壳。
1409
+ - 不得在一个数据控制区内出现两个搜索框。
1410
+ - 不得为它增加可展开 / 可折叠的形态或尺寸变体。
1411
+
1412
+ ## SidebarAppLinkButton
1413
+
1414
+ **用途。** 应用快捷入口 —— 从工作台侧栏或应用切换器跳转到**另一个应用**。
1415
+
1416
+ **何时使用。** 目标是另一个应用、且需要同时呈现应用名与说明时,必须使用本组件。名称 14/20,说明 12/16 label 色,两行均超长省略。图标块是 28px 圆角方块,内含 18px 字形,底色为 8% 强调色混入表面色的淡底。
1417
+
1418
+ **何时改用其他组件。**
1419
+ - 同一应用内的模块切换:改用 `ApplicationModuleSwitcher`,它是应用二级导航的左半部分。
1420
+ - 工作台菜单栏的图标条目:改用 `SidebarRailButton`。
1421
+ - Content Canvas 内部的垂直导航面(SPLIT 左侧目录、设置导航、模块子导航):改用 `Sidebar`。
1422
+ - 通用的「前置槽位 · 标题 + 描述 · 尾部槽位」列表行:改用 `Item`。
1423
+ - 触发的是动作而非跳转:改用 `SystemButton`。
1424
+
1425
+ **组合约定。** 该组件铺满容器宽度,容器负责列宽、内边距与条目之间的间距,该组件不自带外边距;容器必须给出确定宽度,`name` 与 `description` 的省略号依赖它,不得让内容撑开父级。`glyph` 必须是 18px 档的 `Icon` 或等价字形节点,且必须置于组件自带的方块内,调用方不得自行包一层带背景的容器。`description` 可省略,省略时组件只渲染单行名称;mock 文案登记为「应用说明信息」。跳转路由由调用方在 `onClick` 中完成,该组件不含任何导航逻辑。原生 `name` 属性已被 Omit,该组件不参与表单提交。
1426
+
1427
+ **禁止 / 使用边界。**
1428
+ - 不得省略 `name` —— 无名称的应用入口不可识别。
1429
+ - 禁止在应用字形后面放一个完全饱和的强调色块。
1430
+ - 不得用于应用内部的模块或页面导航。
1431
+ - 不得在其内部再嵌套按钮或链接,该组件本身即是一个按钮。
1432
+
1433
+ ## SidebarRailButton
1434
+
1435
+ **用途。** 工作台菜单栏条目 —— 56px 宽的列内,图标在上、标签在下。
1436
+
1437
+ **何时使用。** 工作台左侧图标栏的导航条目必须使用本组件。图标登记尺寸 20px,标签 12/16 且限宽 52px、超长省略,激活态是淡强调色洗并渲染 `aria-current="page"`。
1438
+
1439
+ **何时改用其他组件。**
1440
+ - 该栏整体由 `GlobalSidebar` 渲染:改为向 `GlobalSidebar` 的 `items` 传数据(`icon` / `label` / `badge` / `separator`),本组件由它在内部渲染。
1441
+ - 跨应用的快捷入口:改用 `SidebarAppLinkButton`。
1442
+ - Content Canvas 内部的通用垂直导航:改用 `Sidebar`,其折叠态即是 56px 图标栏。
1443
+ - Shell 的四带导航:改用 `TopNavigationPrimaryBar`、`ApplicationPrimaryNavigation`、`ApplicationSecondaryNavigation`、`ApplicationModuleSwitcher`。
1444
+
1445
+ **组合约定。** `label` 不可省略 —— 规范禁止纯图标导航项。图标与标签是一个交互单元,禁用或淡化必须作用于整个条目。同一栏内至多一个条目设 `active`。`badge` 只承载未读计数或极短文本,长文案会溢出 14px 高的药丸。标签必须是 2–4 字裸名词短语,超出即被截断。分隔线通过 `GlobalSidebarEntry.separator` 表达,调用方不得在 `items` 之间手工插入 `Separator`。直接使用本组件时(即不经 `GlobalSidebar`),必须放进 56px 宽的列容器,条目之间的纵向间距由该容器负责,该组件不自带外边距。
1446
+
1447
+ **禁止 / 使用边界。**
1448
+ - 不得省略 `label`,纯图标导航项被规范禁止。
1449
+ - 不得只禁用图标或只淡化标签,二者必须整体一致。
1450
+ - 禁止在 `GlobalSidebar` 的 `items` 之外再向该栏手工插入条目。
1451
+ - 不得把它挪进应用外层 Shell —— Shell 是刻意设计的无侧栏、全宽四带堆叠。
1452
+
1453
+ ## SystemButton
1454
+
1455
+ **用途。** 整个产品的默认动作按钮,是 Foundation `Button` 之上只承载应用意图、loading 与产品状态的薄适配层。
1456
+
1457
+ **何时使用。** 应用层与业务页面中的每一个动作按钮都必须优先使用本组件 —— 应用层存在稳定语义适配器时应优先使用 `SystemButton` 而非 `Button`。改一次应用强调色,全部 `SystemButton` 同时换肤,这个性质正是它存在的理由。该组件绝不重新实现按钮的排版与几何:14/20 字号、32px 高度、16px 圆角全部来自 Foundation `Button`。
1458
+
1459
+ **何时改用其他组件。**
1460
+ - 确无稳定应用语义可用时才降级到 `Button`,这是唯一的降级条件。
1461
+ - 一组相关按钮需要拼接为分段控件或间隔簇:外层用 `ButtonGroup`,组内仍是 `SystemButton`。
1462
+ - 一个局部显示选择(密度、对齐方式、局部视图标记):改用 `ToggleGroup`;单个独立开关改用 `Toggle`。
1463
+ - 立即生效的设置:改用 `Switch`。
1464
+ - 页面模式切换:改用 `ApplicationPageHeader` 的 `pageModes` / `pageMode` / `onPageModeChange`,不得用按钮自造 Page Mode Switch。
1465
+
1466
+ **组合约定。** `intent="icon"` 或 `size="icon"` 时必须提供 `aria-label`,该组件此时映射到 Foundation `Button` 的 `iconOnly`,按钮上没有可见文字。一个动作组内至多一个 `intent="primary"`。`loading` 与 `disabled` 都阻断动作但语义不同:loading 是暂时的且设置 `aria-busy`,等待中的动作必须用 `loading` 表达,不得用 `disabled` 冒充;loading 期间 `children` 必须保持不变,否则按钮宽度会跳动。`intent="destructive"` 只表达外观,破坏性动作仍必须经 `AlertDialog` 确认,批量场景下标题须写明受影响对象的数量。页面级动作放进 `ApplicationPageHeader` 的 `actions`,批量动作放进 `ListBatchActionBar` 的 `actions`,记录级动作放在行尾且必须阻止事件冒泡。该组件不自带外边距,动作之间的间距由 `ButtonGroup` 或容器的 gap 负责。`size="compact"` 当前与 `default` 同为 32px,该值为密度分档预留,不得用它做视觉压缩。换肤只有一个入口 `--ds-color-theme-primary`,覆盖 `--application-accent` 只会改到引用它的那一部分组件。
1467
+
1468
+ **禁止 / 使用边界。**
1469
+ - 不得自建平台级或业务级的按钮变体,逐页 fork 会摧毁统一换肤这个性质。
1470
+ - 不得使用原生 `<button>` 承担动作。
1471
+ - 禁止用 `disabled` 表达加载中,等待状态必须用 `loading`。
1472
+ - 不得省略纯图标按钮的 `aria-label`。
1473
+ - 不得在同一个动作组内出现两个 `intent="primary"`。
1474
+
1475
+ ## TopNavigationPrimaryBar
1476
+
1477
+ **用途。** Shell 第一带 `PLATFORM.TOP_USER_BAR`,承载平台级身份(品牌)与账户入口,跨全部应用与全部页面不变。
1478
+
1479
+ **何时使用。** 一个应用外壳必须且只能渲染一条本组件,作为四带堆叠的最上一层。它表达的是「用户在哪个平台、以什么身份」,与当前打开的是哪个应用、哪个模块、哪个页面全部无关。凡是随应用切换而变化的内容,均不属于本带。
1480
+
1481
+ **何时改用其他组件。**
1482
+ - 应用身份(logo、应用名、应用说明)与五个全局动作:改用 `ApplicationPrimaryNavigation`。
1483
+ - 模块名与业务标签:改用 `ApplicationSecondaryNavigation`。
1484
+ - 页面标题、页面动作、刷新、Page Mode Switch:改用 `ApplicationPageHeader`,它位于 Content Canvas 的上下文区。
1485
+ - 层级回溯路径:改用 `Breadcrumb`,且只能出现在上下文区。
1486
+ - 跨应用跳转的条目:改用 `SidebarAppLinkButton` 渲染在 `onAppSwitch` 打开的面板内。
1487
+
1488
+ **组合约定。** 本带高度由 `--ui-shell-primary-height` 决定(Standard 52px / Compact 44px),只有这两档;调用方不得用 `className` 或行内样式改高。三条导航带的 `position: fixed` 与层级由宿主布局承担,组件本身按普通流元素渲染并输出 `data-shell-slot="top-navigation"` 供布局定位;堆叠总高读 `--ui-shell-application-total-height`,Content Canvas 据此让位。本带自持左右内边距与底部分隔线,宿主不得再加外边距。`brandLogoSrc` 缺省时自动回退到已登记 mock:28×28 纯色块 + 8px 间隙 + `brandName`;提供 `onAccount` 时应一并提供 `accountName`,账户按钮的可访问名与头像首字均取自它。`center` 默认为空,写入内容前必须确认该元素在 Shell 契约中已登记。
1489
+
1490
+ **禁止 / 使用边界。**
1491
+ - 不得在本带内加入搜索框、面包屑、通知铃铛、页面标题、卡片或阴影 —— Shell 契约禁止添加未登记元素。
1492
+ - 禁止在 28×28 纯色块内部再绘制伪 Logo,该色块是占位而非标识。
1493
+ - 不得出现第三种高度,也不得随 Condensed 档改变高度。
1494
+ - 不得在一个页面内渲染第二条本组件,也不得把它嵌进 Content Canvas。
1495
+
1496
+ ## ApplicationPrimaryNavigation
1497
+
1498
+ **用途。** Shell 第二带 `APPLICATION.PRIMARY_NAV`,左侧是当前应用的身份,右侧是五个已登记全局动作的入口。
1499
+
1500
+ **何时使用。** 应用外壳必须在第一带之下渲染一条本组件。它是全局动作(消息、待办、运行总览、风险预警、设置)在整个产品中的唯一入口位置。应用级、跨页面、与当前业务页面无关的动作放在这里;只与当前页面有关的动作一律不放。
1501
+
1502
+ **何时改用其他组件。**
1503
+ - 页面级动作组(新建 / 导入 / 导出 / 更多、刷新):改用 `ApplicationPageHeader` 的动作槽位,按钮用 `SystemButton`。
1504
+ - 搜索、常用筛选、排序、列设置:改用 `ApplicationQueryToolbar`。
1505
+ - 模块切换与业务标签:改用 `ApplicationSecondaryNavigation`。
1506
+ - 前四个动作打开的浮层内容:改用 `ApplicationGlobalActionPanel`;设置打开的浮层:改用 `Drawer` 或 `Sheet`。
1507
+
1508
+ **组合约定。** 五个动作及其顺序(消息 → 待办 → 运行总览 → 风险预警 → 设置)固化在实现内部,不接受外部传入,「已登记」即指此。`onAction` 的第二个参数 `kind` 指明该动作应接哪一类浮层:四个 `popover` 动作必须共用同一个 `ApplicationGlobalActionPanel` 实例,一个面板四套内容;`drawer` 动作接抽屉。`activeAction` 与 `onAction` 必须成对使用,`activeAction` 只对 popover 动作产生 `aria-expanded`。`actionBadges` 的键只能取五个已登记动作键,且它只表达「有未读」而不表达数量。`appGlyph` 取图标 `registry.json` 中已登记的字形名。`compact` 为 true 时仅隐藏 `appDescription`,logo、`appName` 与全部五个动作入口必须保留。本带自持内边距与底部分隔线,宿主不得再加外边距。
1509
+
1510
+ **禁止 / 使用边界。**
1511
+ - 禁止渲染第二个设置入口,无论它出现在本带、账户菜单还是页面内。
1512
+ - 不得增加、删除或重排五个全局动作,也不得把其中任意一个折叠进「更多」。
1513
+ - 不得把 logo 瓦片画成饱和强调色块 —— 它是 8% 强调色混入表面色的淡底。
1514
+ - 不得为每个全局动作各造一个浮层,四个 popover 动作共用同一个面板。
1515
+ - 不得在本带承载页面标题、页面动作或数据控制。
1516
+
1517
+ ## ApplicationSecondaryNavigation
1518
+
1519
+ **用途。** Shell 第三带 `APPLICATION.SECONDARY_NAV`,左侧是完整的模块切换器,右侧是当前模块的业务标签。
1520
+
1521
+ **何时使用。** 应用外壳必须在第二带之下渲染一条本组件。右侧标签表达的是「当前模块内的功能分区」,其集合随模块切换而整体更换。标签数量与内容由模块决定,不由页面决定。
1522
+
1523
+ **何时改用其他组件。**
1524
+ - 页面区域内的局部标签页(详情分节、SPLIT 右栏内容标签):改用 `Tabs`,那里图标是可选的。
1525
+ - 业务视图(`businessView`,如 全部 / 我的责任 / 最近处理):改用 `ApplicationQueryToolbar`。
1526
+ - Page Mode Switch:改用 `ApplicationPageHeader`。
1527
+ - 不强制图标的水平导航基元:改用 `NavigationMenu`。
1528
+ - Content Canvas 内的垂直导航:改用 `Sidebar`。
1529
+
1530
+ **组合约定。** `moduleSwitcher` 槽位只接 `ApplicationModuleSwitcher`,不得传入 `Select`、`DropdownMenu` 或自制触发器。`SecondaryNavTab.icon` 在契约中是必填字段,图标必须来自已登记字形并通过 `Icon` 渲染,且其业务含义在 hover 与 active 下保持不变。`value` 与 `onValueChange` 必须成对使用;`tabs` 非空时 `value` 必须命中其中一项。切换模块时必须同时更换 `tabs` 与 `value`,不得让上一个模块的标签残留。标签行保持单行并横向滚动,滚动条已隐藏,调用方不得在外层再包一层滚动容器。激活态的 2px 下划线由组件绘制,调用方不得通过 `className` 叠加背景或边框。本带自持内边距与底部分隔线,宿主不得再加外边距。
1531
+
1532
+ **禁止 / 使用边界。**
1533
+ - 不得在本带承载 Page Mode、Business View、搜索、筛选、对象动作或页面级主操作。
1534
+ - 禁止纯文字标签,也禁止为适应窄屏而丢弃全部图标。
1535
+ - 不得让标签换行 —— 单行横向滚动是已登记行为。
1536
+ - 不得把激活态改成 pill 背景,激活态是已登记的 2px 下划线。
1537
+ - 禁止在标签文案中使用 `模块1 / 模块2`,标准 mock 文案是 `Tab 1` / `Tab 2`。
1538
+
1539
+ ## ApplicationModuleSwitcher
1540
+
1541
+ **用途。** 应用二级导航的左半部分,指示当前处于哪个模块,并提供切换到其他模块的面板。
1542
+
1543
+ **何时使用。** 应用具备多个模块时,本组件必须作为 `ApplicationSecondaryNavigation` 的 `moduleSwitcher` 出现。即使应用当前只有一个模块,触发器仍必须渲染 —— 它同时承担「你在哪」的指示职责。
1544
+
1545
+ **何时改用其他组件。**
1546
+ - 表单或筛选行中选一个值:改用 `Select`;需要输入过滤时改用 `Combobox`。
1547
+ - 通用的动作菜单:改用 `DropdownMenu`。
1548
+ - 跨应用(而非跨模块)跳转:改用 `TopNavigationPrimaryBar` 的 `onAppSwitch`,条目用 `SidebarAppLinkButton`。
1549
+ - 工作台的图标菜单栏:改用 `GlobalSidebar`;Content Canvas 内的通用垂直导航:改用 `Sidebar`。
1550
+
1551
+ **组合约定。** `open` 与 `onOpenChange` 必须成对提供 —— 触发器点击只调用 `onOpenChange`,不提供该回调时面板永远无法打开。`currentModule` 必须命中 `modules` 中的一项。点击当前模块既不触发 `onSelect` 也不关闭面板;路由计算由调用方在 `onSelect` 中完成,组件不做任何跳转。面板是 `position: fixed`,顶边贴 `--ui-shell-application-total-height`,底边贴视口底,宽 392px 并受视口宽度限制;因此本组件的任何祖先元素都不得设置 `transform`、`filter` 或 `contain`,否则固定定位会改以该祖先为包含块而错位。触发器最小宽 168px、高 40px(Compact 148 / 32),几何由 Shell token 决定,调用方不得改写。`ModuleItem.icon` 与触发器的 `glyph` 均走 `Icon`,`glyph` 的登记尺寸是 18px。
1552
+
1553
+ **禁止 / 使用边界。**
1554
+ - 不得把触发器简化成一个小图标,也不得在窄屏下移除它。
1555
+ - 禁止给面板加圆角、阴影或遮罩 —— 它只有 1px 右边线,是被推开的一块面而非浮起的卡片。
1556
+ - 不得把本组件放到 `ApplicationSecondaryNavigation` 之外的位置。
1557
+ - 不得由本组件承担路由跳转,`onSelect` 只是通知。
1558
+ - 不得用它切换应用、切换页面模式或切换业务视图。
1559
+
1560
+ ## GlobalSidebar
1561
+
1562
+ **用途。** 工作台左侧 72px 图标菜单栏,由 `SidebarRailButton` 构成,位于 Content Canvas 内部。
1563
+
1564
+ **何时使用。** `pageType` 为 `WORKBENCH` 的工作台面需要一列固定的图标入口时使用本组件。它是工作台这一种页面的构件,其存在与否由页面决定,不由应用外壳决定。
1565
+
1566
+ **何时改用其他组件。**
1567
+ - Content Canvas 内的通用垂直导航(SPLIT 左栏目录、设置导航、模块子导航):改用 `Sidebar`。
1568
+ - SPLIT 左栏的记录列表:改用 `ApplicationSplitListSidebar`。
1569
+ - 模块级导航:改用 `ApplicationSecondaryNavigation`。
1570
+ - 编辑器型工作面的水平菜单条:改用 `Menubar`。
1571
+ - 单个图标入口按钮:改用 `SidebarRailButton`;跨应用入口:改用 `SidebarAppLinkButton`。
1572
+
1573
+ **组合约定。** `items` 是数据而非元素 —— 组件内部渲染 `SidebarRailButton` 并自行控制 `active` 与点击,调用方不得先构造好按钮元素再传入。`GlobalSidebarEntry.label` 在类型上可选,在规范上必填:规范禁止纯图标导航项,只给 `icon` 不给 `label` 能通过类型检查但不合规。`icon` 的登记尺寸是 20px,走 `Icon`。`separator` 为 true 时其余字段被忽略,但该条目的 `key` 仍必须在栏内唯一。`value` 与 `onValueChange` 成对使用。`footer` 被推到栏底,与条目之间不需要额外间隔元素。本组件自持内边距与右侧 1px 边线,宿主用 flex 把它与内容区并排即可,不得再加外边距。
1574
+
1575
+ **禁止 / 使用边界。**
1576
+ - 不得把本组件当作应用外壳的全局左栏 —— Shell 是刻意设计的无侧栏、全宽四带堆叠。
1577
+ - 不得给本组件设置 `position: fixed` 或让它跨出 Content Canvas。
1578
+ - 禁止渲染只有图标而没有标签的条目。
1579
+ - 不得用它替代 `Sidebar` 承载带分组标题的多层导航。
1580
+
1581
+ ## ApplicationMetricStrip
1582
+
1583
+ **用途。** Canvas 指标区的容器,同时承载 `numeric` 与 `icon` 两种基础指标语义,并为其他语义的指标卡提供等高排列。
1584
+
1585
+ **何时使用。** 页面存在真实指标、且这些指标是「一眼看完的那几个数」时使用。指标区位于 Canvas 标准区域的第二位 —— 上下文区之后、数据控制之前,且是可选区域。
1586
+
1587
+ **何时改用其他组件。**
1588
+ - 指标超过 6 个,或需要排序、筛选、分页:改用 `Table`。
1589
+ - 需要完整的坐标轴、图例与多系列对比:改用 `Chart`。
1590
+ - 占比、配额使用率、批处理进度:改用 `Progress`。
1591
+ - 行内或表格单元中的状态标签:改用 `Badge`。
1592
+ - 承载业务内容而非数字的卡片:改用 `Card`。
1593
+
1594
+ **组合约定。** 本组件必须放进 `ApplicationPageLayoutContainer` 的 `metrics` 槽位,区域之间的间隙由该容器的 `--ui-section-gap` 负责;卡片之间的间隙由本组件的 `--ui-card-gap` 负责(Standard 12px / Condensed 10px / Compact 8px)。单张指标卡不得自带外边距。`trend` / `status` / `chart` / `primary-secondary` 四种语义的卡片必须作为 `children` 写在本组件内部,与 `metrics` 生成的基础卡共用同一个 grid,等高才能成立;把它们平级另起一行会破坏等高。每区 4–6 张,`columns` 缺省取指标数量、上限 6。`Metric.key` 应显式提供 —— `label` 是 ReactNode,用它作 React key 在传入 JSX 时无效。`Metric.icon` 走 `Icon`,提供后该卡语义从 `numeric` 变为 `icon`。
1595
+
1596
+ **禁止 / 使用边界。**
1597
+ - 不得用占位卡凑数:页面没有真实指标时整个区域不渲染,向 `ApplicationPageLayoutContainer` 传 `metrics={undefined}`。
1598
+ - 不得给指标卡挂点击跳转,整卡默认只读,`cursor: default` 是已登记行为。
1599
+ - 不得一行超过 6 张,也不得让同一区内的卡片高度不一致。
1600
+ - 不得在指标区放置页面动作按钮、搜索框或筛选控件。
1601
+ - 禁止给指标卡加阴影 —— 卡片壳是 16px 圆角 + 1px 边框,无阴影。
1602
+
1603
+ ## ApplicationMetricTrend
1604
+
1605
+ **用途。** `trend` 语义的指标卡:一个数值加上它相对某个对比窗口的变化量。
1606
+
1607
+ **何时使用。** 指标本身的数值之外还需要回答「与上一周期相比变了多少」时使用。变化量必须有明确的对比窗口,否则该指标应退回 `ApplicationMetricStrip` 的 `numeric` 卡。
1608
+
1609
+ **何时改用其他组件。**
1610
+ - 需要看出变化的形状而非单一变化量:改用 `ApplicationMetricChart`。
1611
+ - 变化本身带有好坏判断(逾期、违规、健康度):改用 `ApplicationMetricStatus`。
1612
+ - 需要多系列、多周期的完整趋势分析:改用 `Chart`。
1613
+ - 只有数值没有变化量:改用 `ApplicationMetricStrip` 的 `metrics`。
1614
+
1615
+ **组合约定。** 本卡必须作为 `ApplicationMetricStrip` 的 `children` 渲染,等高与卡间距由容器负责,本卡不得自带外边距。`delta` 与 `period` 必须成对提供 —— 没有对比窗口的变化量没有意义。`direction` 只决定箭头字形(up / down / flat),不影响任何颜色,且必须与 `delta` 的符号一致。变化量使用中性色 `--application-metric-delta`,三个方向共用同一取值,这是有意设计而非遗漏。`unit` 紧随 `value` 渲染,不作用于 `delta`。
1616
+
1617
+ **禁止 / 使用边界。**
1618
+ - 不得把上升画成绿色、下降画成红色 —— 上涨不自动等于好。
1619
+ - 不得对变化量使用功能状态色或图表分类色。
1620
+ - 不得省略 `period`,也不得把对比窗口写进 `delta` 文本里凑数。
1621
+ - 不得让本卡承担点击跳转。
1622
+
1623
+ ## ApplicationMetricStatus
1624
+
1625
+ **用途。** `status` 语义的指标卡:一个功能状态及其计数 —— 逾期数、规则违反数、系统健康度。
1626
+
1627
+ **何时使用。** 指标的读数本身带有好坏判断,需要用功能状态色标注时使用。状态词应当反映业务语境下的具体说法,而不是通用的四个默认词。
1628
+
1629
+ **何时改用其他组件。**
1630
+ - 行内、表格单元或详情头中的紧凑状态标签:改用 `Badge`。
1631
+ - 页面级、需要用户注意并可能附带动作的提示:改用 `Alert`。
1632
+ - 数据区的 Loading / Empty / Error / No Permission / Not Found / Partial Failure 六种状态:改用 `ApplicationDataDisplay`,六种状态各有各的措辞,不得共用。
1633
+ - 变化量中性、不带好坏判断:改用 `ApplicationMetricTrend`。
1634
+
1635
+ **组合约定。** 本卡必须作为 `ApplicationMetricStrip` 的 `children` 渲染,等高与卡间距由容器负责,本卡不得自带外边距。状态由圆点、文字、颜色三者共同承载,缺任何一个都不成立。`status` 取 `normal` / `warning` / `danger` / `info` 四个功能状态之一,其色值由组件从功能状态色板取得。默认状态词是 `正常` / `预警` / `异常` / `提示`;业务语境下应当用 `statusText` 覆盖成具体说法,且覆盖文案须为 2–4 字裸名词短语。`note` 是脚注级补充(如「较昨日 +3」),比 `label` 再淡一档,不得用它承载动作或链接。同一个 `status` 取值在整个产品内只能有一个含义。
1636
+
1637
+ **禁止 / 使用边界。**
1638
+ - 禁止使用图表分类色表达状态 —— 「红色系列」不等于「危险」。
1639
+ - 不得只用颜色区分状态,圆点与文字必须同时存在。
1640
+ - 不得用本卡表达页面级的加载失败或无权限,那是 `ApplicationDataDisplay` 的职责。
1641
+ - 不得让本卡承担点击跳转。
1642
+
1643
+ ## ApplicationMetricChart
1644
+
1645
+ **用途。** `chart` 语义的指标卡:一个数值加上内嵌的迷你走势线。
1646
+
1647
+ **何时使用。** 指标的形状(上升段、回落段、波动)本身构成信息,而读者只需一眼扫过时使用。走势线是示意,不是可读的图表。
1648
+
1649
+ **何时改用其他组件。**
1650
+ - 需要坐标轴、图例、网格或多系列对比:改用 `Chart`;当图表是当前的 `dataPresentation` 时,其设置按钮必须写作「图表设置」。
1651
+ - 只需要一个变化量:改用 `ApplicationMetricTrend`。
1652
+ - 表达占比或完成度:改用 `Progress`。
1653
+ - 无形状信息、只有一个数:改用 `ApplicationMetricStrip` 的 `metrics`。
1654
+
1655
+ **组合约定。** 本卡必须作为 `ApplicationMetricStrip` 的 `children` 渲染,等高与卡间距由容器负责,本卡不得自带外边距。走势图形是 `aria-hidden` 的装饰性 SVG,指标的可读信息必须完整地由 `label` 与 `value` 表达;`data` 与 `value` 必须成对提供。`data` 为空数组时不渲染走势图形,卡片仍保留数值并参与等高。`colorIndex` 索引的是 20 色图表分类色板 `--application-categorical-01…20`,仅编码分类,与好坏无关。绘图区是 88×28px 的版式常量,调用方不得改写。
1656
+
1657
+ **禁止 / 使用边界。**
1658
+ - 不得用本卡替代 `Chart` 承担分析职责,它没有坐标轴、图例与数值刻度。
1659
+ - 禁止给走势线配功能状态色 —— 分类色不表达状态。
1660
+ - 不得给走势线添加 tooltip、hover 高亮或数据点交互,指标卡默认只读。
1661
+ - 不得让本卡承担点击跳转。
1662
+
1663
+ ## ApplicationMetricPrimarySecondary
1664
+
1665
+ **用途。** `primary-secondary` 语义的指标卡:一个主数字,加上它的 2–3 项拆解。
1666
+
1667
+ **何时使用。** 主数字的构成本身需要当场交代,且拆解项少到可以一眼读完时使用。拆解项之间是同一口径的并列关系,不是不同口径的多个指标。
1668
+
1669
+ **何时改用其他组件。**
1670
+ - 拆解项超过 3 个,或需要排序、对齐、分页:改用 `Table`。
1671
+ - 拆解项是详情字段而非数字:改用 `ApplicationRecordDetailBody`。
1672
+ - 只有主数字没有拆解:改用 `ApplicationMetricStrip` 的 `metrics`。
1673
+ - 拆解意在表达占比:改用 `Progress`。
1674
+
1675
+ **组合约定。** 本卡必须作为 `ApplicationMetricStrip` 的 `children` 渲染,等高与卡间距由容器负责,本卡不得自带外边距。`secondary` 控制在 2–3 个,超出即说明该内容应当是一张表。`unit` 只作用于主数值 `value`;次级项如需单位,写进 `SecondaryFigure.value` 内部。次级项的名与值以基线对齐渲染,二者字号相同而颜色不同,调用方不得靠 `className` 把某一项加粗以示强调 —— 强调关系已由主次结构表达。
1676
+
1677
+ **禁止 / 使用边界。**
1678
+ - 不得让 `secondary` 超过 3 项。
1679
+ - 不得用本卡承载明细列表或分页数据。
1680
+ - 不得把次级数字做成链接或按钮,指标卡默认只读。
1681
+ - 不得让本卡承担点击跳转。
1682
+
1683
+ ## ApplicationPageLayoutContainer
1684
+
1685
+ **用途。** Canvas 内每个业务页面的脚手架,把页面组织为固定顺序的四个标准区域:上下文区 → 指标区(可选)→ 数据控制 → 数据展示。
1686
+
1687
+ **何时使用。** 进入 Content Canvas 的每一个业务页面都必须以该组件作为内容根。页面处于 LIST / CARD / SPLIT / BOARD / CALENDAR 中的哪一种页面模式都不改变这一点 —— 页面模式只改变数据展示区的内部构造,不改变外层区域顺序。页面内容根的内边距与区域间隙由它独占。
1688
+
1689
+ **何时改用其他组件。**
1690
+ - Shell 的三条导航带不属于页面内容根,改用 `TopNavigationPrimaryBar`、`ApplicationPrimaryNavigation`、`ApplicationSecondaryNavigation`。
1691
+ - 浮层内部的分区外壳改用 `ApplicationFormDialog`、`ApplicationDetailDrawer`、`Dialog`、`Drawer`,四者各自持有自己的外壳留白。
1692
+ - 只需要一个带边框的内容面板时改用 `Card`。
1693
+ - SPLIT 的两栏切分改用 `Resizable`,它落在该组件的数据展示区之内,不替代该组件。
1694
+
1695
+ **组合约定。**
1696
+ - 四个槽位与 Canvas 五层模型逐一对应:`header` 承载上下文区,`metrics` 承载指标区,`dataControl` 承载 L3 业务视图与 L4 数据控制,`children` 承载 L5 数据呈现。
1697
+ - `header` 应传 `ApplicationPageHeader`,`metrics` 应传 `ApplicationMetricStrip`,`dataControl` 应传 `ApplicationQueryToolbar`,`children` 应传 `ApplicationDataDisplay`。
1698
+ - 区域顺序由槽位固定,不由调用方书写次序决定:把上下文区传进 `metrics` 不会让它落到指标区的位置上。
1699
+ - 外边距归属唯一:Content Canvas 宿主内边距为零,页面内边距与区域间隙(Standard 12px / Condensed 10px / Compact 8px)全部由该组件持有。四个区域自身不得再带外边距。
1700
+ - 密度三档由 `--ui-page-gutter` 与 `--ui-section-gap` 在 `:root` 层改写,调用方不得为此写任何断点。
1701
+ - 页面没有真实指标时 `metrics` 整体省略。
1702
+ - SPLIT 模式下,左栏 `ApplicationSplitListSidebar` 与右栏成对落在数据展示区内,由 `Resizable` 或等效两栏容器承载。
1703
+
1704
+ **禁止 / 使用边界。**
1705
+ - 不得调整四个区域的顺序,也不得新增第五个页面级区域。
1706
+ - 不得在该组件外层再包一层带内边距的容器 —— 页面留白只有一个持有者,两边都加会得到双倍留白。
1707
+ - 禁止用占位指标卡凑满 `metrics`,无真实指标时该区域整体不渲染。
1708
+ - 不得在该组件内部再嵌套一个 `ApplicationPageLayoutContainer`。
1709
+ - 禁止在页面内堆叠第二个无界垂直滚动容器 —— Content Canvas 是唯一的垂直滚动持有者。
1710
+
1711
+ ## ApplicationPageHeader
1712
+
1713
+ **用途。** Canvas 的上下文区,承载页面身份、数据新鲜度与页面级 Page Mode Switch。
1714
+
1715
+ **何时使用。** 每个业务页面的第一个区域必须是该组件。页面标题、面包屑、数据状态与刷新、页面级动作组、Page Mode Switch 全部集中在这里,且只有这里。该组件回答的是「这是哪个页面、数据是什么时候的、用哪种模式看」。
1716
+
1717
+ **何时改用其他组件。**
1718
+ - 跨页身份与应用、模块导航属于 Shell,改用 `TopNavigationPrimaryBar`、`ApplicationPrimaryNavigation`、`ApplicationSecondaryNavigation`。
1719
+ - 搜索、常用筛选、排序、呈现设置、SPLIT 右栏的 View Mode Switch 一律改用 `ApplicationQueryToolbar`。
1720
+ - 批量动作改用 `ListBatchActionBar`,它出现在结果集上方而非上下文区。
1721
+ - 记录对象的头部改用 `ApplicationRecordDetailBody` 的 `summary` 与 `ApplicationDetailDrawer` 的标题区。
1722
+ - 面包屑本体用 `Breadcrumb`,经 `breadcrumb` 槽位传入。
1723
+
1724
+ **组合约定。**
1725
+ - `actions` 承载页面级动作组,元素应为 `Button` 或 `SystemButton`,至多一个 primary。中文标签为 2–4 字裸名词短语:`新建`、`导入`、`导出`、`更多`。
1726
+ - Page Mode Switch 由 `pageModes`、`pageMode`、`onPageModeChange` 三者共同驱动,三者必须成组提供;只给 `pageModes` 会得到一个点不动的开关。
1727
+ - `pageModes` 只列该页面真正开放的模式。少于 2 个时开关完全不渲染且不占位。
1728
+ - `dataStatus` 为 `normal` 时应同时提供 `updatedAt`,否则状态区只剩一个刷新按钮,数据新鲜度无从判断。
1729
+ - 三种数据状态各有各的措辞与可用性:`normal` 显示更新时刻,`refreshing` 显示刷新中且刷新按钮禁用,`failed` 显示刷新失败且按钮读作 `重试`。
1730
+ - `title` 为字符串时才会得到悬浮提示。需要悬浮提示又需要补充信息时,标题主体传 `title`,补充信息走 `subtitle`。
1731
+ - 该组件自身不带外边距,与相邻区域的间距由 `ApplicationPageLayoutContainer` 的区域间隙负责。
1732
+ - Page Mode Switch 的选中态与 `ToggleGroup` 同为分段控件表达(选中项抬升为表面色),不得改为淡色洗 —— 淡色洗属于独立开关 `Toggle`。
1733
+
1734
+ **禁止 / 使用边界。**
1735
+ - 不得把搜索框、常用筛选、排序控件或任何呈现设置放进 `actions`。
1736
+ - 禁止把 Page Mode Switch 折叠进「更多」菜单,也不得让它在不同页面模式下改变物理位置。
1737
+ - 不得让刷新重置业务视图、搜索、筛选、排序或页面模式 —— 刷新只更新数据。
1738
+ - 不得在 `actions` 中放置行级动作或批量动作。
1739
+ - 禁止渲染只有一种取值的 Page Mode Switch,也不得为它保留空位。
1740
+
1741
+ ## ApplicationQueryToolbar
1742
+
1743
+ **用途。** 数据控制区,以固定三行统一承载 Canvas 五层模型的 L3 业务视图与 L4 数据控制。
1744
+
1745
+ **何时使用。** 页面存在搜索、筛选、排序或多个业务视图时,必须由该组件承载。同一个结果集只允许有一份该组件。SPLIT 模式下它服务右栏,并且是 `viewModeSwitch` 唯一合法的位置。
1746
+
1747
+ **何时改用其他组件。**
1748
+ - Page Mode Switch 属于 `ApplicationPageHeader`,不得在此重建。
1749
+ - 单个高频筛选维度的触发器改用 `ApplicationFilterMenu`,经 `commonFilters` 传入。
1750
+ - 完整的筛选维度面板改用 `ApplicationFilterList`,装进 `Collapsible` 或 `Popover` 后经 `moreFilters` 传入。
1751
+ - 纯文本搜索输入已由该组件内置的 `SearchField` 承担,不得在工具栏内另置搜索控件。
1752
+ - 分页改用 `ListTablePagination`,它属于 `ApplicationDataDisplay` 的底部。
1753
+ - 批量动作改用 `ListBatchActionBar`。
1754
+
1755
+ **组合约定。**
1756
+ - 三行的渲染条件固定:第一行业务视图仅当确有视图时渲染,第二行恒在,第三行仅当有筛选生效时渲染。
1757
+ - `businessViews` 传 2–4 个稳定工作视角,`businessView` 与 `onBusinessViewChange` 必须成对提供。
1758
+ - 搜索经 `searchValue` 与 `onSearchChange` 受控,提交只经 `onSearchSubmit`,由 Enter 触发。
1759
+ - `commonFilters` 常驻 2–3 个 `ApplicationFilterMenu`,其余维度一律收进 `moreFilters`。折叠只改变入口,不移除能力。
1760
+ - 生效条件必须回写 `appliedTags`,并同时提供 `onRemoveTag` 与 `onResetTags`。`AppliedFilterTag.label` 为非字符串时必须提供 `labelText`,否则移除按钮的无障碍名称为空。
1761
+ - `presentation` 决定呈现设置按钮的文案,必须与 `ApplicationDataDisplay` 的同名 prop 取自同一处状态。
1762
+ - 无真实可配置项时传 `hasPresentationSettings={false}`,按钮不渲染且不占位;提供设置时 `onPresentationSettings` 必须一并给出。
1763
+ - 每种呈现方式各自独立存储其设置,切换呈现方式不得沿用上一种的设置。
1764
+ - `viewModeSwitch` 仅允许出现在服务 SPLIT 右栏的那一份工具栏上,且只改 `dataPresentation`。
1765
+ - 搜索框固定 240px,该组件自身不带外边距,与相邻区域的间距由 `ApplicationPageLayoutContainer` 负责。
1766
+
1767
+ **禁止 / 使用边界。**
1768
+ - 禁止逐字实时搜索,不得在 `onSearchChange` 中直接发起查询。
1769
+ - 禁止出现通用的「视图设置」按钮 —— 按钮必须按当前呈现方式命名:`列设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
1770
+ - 不得在该组件内渲染 Page Mode Switch,也不得用 `viewModeSwitch` 改动 `pageMode`。
1771
+ - 不得让筛选状态只存在于菜单或面板内部而不回写 `appliedTags`。
1772
+ - 禁止为同一个结果集放置两份工具栏,也不得把搜索、筛选、排序下沉进 `ApplicationDataDisplay`。
1773
+
1774
+ ## ApplicationFilterList
1775
+
1776
+ **用途。** 「更多筛选」的面板主体 —— 全量筛选维度列表,持有草稿并由「应用」提交。
1777
+
1778
+ **何时使用。** 页面的可筛选维度多于工具栏能常驻的 2–3 个时使用。它是筛选能力的全集入口,而非常用筛选的补充。每个提供筛选的页面至多一份。
1779
+
1780
+ **何时改用其他组件。**
1781
+ - 常驻在工具栏主控制行的单个高频维度改用 `ApplicationFilterMenu`。
1782
+ - 面板的展开与浮层外壳改用 `Collapsible` 或 `Popover`,该组件只是它们的内容。
1783
+ - 选项极多且需要输入过滤的单个维度改用 `Combobox`;单个选择控件改用 `Select`。
1784
+ - 面板内的搜索框改用 `SearchField`,经 `search` 槽位传入。
1785
+
1786
+ **组合约定。**
1787
+ - 该组件完全受控且不持有内部状态:`values` 是草稿,`onChange` 报告被点击的维度键与取值,草稿的合并由调用方完成。
1788
+ - `FilterGroup.multiple` 为 true 时,调用方必须在 `onChange` 中把该维度的取值合并为数组后写回 `values`;单选维度写回字符串。
1789
+ - `search` 必须提供 —— 全集入口没有搜索时,维度一多就无法定位。
1790
+ - `onApply` 与 `onReset` 必须成对提供。应用之前任何改动都不生效。
1791
+ - 应用后,每一条生效条件必须回写到 `ApplicationQueryToolbar` 的 `appliedTags`,且逐条可移除。
1792
+ - 该组件不自带浮层外壳与关闭行为,关闭时机由承载它的 `Collapsible` 或 `Popover` 决定。
1793
+ - 维度区最高 360px 且自身滚动,搜索与底部动作固定不滚动。调用方不得在外层再加一层滚动容器。
1794
+ - 取值按钮高 28px,比工具栏控件的 32px 矮一档 —— 它们是密集排布的候选项,不是主控制行的控件。
1795
+
1796
+ **禁止 / 使用边界。**
1797
+ - 不得在 `onChange` 中直接提交查询 —— 草稿只有经「应用」才生效。
1798
+ - 禁止把生效的筛选条件只保留在面板内部而不回写筛选标签行。
1799
+ - 不得只放部分维度 —— 该面板必须覆盖每一个可筛选维度,否则它不能被称作「更多筛选」。
1800
+ - 不得用该组件替代工具栏内常驻的 2–3 个常用筛选。
1801
+ - 禁止在该组件内放置排序、呈现设置或页面模式相关的控件。
1802
+
1803
+ ## ApplicationDataDisplay
1804
+
1805
+ **用途。** Canvas 的数据展示区,承载恰好一种 Data Presentation,外加它的选择态、分页与六种系统状态。
1806
+
1807
+ **何时使用。** 页面需要展示结果集时使用。LIST 页面模式与 SPLIT 右栏共用同一个该组件与同一个呈现组件。该区域只负责展示与选择,不负责查询。
1808
+
1809
+ **何时改用其他组件。**
1810
+ - 具体的呈现形态由被承载的组件决定:结构化记录列表用 `ApplicationRecordList`,表格用 `Table`,图表用 `Chart`,日历用 `Calendar`。
1811
+ - 单条记录的详情主体改用 `ApplicationRecordDetailBody`。
1812
+ - 指标概览属于指标区,改用 `ApplicationMetricStrip` 与四个语义指标卡。
1813
+ - 只需要一个带边框的静态面板时改用 `Card`。
1814
+ - 空态、骨架、分页、批量条各有专属组件:`Empty`、`Skeleton`、`ListTablePagination`、`ListBatchActionBar`,它们经槽位传入而非在内部重画。
1815
+
1816
+ **组合约定。**
1817
+ - `state` 为 `ready` 时渲染 `children`,其余五种状态各自渲染对应槽位。使用某个状态前必须提供该状态的节点,否则该区域为空白。
1818
+ - 六种状态的文案必须区分成因:`loading` 传贴近最终结构的 `Skeleton`,`empty` 传 `Empty` 且点明当前口径,`error` 说明失败原因并提供重试,`noPermission` 与 `notFound` 各写各的措辞。
1819
+ - `presentation` 必须与 `ApplicationQueryToolbar` 的同名 prop 取自同一处状态,否则呈现设置按钮会命名错误。
1820
+ - `batchBar` 应传 `ListBatchActionBar`,仅在有记录被选中时才出现;`pagination` 应传 `ListTablePagination`,固定在区域底部。
1821
+ - 展示区自身滚动,批量条与分页固定在上下两端。调用方不得在 `children` 外再包一层滚动容器。
1822
+ - 该组件在列向 flex 中吃掉剩余高度,必须作为 `ApplicationPageLayoutContainer` 的 `children` 使用,否则拿不到剩余高度,内部滚动失效。
1823
+ - 边框、圆角与背景由该组件持有,被承载的呈现组件不得再画一层外框。
1824
+
1825
+ **禁止 / 使用边界。**
1826
+ - 不得在该区域内持有第二套查询状态 —— 搜索、筛选、排序全部属于 `ApplicationQueryToolbar`。
1827
+ - 禁止 Loading / Empty / Error / No Permission / Not Found 共用同一句文案。
1828
+ - 不得为 LIST 页面模式与 SPLIT 右栏各写一份近乎相同的呈现实现。
1829
+ - 不得在一个展示区内同时渲染两种 Data Presentation。
1830
+ - 禁止用通用转圈顶替 `loading` 槽位的结构骨架。
1831
+
1832
+ ## ApplicationSplitListSidebar
1833
+
1834
+ **用途。** SPLIT 页面模式的左栏定位器,承载目录搜索、目录本体与目录设置。
1835
+
1836
+ **何时使用。** 页面模式为 SPLIT,且左栏回答「你在哪」时使用。宽度默认 360px,Compact 档 300px,与 `Resizable` 的默认左栏同值。该组件的职责边界是定位,不是展示结果。
1837
+
1838
+ **何时改用其他组件。**
1839
+ - 跨页与模块级导航改用 `ApplicationSecondaryNavigation`、`GlobalSidebar`、`Sidebar`。
1840
+ - 两栏的切分与拖拽本身改用 `Resizable`,该组件是它的左栏内容。
1841
+ - 右栏的结果集改用 `ApplicationDataDisplay` 与其中的呈现组件。
1842
+ - 目录搜索框改用 `SearchField`,经 `search` 槽位传入。
1843
+ - 需要多级互斥折叠的深层目录改用 `Accordion`。
1844
+
1845
+ **组合约定。**
1846
+ - 该组件受控:`value` 与 `onValueChange` 必须成对提供。
1847
+ - 当前对象的合法取值只有两种:空,或当前结果集中一个有权限的对象。
1848
+ - `SplitSidebarItem.depth` 从 0 起,每级缩进一档。树形目录必须逐项给出 `depth`,否则全部平铺。
1849
+ - `SplitSidebarItem.icon` 应传 `Icon`,字形须在 `src/icon/registry.json` 中登记。
1850
+ - `width` 只在需要覆盖已登记宽度时传;不传则取 `--ui-sidebar-list-width`,三档密度自动生效。
1851
+ - 该组件自身滚动,右侧分隔边框由它持有。调用方不得再加外边距或第二条分隔线。
1852
+ - `settings` 是目录设置,与右栏的呈现设置是两回事,两者不得互相顶替。
1853
+ - 目录项的计数经 `count` 传入,不得拼进 `label`。
1854
+
1855
+ **禁止 / 使用边界。**
1856
+ - 禁止在左栏放置第二个 Page Mode Switch。
1857
+ - 不得在左栏承载右栏的 View Mode Switch 或任何呈现设置。
1858
+ - 不得为了填满右栏而自动选中第一项 —— 空选是完全合法的状态。
1859
+ - 禁止在左栏承载结果集本身、批量动作或分页。
1860
+ - 不得在 SPLIT 以外的页面模式下使用该组件。
1861
+
1862
+ ## ApplicationRecordDetailBody
1863
+
1864
+ **用途。** 唯一的业务详情主体,由抽屉形态与独立详情页共用 ——「一份详情,两个载体」。
1865
+
1866
+ **何时使用。** 展示一条记录的完整字段与分节时使用。抽屉与独立详情页必须共用同一份该组件的装配,两个载体的差异只在外壳。它只读展示,不承载编辑。
1867
+
1868
+ **何时改用其他组件。**
1869
+ - 抽屉外壳改用 `ApplicationDetailDrawer`,该组件作为它的 `children`。
1870
+ - 表单编辑改用 `ApplicationFormDialog` 与 `Field`。
1871
+ - 结果集列表改用 `ApplicationRecordList` 或 `Table`。
1872
+ - 需要折叠的超长分节由 `Collapsible` 或 `Accordion` 承载,经 `DetailSection.content` 传入。
1873
+ - 单个名值对之外的静态面板改用 `Card`。
1874
+
1875
+ **组合约定。**
1876
+ - `summary` 承载对象头:标题、状态徽标(应为 `Badge`)、关键标识。
1877
+ - `sections` 按数组顺序渲染。`DetailSection.title` 为非字符串时必须提供 `key`;契约同样为 `DetailField` 登记了 `key`,`label` 为非字符串时必须提供。
1878
+ - 字段以 `dl` / `dt` / `dd` 输出为名值对,列数随可用宽度自适应,字段列最窄 240px —— 680px 抽屉里排两列,独立详情页全宽下排更多列,两个载体不需要各写一套。
1879
+ - 分节级动作经 `DetailSection.action` 右对齐于标题行;对象级主动作属于载体,写在抽屉右下角的固定动作区。
1880
+ - 时间轴、附件列表等非名值对内容走 `DetailSection.content`,排在字段之后。
1881
+ - 该组件不带外边距也不自持滚动,留白与滚动一律由载体负责。
1882
+ - 允许存在抽屉专用变体的条件是:超过 3 个分节、超过 15 个字段、动作流程有实质差异、性能要求不同,四者任一成立。即便成立,该变体只保留核心内容。
1883
+ - 载体措辞固定:抽屉说 `关闭`,独立详情页说 `返回`,深链接只指向独立详情页。
1884
+
1885
+ **禁止 / 使用边界。**
1886
+ - 不得为抽屉与独立详情页各写一份详情主体。
1887
+ - 禁止把对象级主动作、关闭或返回按钮放进该组件。
1888
+ - 不得在分节顺序可变时省略 `key` —— 重排序会导致内部状态错位。
1889
+ - 禁止在该组件内部再嵌套一个 `ApplicationRecordDetailBody`。
1890
+ - 不得在该组件内承载搜索、筛选、排序或分页。
1891
+
1892
+ ## ApplicationRecordList
1893
+
1894
+ **用途。** 非表格形态的结构化列表,承载业务记录行 —— 每行是「标题 + 元信息 + 状态 + 关键数值 + 行尾动作」这一固定结构。
1895
+
1896
+ **何时使用。** 当记录需要逐行扫视、但表格列数已经过剩时,该页面必须选用本组件而非 `Table`。它同时服务 LIST 页面模式与 SPLIT 右栏,两处必须是同一个实例配置,不得为同一份业务数据写两套近乎相同的实现。行内需要选择集合、需要记录级动作、需要「当前打开对象」高亮时,本组件是默认选择。
1897
+
1898
+ **何时改用其他组件。**
1899
+ - 字段构成稳定、需要列排序与列宽约定的多列比对,改用 `Table`(DataTable 呈现方式)。
1900
+ - 目录、选择器、菜单里的通用行 —— 无选择集合、无记录级动作 —— 改用 `Item`。
1901
+ - CardList 呈现方式的磁贴改用 `Card`。
1902
+ - 消息流与活动流的条目改用 `Message`,会话气泡改用 `Bubble`。
1903
+ - 六种系统状态的承载、批量动作条与分页的挂载,由宿主 `ApplicationDataDisplay` 负责,不在本组件内解决。
1904
+
1905
+ **组合约定。** 本组件必须放进 `ApplicationDataDisplay` 的 `children`,仅在 `state="ready"` 时渲染。外边距由 `ApplicationPageLayoutContainer` 持有(`--ui-page-gutter` 与 `--ui-section-gap`),本组件与其行一律不自带 margin。`selectable` 为 true 时行首由组件自动渲染 `ListSelectionCheckbox`,调用方不得再自行插一个;`selected` 与 `onSelectedChange` 必须成对提供,本组件的选择是受控的。选择集合非空时,调用方必须把 `ListBatchActionBar` 交给 `ApplicationDataDisplay` 的 `batchBar`。`activeId` 与选择集合是两回事:前者是 SPLIT 右栏或抽屉流程中的当前对象,只有一个,视觉上是选中底色;后者是勾选集合,视觉上是 4% 淡洗。`RecordListItem.actions` 由组件包一层并阻止点击冒泡;一旦改用 `renderRow` 接管行主体,阻止冒泡的责任转移给调用方。行高 56px,容得下标题与元信息两行。呈现设置按钮读作「列设置」,且它属于 `ApplicationQueryToolbar`,不属于本组件。
1906
+
1907
+ **禁止 / 使用边界。**
1908
+ - 不得在本组件内持有搜索、筛选、排序状态 —— 那些全部属于 `ApplicationQueryToolbar`,数据展示区绝不持有第二套查询状态。
1909
+ - 不得把右键菜单作为某个记录级动作的唯一入口,该动作必须同时出现在行尾或详情中。
1910
+ - 不得为业务记录另写一套行结构,需要改写行主体时使用 `renderRow`。
1911
+ - 禁止在 `renderRow` 返回的行主体里省略阻止冒泡 —— 点动作绝不能顺带打开详情。
1912
+ - 不得把分页塞进本组件,分页固定在 `ApplicationDataDisplay` 区域底部。
1913
+
1914
+ ## ListBatchActionBar
1915
+
1916
+ **用途。** 当前选择集的批量动作条,紧贴结果集上方,说明「选了多少」并提供作用于这批记录的动作。
1917
+
1918
+ **何时使用。** 凡呈现方式启用了行选择 —— DataTable、结构化列表、卡片网格、看板 —— 该页面必须提供本组件。它由选择集合驱动:`count` 为 0 时整个组件渲染 `null`,不占位、不留空条。跨页选择场景必须同时提供 `hint`,写明作用范围。
1919
+
1920
+ **何时改用其他组件。**
1921
+ - 页面级动作(新建 / 导入 / 导出 / 更多)改用 `ApplicationPageHeader` 的 `actions`。
1922
+ - 单条记录的动作改用 `RecordListItem.actions` 的行尾槽位,或 `ApplicationDetailDrawer` 的 `primaryAction` / `secondaryActions`。
1923
+ - 破坏性批量动作的确认改用 `AlertDialog`,标题中必须写明受影响对象的数量。
1924
+ - 「已办结 3 条」这类事后确认改用 `Sonner`;需要用户处理的局部失败改用 `Alert`。
1925
+
1926
+ **组合约定。** 本组件与 `ListSelectionCheckbox` 成对出现 —— 页面提供了行选择能力就必须提供本组件,反之没有选择能力就不得渲染本组件。挂载位置固定为 `ApplicationDataDisplay` 的 `batchBar` 槽位,外边距由该宿主与 `ApplicationPageLayoutContainer` 负责。`count` 必须由选择集合的长度驱动,不得另设计数状态。`onClear` 必须真正清空选择集合,而不仅仅隐藏动作条。`actions` 内一律传 `Button`,右对齐由组件负责。区带高度 44px,比 32px 的工具栏行高一档 —— 这是区带尺度,不在控件高度标尺(24 / 28 / 32 / 40)上。
1927
+
1928
+ **禁止 / 使用边界。**
1929
+ - 不得把批量动作条放进 Shell 的任何一带 —— 批量动作作用于当前选中的那些行,放远了读者看不出它作用于什么。
1930
+ - 不得把批量动作混进上下文区 `ApplicationPageHeader` 的页面动作组。
1931
+ - 禁止在 `count` 为 0 时渲染一条空动作条或等高占位。
1932
+ - 禁止破坏性批量动作不经 `AlertDialog` 直接执行。
1933
+
1934
+ ## ApplicationFormDialog
1935
+
1936
+ **用途。** 业务对象新建与编辑的模态表单载体,拥有已登记的字段网格与提交 / 取消语义。
1937
+
1938
+ **何时使用。** 用户必须完成或放弃的表单任务一律用本组件。已登记宽度只有 `small` 720px 与 `large` 960px 两档,字段默认排布在两列网格上。提交中由 `submitting` 表达,提交级失败由 `error` 表达。该组件建立在共享 Overlay 基座上,因此自带 Esc 关闭、焦点陷阱、关闭后焦点恢复与背景滚动锁定。
1939
+
1940
+ **何时改用其他组件。**
1941
+ - 不含表单的聚焦任务(导入映射、确认预览)改用 Foundation `Dialog`。
1942
+ - 不可逆动作的确认改用 `AlertDialog` —— 它的遮罩点击不关闭,破坏性确认必须是显式选择。
1943
+ - 人员、组织、审核人、通知接收人的目录式选择改用 `PeoplePickerDialog`。
1944
+ - 只读的业务对象详情改用 `ApplicationDetailDrawer` 或独立详情页。
1945
+ - 设置、帮助、附件预览这类辅助性面板改用 `Sheet`。
1946
+ - 字段规模超出两档宽度可承载的范围时,改用独立编辑页承载。
1947
+
1948
+ **组合约定。** 字段一律以 `Field` 子元素传入 `children`,一个 `Field` 管辖一个控件。需要跨列的字段传 `style={{ gridColumn: '1 / -1' }}`;需要单列或三列时改 `columns`,不要用外部 CSS 重排网格。字段级错误交给 `Field` 的 `error`,并且控件自身的 `invalid` 需另行设置 —— 两者不联动。提交级失败传 `error`,内容应是 `<Alert tone="danger">`,由组件渲染在主体顶部、字段网格之前。`submitting` 为 true 时组件禁用主按钮并置忙态,调用方仍须在自己的提交回调里防止重复请求。底部动作区由组件持有,取消在左、主操作在右,文案经 `submitText` / `cancelText` 覆盖。`onCancel` 同时被取消按钮、Esc 与遮罩点击触发,因此它必须是幂等的。视口边距由 Overlay 基座负责,调用方不得再包一层定位容器。
1949
+
1950
+ **禁止 / 使用边界。**
1951
+ - 不得把提交失败呈现为 `Sonner` —— 用户必须处理的失败绝不能放进转瞬即逝的提示里。
1952
+ - 不得在 `children` 里自行渲染提交与取消按钮,底部动作区由组件持有。
1953
+ - 禁止把宽度改到 720px / 960px 两档之外,也禁止让对话框超出有效视口。
1954
+ - 不得用本组件承载只读详情,详情有它自己的两个载体。
1955
+ - 不得在 `children` 内用内联 style 改写控件自身的边框、高度或圆角。
1956
+
1957
+ ## ApplicationDetailDrawer
1958
+
1959
+ **用途。** DETAIL 的抽屉载体 —— 打开一条业务记录的详情,同时保持身后的列表上下文可见。
1960
+
1961
+ **何时使用。** 从列表打开单条记录且不希望丢失来源上下文时,该页面必须用本组件。推荐宽度 680px,底部动作区固定不随内容滚动。它与独立详情页共用同一个 `ApplicationRecordDetailBody`,是「一份详情,两个载体」中的抽屉那一个。
1962
+
1963
+ **何时改用其他组件。**
1964
+ - 非业务记录的侧边面板、或不需要已登记详情结构的裸抽屉,改用 Foundation `Drawer`。
1965
+ - 设置、帮助、附件预览这类辅助性内容改用 `Sheet` —— 业务对象详情不属于那里。
1966
+ - 需要深链接的详情改用独立详情页,深链接永远只指向独立详情页。
1967
+ - 分节超过 3 个、字段超过 15 个、动作流程有实质差异或性能要求不同时,改用独立详情页承载完整内容;抽屉侧只保留核心内容。
1968
+ - 编辑与新建改用 `ApplicationFormDialog`;不可逆动作的确认改用 `AlertDialog`。
1969
+
1970
+ **组合约定。** `children` 必须传 `ApplicationRecordDetailBody`,不得为抽屉另写一份详情主体。`width` 默认 680px;`--application-drawer-width` 的 1280px 是宽 / 全屏变体,需要时经 `width` 显式传入。`primaryAction` 是唯一的主对象动作,固定在右下角,其余一律进 `secondaryActions`。关闭按钮由组件渲染并写作「关闭」,独立详情页写「返回」—— 这是结构区分,不是文案偏好。`onClose` 里调用方必须还原来源页面的八项上下文:业务视图、搜索、筛选、排序、分页、页面模式、当前对象、滚动位置,少还原任何一项都算缺陷。与列表配合时,来源侧用 `ApplicationRecordList` 的 `activeId` 或 `Table` 的 `onRowClick` 标记当前对象。视口边距、Esc、焦点陷阱、焦点恢复与滚动锁定由 Overlay 基座负责,调用方不得再实现一遍。
1971
+
1972
+ **禁止 / 使用边界。**
1973
+ - 不得让深链接指向抽屉 —— 深链接只指向独立详情页。
1974
+ - 不得为抽屉与独立详情页各写一份详情主体。
1975
+ - 不得在 `onClose` 里做导航跳转 —— 抽屉是叠加层,关闭必须回到来源页面的原状态。
1976
+ - 禁止把关闭按钮的文案写成「返回」,也禁止再加第二个退出入口。
1977
+ - 不得渲染第二个 `primaryAction`,主对象动作唯一。
1978
+
1979
+ ## ApplicationGlobalActionPanel
1980
+
1981
+ **用途。** 消息、待办、运行总览、风险预警这四个 popover 型全局动作共享的同一个面板。
1982
+
1983
+ **何时使用。** 该面板由 `ApplicationPrimaryNavigation` 的右侧动作簇触发,`onAction` 回调的 `kind` 为 `'popover'` 时打开本组件。四个动作复用同一个实例,切换的只是 `title`、`tabs` 与 `children`。它不是模态:背景仍可交互,因此不锁滚动、不陷阱焦点。
1984
+
1985
+ **何时改用其他组件。**
1986
+ - 设置改用 `Drawer` 或 `Sheet` —— `onAction` 对它给出的 `kind` 是 `'drawer'`,它不走本面板。
1987
+ - 页面内的锚定浮层(常用筛选、更多筛选、呈现设置)改用 `Popover`,那是 Canvas 的事。
1988
+ - 必须完成或放弃的聚焦任务改用 `Dialog` 或 `ApplicationFormDialog`。
1989
+ - 业务页面内容一律留在 Canvas,不进入 Shell 层的任何浮层。
1990
+
1991
+ **组合约定。** `open` 与 `title` 必须与 `ApplicationPrimaryNavigation` 的 `activeAction` 同步,四个动作绝不各造一个弹层。`tabs` 传 `GlobalActionTab`(`value` / `label` / `count`),当前项由 `activeTab` 受控、`onTabChange` 回写。`children` 通常是一组 `Message`;条目多到需要独立滚动时用 `MessageScroller` 并给它显式 `height` —— 那是有界的正交滚动区,不得堆叠无界的垂直滚动容器。无条目时传 `emptyState`,内容应是 `Empty`,其文案必须区别于无权限与加载失败。整体性动作(例如「全部标记为已读」)放 `footer`。几何全部由 `--ui-shell-global-action-*` 登记:720px 宽、20px 圆角、680px 最高、16px 视口边距、位于整个 Shell 堆叠之下,调用方不得覆盖。由于本面板非模态,外点击关闭由调用方触发 `onClose`。
1992
+
1993
+ **禁止 / 使用边界。**
1994
+ - 不得为四个全局动作分别造弹层 —— 一个面板,四套内容。
1995
+ - 不得在本面板内渲染设置,也不得在产品内存在第二个设置入口。
1996
+ - 不得把业务页面内容搬进本面板,Shell 不承载业务内容。
1997
+ - 禁止让 Loading、Empty、No Permission、Error 共用 `emptyState` 一句文案。
1998
+ - 不得覆盖已登记的宽度、圆角与最大高度。
1999
+
2000
+ ## PeoplePickerDialog
2001
+
2002
+ **用途。** 人员与组织的选择器 —— 指派人、审核人、通知接收人、共享对象。
2003
+
2004
+ **何时使用。** 一次选择可能很长、且用户需要在确认前审阅已选集合时,该场景必须用本组件:左侧搜索与目录,右侧实时显示已选集合且可逐项移除。搜索同时匹配姓名与所属机构。`multiple` 为 false 时选中即替换,仍须经「确定」提交。
2005
+
2006
+ **何时改用其他组件。**
2007
+ - 单选、选项可在本地筛选、且无须审阅已选集合的,改用 `Combobox`。
2008
+ - 选项固定且数量少的,改用 `Select`;表格行内的密集编辑器改用 `NativeSelect`。
2009
+ - 浏览与管理组织及成员(不是一次性选择)改用 `ContactsCollaborationWorkspace`。
2010
+ - 把人员作为筛选维度使用时改用 `ApplicationFilterMenu`,本组件不承担筛选。
2011
+ - 非人员的通用选择任务改用 `Dialog`。
2012
+
2013
+ **组合约定。** `Person.name` 必须是纯文本 —— 它参与搜索匹配,也用于已选项的移除按钮无障碍名称;`org` 同样参与匹配。`selected` 与 `onSelectedChange` 成对提供,选择受控。搜索框由组件内部以 `SearchField` 渲染,调用方不得再传一个;对应地,本组件没有搜索槽位。已选栏宽 240px,对话框宽度取 720px 一档、高度固定 520px,目录与已选清单各自滚动,人数增减不改变对话框尺寸。`onCancel` 同时被取消按钮、Esc 与遮罩点击触发。作为表单字段的值选择器使用时,触发器与回显由调用方在 `Field` 内提供,本组件只负责选择过程。视口边距、焦点与滚动锁定由 Overlay 基座负责。
2014
+
2015
+ **禁止 / 使用边界。**
2016
+ - 不得把 `Person.name` 传成 JSX —— 那会让该条目搜索不到,也会让移除按钮的无障碍名称失效。
2017
+ - 不得在 `people` 中放入当前用户无权限查看的对象。
2018
+ - 不得用本组件承担筛选,筛选属于 `ApplicationQueryToolbar` 与 `ApplicationFilterMenu`。
2019
+ - 禁止覆盖内部 `SearchField` 的颜色、边框、圆角、背景与焦点视觉。
2020
+ - 不得省略「确定」而在勾选时即刻生效 —— 长选择在提交前必须是可审阅、可撤销的。
2021
+
2022
+ ## ContactsCollaborationWorkspace
2023
+
2024
+ **用途。** 「人员与组织」工作台的整装模块件 —— 组织树定位器、成员列表、成员详情三栏。
2025
+
2026
+ **何时使用。** 通讯录与组织管理页面必须整体复用本组件。三栏的宽度、分界与滚动归属是登记结构的一部分:组织树 280px、成员列表 320px、详情占剩余宽度,三栏各自滚动。详情栏与其他详情载体共用同一份主体。
2027
+
2028
+ **何时改用其他组件。**
2029
+ - 常规业务页面的分栏结构改用 `ApplicationPageLayoutContainer` + `ApplicationSplitListSidebar` + `ApplicationDataDisplay` 组合,那才是 SPLIT 页面模式。
2030
+ - 一次性挑人改用 `PeoplePickerDialog`。
2031
+ - 只需要详情主体本身改用 `ApplicationRecordDetailBody`。
2032
+ - 文件与日程各有自己的工作台:`FilesCollaborationWorkspace`、`ScheduleCollaborationWorkspace`。
2033
+
2034
+ **组合约定。** 本组件是受控的整体结构,整体复用,不得拆开抄进页面。`search` 应传 `SearchField`,其 `ariaLabel` 必填且应写明搜索范围。`orgTree` 复用 `SplitSidebarItem` 的条目结构(`value` / `label` / `icon` / `count` / `depth`),树形缩进走 `depth`,不要另造一套树数据。`detail` 应传 `ApplicationRecordDetailBody`。`activePerson` 为空是完全合法的状态,不得为了填满详情栏而自动选中第一个成员。成员行的头像、姓名、岗位、状态由 `WorkspacePerson` 的四个字段驱动,行本身复用 Foundation `Item`。本组件不设工具栏槽位 —— 页面级动作留在 `ApplicationPageHeader`。外壳的边框、16px 圆角与分栏滚动规则由三个 collaboration 组件共用同一份 CSS,`--mh-contacts-*` 是本组件的局部尺度而非公共接口。
2035
+
2036
+ **禁止 / 使用边界。**
2037
+ - 不得在每个页面重新搭一遍三栏布局 —— 复制出去的外壳会让下一次调整要改多处。
2038
+ - 不得在详情栏另写一份详情主体,抽屉、独立详情页与本工作台共用同一个 `ApplicationRecordDetailBody`。
2039
+ - 不得为了填满详情栏自动选中第一个成员。
2040
+ - 禁止把本组件的外壳类名挪作其他三栏布局使用。
2041
+ - 不得在本组件外再包一层自己的 padding,页面内容根的内边距由 `ApplicationPageLayoutContainer` 持有。
2042
+
2043
+ ## FilesCollaborationWorkspace
2044
+
2045
+ **用途。** 「文件」工作台的整装模块件 —— 文件夹定位器、文件表、可选预览栏。
2046
+
2047
+ **何时使用。** 文件浏览与管理页面必须整体复用本组件。文件表是共享的 `Table`,固定列为名称、所有者、大小、更新时间,四列的列定义与窄视口降级顺序都内建:先压间距,再隐藏优先级为 `low` 的大小与更新时间两列。
2048
+
2049
+ **何时改用其他组件。**
2050
+ - 不需要文件夹定位器与预览栏的纯表格,改用 Foundation `Table`。
2051
+ - 非文件类业务记录改用 `ApplicationRecordList` 或 `Table`。
2052
+ - 附件预览若属于业务详情的一部分,改由 `ApplicationRecordDetailBody` 的分节 `content` 承载。
2053
+ - 人员与日程各有自己的工作台:`ContactsCollaborationWorkspace`、`ScheduleCollaborationWorkspace`。
2054
+
2055
+ **组合约定。** 本组件是整装件,整体复用。`search` 应传 `SearchField`,`folders` 复用 `SplitSidebarItem` 的条目结构。`preview` 仅在确有选中项时传 —— 无选中项时整体省略该槽位,与「无真实指标时不渲染指标区」是同一条原则。`empty` 应传 `Empty`,文案须点明是「此目录下」无文件,且不得与无权限、未找到、加载失败共用措辞。上传、新建文件夹这类目录级动作放 `toolbar`。本组件不设 `batchBar` 槽位,选中文件后的批量动作同样由调用方放进 `toolbar`。行选择由内部 `Table` 承载,`selected` 与 `onSelectedChange` 成对提供;打开文件走 `onOpen`。文件夹树 280px、预览栏 320px,文件表占剩余宽度并独立滚动。
2056
+
2057
+ **禁止 / 使用边界。**
2058
+ - 不得在没有选中项时传 `preview` —— 空的预览栏会白占一栏宽度。
2059
+ - 不得手写文件表或增删四个固定列,列定义内建于本组件。
2060
+ - 不得让空态、无权限与加载失败共用同一句文案。
2061
+ - 禁止在 `toolbar` 里放页面级动作,页面级动作属于 `ApplicationPageHeader`。
2062
+ - 不得拆开外壳单独复用其中一栏。
2063
+
2064
+ ## ScheduleCollaborationWorkspace
2065
+
2066
+ **用途。** 「日程」工作台的整装模块件 —— 粒度切换、月格、当日议程栏。
2067
+
2068
+ **何时使用。** 需要在一个工作台面里同时看到月度分布与当日明细时使用本组件。周一为一周起始。日格最多平铺 2 条事件,其余折成「+N」;格高 76px,议程栏宽 280px。粒度在日、周、月三档之间切换,由 `grain` 与 `onGrainChange` 受控。
2069
+
2070
+ **何时改用其他组件。**
2071
+ - 表单里的日期字段与筛选区间,改用 Foundation `Calendar` 与 `Input` 一起放进 `Popover` —— 那是控件,本组件是工作台面。
2072
+ - 整页的日历承载面改用 `CALENDAR` 页面模式,即 `ApplicationPageHeader` 的 `pageMode` 与 `ApplicationDataDisplay` 的 `presentation="Calendar"` 组合。
2073
+ - 人员与文件各有自己的工作台:`ContactsCollaborationWorkspace`、`FilesCollaborationWorkspace`。
2074
+
2075
+ **组合约定。** 本组件是整装件,整体复用。`month` 是 `Date`,只取年月;`selectedDate` 与 `ScheduleEvent.date` 是 ISO `yyyy-mm-dd` 字符串 —— 它们是标识而非时间点,两者语义不同,不强行统一为同一种类型。事件日期串必须按本地时区生成,与组件内部的日期比较口径一致。`onGrainChange` 回传的是 `ScheduleGrain` 字面量,调用方不得回写其他值。`toolbar` 排在粒度切换之后,属于日程范围内的动作。外壳的边框、16px 圆角与分栏滚动规则与另外两个 collaboration 组件共用同一份 CSS;三者栏数并不相同:本组件是月格与议程栏两栏,`ContactsCollaborationWorkspace` 是三栏,`FilesCollaborationWorkspace` 视 `preview` 有无为两栏或三栏。选用任何日历型承载面之前,调用方必须先命名日期字段与真实的观察粒度。
2076
+
2077
+ **禁止 / 使用边界。**
2078
+ - 不得用本组件替代 `CALENDAR` 页面模式,两者同名不同层。
2079
+ - 不得用 `toISOString().slice(0, 10)` 生成 `ScheduleEvent.date` —— 在 UTC+8 下会整体错一天。
2080
+ - 不得把周日作为一周起始。
2081
+ - 禁止绕开「+N」折叠机制在单个日格内堆入超过 2 条事件。
2082
+ - 不得在缺少日期字段或未确定观察粒度的情况下选用本组件。