@moheng-design/ui-skill 1.0.0 → 3.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.
@@ -1,13 +1,13 @@
1
1
  ---
2
2
  name: moheng-ui
3
- description: 用 @moheng-design/ui 写 React 界面时加载。含 91 个组件的清单与常用 props、原生元素到组件的替换映射表、Application Module 层强绑定的五层 Canvas 模型使用前提,以及样式覆盖、换肤与暗色的正确做法。凡涉及按钮、输入、选择、表格、浮层、导航、页面骨架等任何界面代码,均适用。
3
+ description: 用 @moheng-design/ui 写 React 界面时加载。含 94 个组件的清单与常用 props、原生元素到组件的替换映射表、Application Module 层强绑定的五层 Canvas 模型使用前提,以及样式覆盖、换肤与暗色的正确做法。凡涉及按钮、输入、选择、表格、浮层、导航、页面骨架等任何界面代码,均适用。
4
4
  ---
5
5
 
6
6
  <!-- 生成文件 —— 请勿手改。源:@moheng-design/ui 的 contracts/ 与 mappings.json,生成器:scripts/generate.mjs -->
7
7
 
8
8
  # @moheng-design/ui 使用指南
9
9
 
10
- 适用版本:v1.0.0
10
+ 适用版本:v3.0.0
11
11
 
12
12
  > 请先确认项目 `package.json` 中 `@moheng-design/ui` 的版本与本文件声明一致。
13
13
  > 若不一致,以 `node_modules/@moheng-design/ui-skill/generated/reference.md` 为准 ——
@@ -32,7 +32,8 @@ import '@moheng-design/ui/styles.css'
32
32
  换肤的唯一入口是 `--ds-color-theme-primary`。暗色靠 `.dark` 类。
33
33
 
34
34
  **两者都必须挂在 `<html>` 上。** `--application-*` 别名层整层声明在 `:root`,
35
- `var()` 代换在声明所在元素就完成了,挂在 `<body>` 或容器 div 上一律无效。
35
+ `var()` 代换在声明所在元素就完成了。挂在 `<body>` 或容器 div 上是半生效,比无效更糟:
36
+ 直接读 `--ds-*` 的部件变了,读 `--application-*` 的部件不变,同一屏一半换了一半没换。
36
37
  不存在「局部暗色区块」这种用法。
37
38
 
38
39
  ### 样式覆盖
@@ -45,19 +46,20 @@ import '@moheng-design/ui/styles.css'
45
46
 
46
47
  ### 可用的 token
47
48
 
48
- 组件的全部颜色、尺度与层级由 CSS 自定义属性表达,共 356 条。
49
+ 组件的全部颜色、尺度与层级由 CSS 自定义属性表达,共 389 条。
49
50
  覆盖样式、与组件对齐尺度时读它们,**不得写字面色值、尺寸、圆角、间距**。
50
51
 
51
- 消费方可用的是 `--application-*`(91 条)与 `--ui-*`(134 条),共 225 条。
52
- `--ds-*`(131 条)是 Foundation 内部实现,不构成公开接口,
53
- 任意小版本都可能改动,唯一例外是上一节的换肤入口 `--ds-color-theme-primary`。
52
+ 消费方可用的是 `--application-*`(101 条)与 `--ui-*`(145 条),共 246 条。
53
+ `--ds-*`(143 条)是 Foundation 内部实现,不构成公开接口,
54
+ 任意小版本都可能改动。例外是上一节的换肤入口 `--ds-color-theme-primary`,
55
+ 与只读的焦点环几何 `--ds-focus-ring-width` / `--ds-focus-ring-offset`。
54
56
 
55
57
  命名形如 `--<层>-<分组>-<项>`。消费方可用的分组与条数:
56
58
 
57
- - **`--application-*`**(91 条)—— `categorical` 20、`radius` 6、`space` 6、`font-size` 5、`line-height` 5、`button` 4、`font-weight` 4、`form-dialog` 2;另有 39 条不带分组段,形如 `--application-canvas`
58
- - **`--ui-*`**(134 条)—— `shell` 106、`viewport` 7、`z` 4、`card` 3、`duration` 2、`shadow` 2、`application` 1、`border` 1、`control` 1、`divider` 1、`ease` 1、`overlay` 1、`page` 1、`section` 1、`sidebar` 1、`surface` 1
59
+ - **`--application-*`**(101 条)—— `categorical` 20、`radius` 10、`space` 6、`font-size` 5、`line-height` 5、`button` 4、`font-weight` 4、`form-dialog` 3;另有 44 条不带分组段,形如 `--application-canvas`
60
+ - **`--ui-*`**(145 条)—— `shell` 117、`viewport` 7、`z` 4、`card` 3、`duration` 2、`shadow` 2、`application` 1、`border` 1、`control` 1、`divider` 1、`ease` 1、`overlay` 1、`page` 1、`section` 1、`sidebar` 1、`surface` 1
59
61
 
60
- 356 条 token 的完整名值表见
62
+ 389 条 token 的完整名值表见
61
63
  `node_modules/@moheng-design/ui-skill/generated/reference.md` 的「Token 全表」一节 ——
62
64
  该文件随包分发,不会过期。两层各自的取用规则见下文「组合约定」。
63
65
 
@@ -67,7 +69,7 @@ import '@moheng-design/ui/styles.css'
67
69
 
68
70
  | 不要写 | 改写成 | 替换指令 |
69
71
  |---|---|---|
70
- | `<button>` | `<Button>` | 请使用 Button 组件替代原生 <button>。导入方式:import { Button } from '@moheng-design/ui' |
72
+ | `<button>` | `<SystemButton>` | 请使用 SystemButton 组件替代原生 <button>,业务页面的按钮一律用它。导入方式:import { SystemButton } from '@moheng-design/ui' |
71
73
  | `<input>` | `<Input>` | 请使用 Input 组件替代原生 <input>。导入方式:import { Input } from '@moheng-design/ui'。type 为 checkbox / radio / range / search 时另有专用组件,见 no-native-checkbox / no-native-radio / no-native-range / no-native-search |
72
74
  | `<input type="checkbox">` | `<Checkbox>` | 请使用 Checkbox 组件替代 <input type="checkbox">。导入方式:import { Checkbox } from '@moheng-design/ui'。列表行内的批量选择另用 ListSelectionCheckbox |
73
75
  | `<input type="radio">` | `<RadioGroup>` | 请使用 RadioGroup 组件替代 <input type="radio">。RadioGroup 是组级控件,全部选项写在 items 数组里,不要逐个渲染单选项。导入方式:import { RadioGroup } from '@moheng-design/ui' |
@@ -83,7 +85,7 @@ import '@moheng-design/ui/styles.css'
83
85
  | `<details>` | `<Collapsible>` | 请使用 Collapsible 组件替代原生 <details>。导入方式:import { Collapsible } from '@moheng-design/ui'。多个互斥折叠项改用 Accordion |
84
86
  | `<summary>` | `<Collapsible>` | 请使用 Collapsible 组件的 label 替代原生 <summary>。触发器文字写进 label,被折叠的内容写进 children。导入方式:import { Collapsible } from '@moheng-design/ui' |
85
87
  | `<kbd>` | `<Kbd>` | 请使用 Kbd 组件替代原生 <kbd>。导入方式:import { Kbd } from '@moheng-design/ui' |
86
- | `<svg>` | `<Icon>` | 请使用 Icon 组件替代逐页手写的内联 <svg>。导入方式:import { Icon } from '@moheng-design/ui',写作 <Icon name="登记名" size={16} />。name 只接受已登记字形,清单见 @moheng-design/ui 的 src/icon/registry.json(reference.md 亦有全表);未登记的名字渲染为等尺寸占位盒,确需新字形须先登记进该清单并随包发版。数据可视化改用 Chart 组件,不要手绘图形 |
88
+ | `<svg>` | `<Icon>` | 请使用 Icon 组件替代逐页手写的内联 <svg>。导入方式:import { Icon } from '@moheng-design/ui',写作 <Icon name="登记名" size={16} />。name 只接受已登记字形,可用名字见 @moheng-design/ui-skill 的 generated/reference.md「图标字形」一节;未登记的名字渲染为等尺寸占位盒,确需新字形须先登记进该清单并随包发版。数据可视化改用 Chart 组件,不要手绘图形 |
87
89
  | `@/components/ui/*` | `@moheng-design/ui` | 禁止从 @/components/ui/* 导入。该目录通常是 npx shadcn add 生成的平行组件实现,与 @moheng-design/ui 并存会造成同一界面两套视觉。请改为 import { ... } from '@moheng-design/ui' |
88
90
  | `@moheng-design/ui/dist/*` | `@moheng-design/ui` | 禁止深引 @moheng-design/ui 的内部路径。请从包入口导入:import { ... } from '@moheng-design/ui'。样式表另有专用入口 @moheng-design/ui/styles.css |
89
91
 
@@ -102,7 +104,7 @@ import '@moheng-design/ui/styles.css'
102
104
 
103
105
  ## 组件清单
104
106
 
105
- 91 个组件全部在 `@moheng-design/ui` 单包内:Foundation 58 个、Application Atomic 7 个、Application Module 26 个。
107
+ 94 个组件全部在 `@moheng-design/ui` 单包内:Foundation 60 个、Application Atomic 8 个、Application Module 26 个。
106
108
 
107
109
  表中 `*` 标记必填 prop,括号内是枚举的全部取值。完整签名见 reference.md。
108
110
 
@@ -110,24 +112,25 @@ import '@moheng-design/ui/styles.css'
110
112
 
111
113
  | 组件 | 用途 | 常用 props |
112
114
  |---|---|---|
113
- | `Icon` | 已登记字形集中的单色图标 —— 规范要求图标的任何位置都用它。 | `name`*、`size`(14 / 16 / 18 / 20 / 24) |
115
+ | `Icon` | 已登记字形集中的单色图标 —— 规范要求图标的任何位置都用它。 | `name`(activity / arrow-down / arrow-up / calendar / check / chevron-down / chevron-left / chevron-right / chevron-up / chevrons-left / chevrons-right / circle-alert / circle-check / circle-check-big / columns-2 / download / ellipsis / funnel / info / kanban / layout-grid / list / message-square / minus / pencil / plus / refresh-cw / search / settings / shield-check / sliders-horizontal / trash-2 / triangle-alert / upload / x)、`size`(14 / 16 / 18 / 20 / 24) |
114
116
 
115
117
  ### Foundation · actions(4)
116
118
 
117
119
  | 组件 | 用途 | 常用 props |
118
120
  |---|---|---|
119
- | `Button` | Foundation 按钮 —— 按钮排版、几何、圆角与基础交互的唯一 Foundation Owner。 | `children`*、`variant`(primary / secondary / outline / ghost / destructive / link)、`size`(xs / sm / default / lg) |
121
+ | `Button` | Foundation 按钮 —— 按钮排版、几何、圆角与基础交互的唯一 Foundation Owner。 | `children`*、`variant`(primary / secondary / outline / ghost / destructive / destructive-outline / link)、`size`(xs / sm / default / lg) |
120
122
  | `ButtonGroup` | 把一组相关 Button 合并为一个分段控件或间隔簇。 | `orientation`(horizontal / vertical) |
121
123
  | `Toggle` | 单个两态可按下控件 —— 用于一个独立的格式或显示开关。 | `size`(sm / default / lg) |
122
124
  | `ToggleGroup` | 一组分段式开关,用于**一个局部显示选择** —— 密度、对齐方式、局部视图标记。 | `items`*、`type`(single / multiple)、`size`(sm / default / lg) |
123
125
 
124
- ### Foundation · input-selection(14)
126
+ ### Foundation · input-selection(15)
125
127
 
126
128
  | 组件 | 用途 | 常用 props |
127
129
  |---|---|---|
128
130
  | `Calendar` | 月格日期选择器,**周一为一周起始**(一…日)。 | — |
129
131
  | `Checkbox` | 独立的布尔选择,16px 方形,4px 圆角,选中时填充强调色。 | — |
130
132
  | `Combobox` | 输入即筛选的单选控件 —— 选项多到不便逐条扫视,但又不构成一次数据查询时使用。 | `options`* |
133
+ | `DateInput` | 单个日期的录入控件:与 `Input` 同高同壳(32px、12px 圆角、1px 描边),右侧带 16px 日历图标,点击弹出 `Calendar` 月格,选中即回填并收起。 | — |
131
134
  | `Field` | 表单行:标签 + 控件 + 一行说明**或**错误。 | — |
132
135
  | `Input` | 单行文本控件。 | — |
133
136
  | `InputGroup` | 单一焦点壳,包裹前置/后置附加物与一个控件 —— 图标、单位、提交按钮。 | — |
@@ -146,12 +149,12 @@ import '@moheng-design/ui/styles.css'
146
149
  |---|---|---|
147
150
  | `Accordion` | 堆叠式渐进披露,区块之间以 1px 分隔线相隔 —— **无卡片、无阴影**。 | `items`*、`type`(single / multiple) |
148
151
  | `Breadcrumb` | 真实层级的回溯路径。 | `items`* |
149
- | `Command` | 键盘优先的命令面板 —— 放进 `Dialog` 里作为全局搜索与执行入口。 | `groups`* |
152
+ | `Command` | 键盘优先的命令面板 —— 以 `dialog` 形态作为全局搜索与执行入口。 | `groups`* |
150
153
  | `ContextMenu` | 内容区域上的右键菜单 —— 行、卡片、看板块。 | `items`* |
151
154
  | `Menubar` | 桌面风格的水平菜单条,用于编辑器型工作面 —— 报表设计器、看板配置器。 | `menus`* |
152
- | `NavigationMenu` | 水平导航,条目可展开富内容面板。 | `items`* |
153
- | `Pagination` | 裸分页步进器。 | — |
154
- | `Sidebar` | Content Canvas 内部的垂直导航面 —— SPLIT 左侧目录、设置导航、模块子导航。 | `groups`* |
155
+ | `NavigationMenu` | 水平导航,条目可展开富内容面板。 | `items`*、`current`(page / true) |
156
+ | `Pagination` | 裸分页步进器:首页 · 上一页 · 页码窗口 · 下一页 · 末页。 | — |
157
+ | `Sidebar` | Content Canvas 内部的垂直导航面 —— 设置页目录。 | `groups`* |
155
158
  | `Tabs` | 页面区域内的局部标签页 —— Business View 标签、SPLIT 右栏内容标签、详情分节。 | `items`* |
156
159
 
157
160
  ### Foundation · data-content-layout(18)
@@ -177,44 +180,46 @@ import '@moheng-design/ui/styles.css'
177
180
  | `Skeleton` | 加载占位骨架 —— Loading 系统状态。 | — |
178
181
  | `Table` | DataTable 承载面 —— LIST 页面模式、LEDGER 台账页、SPLIT 右栏。 | `columns`*、`rows`*、`density`(default / sm) |
179
182
 
180
- ### Foundation · feedback-overlay(12)
183
+ ### Foundation · feedback-overlay(13)
181
184
 
182
185
  | 组件 | 用途 | 常用 props |
183
186
  |---|---|---|
184
187
  | `Alert` | 就地的、**不打断**的区域内消息 —— 缓存数据提示、部分失败、权限说明。 | `tone`(info / success / warning / danger) |
185
188
  | `AlertDialog` | 后果严重或不可逆动作前的**阻塞式确认** —— 删除、撤回、批量办结。 | — |
186
- | `Collapsible` | 单个显隐区域,由一个触发器控制 —— 查询工具栏里的「更多筛选」模式。 | — |
189
+ | `Collapsible` | 单个显隐区域,由一个触发器控制 —— 详情页的次要分节、表单里的高级选项。 | — |
187
190
  | `Dialog` | 模态容器,用于用户必须完成或放弃的聚焦任务 —— 新建、编辑、导入映射。 | — |
188
191
  | `Drawer` | 侧边面板,保持列表上下文可见 —— DETAIL 的抽屉形态。 | `side`(right / left) |
189
192
  | `DropdownMenu` | 触发器 + 菜单面板,低频动作的收纳处 —— 上下文区或行尾的「**更多**」按钮。 | `items`*、`align`(start / end) |
190
193
  | `HoverCard` | 悬停时展示的富预览 —— 人员、机构、关联记录。 | — |
191
194
  | `Popover` | 锚定式浮层面板 —— 筛选器、呈现设置、日期选择器。 | `align`(start / end) |
192
- | `Sheet` | 从任意边缘滑出的面板,用于**辅助性内容** —— 从一级导航打开的「设置」面板、帮助面板、附件预览。 | `side`(right / left / top / bottom) |
195
+ | `Sheet` | 从任意边缘滑出的面板,用于**辅助性内容** —— 帮助面板、附件预览。 | `side`(right / left / top / bottom) |
193
196
  | `Sonner` | 转瞬即逝的提示堆栈 —— **确认某件事已经发生**(已保存、已导出、3 条已办结)。 | `toasts`*、`position`(bottom-right / bottom-left / top-right / top-left) |
197
+ | `SonnerProvider` | `Sonner` 的调用入口 —— 挂在应用根,子树里任何位置用 `useToast()` 弹出提示。 | `position`(bottom-right / bottom-left / top-right / top-left) |
194
198
  | `Spinner` | 不确定时长的**原地**等待 —— 刷新中的按钮、提交中的对话框。 | — |
195
199
  | `Tooltip` | 悬停或聚焦时出现的短标签,用于**为纯图标控件命名** —— 五个全局动作触发器、工具栏图标按钮。 | `side`(top / bottom / left / right) |
196
200
 
197
- ### Application Atomic(7)
201
+ ### Application Atomic(8)
198
202
 
199
203
  | 组件 | 用途 | 常用 props |
200
204
  |---|---|---|
205
+ | `ApplicationDateRangeFilter` | 查询工具栏主控制行中的**日期区间**快捷筛选,与 `ApplicationFilterMenu` 同为一个 常驻维度,放进 `ApplicationQueryToolbar` 的 `commonFilters`。 | `label`* |
201
206
  | `ApplicationFilterMenu` | 查询工具栏主控制行中的常驻快捷筛选 —— **一个高频维度**。 | `options`* |
202
207
  | `ListSelectionCheckbox` | 列表 / 表格 / 卡片网格 / 看板的记录选择框。 | `scope`(row / all) |
203
- | `ListTablePagination` | 列表 / 表格分页 —— 结果区间、总数、每页条数与翻页步进。 | — |
208
+ | `ListTablePagination` | 列表 / 表格分页 —— 摘要、每页条数、页码窗口与跳页。 | — |
204
209
  | `SearchField` | 共享的紧凑搜索入口 —— **产品内每一处纯文本搜索**: 查询工具栏、目录搜索、人员与文件选择器。 | `ariaLabel`* |
205
210
  | `SidebarAppLinkButton` | 应用快捷入口 —— 从工作台侧栏或应用切换器跳转到另一个应用。 | — |
206
211
  | `SidebarRailButton` | 工作台菜单栏条目 —— 56px 宽的列内,图标在上、标签在下。 | — |
207
- | `SystemButton` | 应用语义按钮 —— **整个产品的默认动作按钮**。 | `intent`(primary / secondary / quiet / icon / link / destructive)、`size`(default / compact / icon) |
212
+ | `SystemButton` | 应用语义按钮 —— **整个产品的默认动作按钮**。 | `intent`(primary / secondary / quiet / link / destructive / destructive-outline)、`size`(default / compact / sm) |
208
213
 
209
214
  ### Application Module · navigation(5)
210
215
 
211
216
  | 组件 | 用途 | 常用 props |
212
217
  |---|---|---|
213
218
  | `ApplicationModuleSwitcher` | 应用二级导航的**左半部分** —— 你在哪个模块,以及如何切换。 | — |
214
- | `ApplicationPrimaryNavigation` | `APPLICATION.PRIMARY_NAV` —— 固定 Shell 的**第二带**。 | `activeAction`(messages / todos / overview / risk / settings) |
215
- | `ApplicationSecondaryNavigation` | `APPLICATION.SECONDARY_NAV` —— 固定 Shell 的**第三带**。 | — |
219
+ | `ApplicationPrimaryNavigation` | `APPLICATION.PRIMARY_NAV` —— GAP Design kit「通用导航 / 应用一级导航」。 | `appGlyph`(activity / arrow-down / arrow-up / calendar / check / chevron-down / chevron-left / chevron-right / chevron-up / chevrons-left / chevrons-right / circle-alert / circle-check / circle-check-big / columns-2 / download / ellipsis / funnel / info / kanban / layout-grid / list / message-square / minus / pencil / plus / refresh-cw / search / settings / shield-check / sliders-horizontal / trash-2 / triangle-alert / upload / x)、`activeAction`(messages / todos / overview / risk / settings) |
220
+ | `ApplicationSecondaryNavigation` | `APPLICATION.SECONDARY_NAV` —— GAP Design kit「应用二级导航」,外壳的最后一带 (基础版第二带、集团版第三带)。 | — |
216
221
  | `GlobalSidebar` | 工作台左侧 72px 菜单栏,由 `SidebarRailButton` 构成。 | — |
217
- | `TopNavigationPrimaryBar` | `PLATFORM.TOP_USER_BAR` —— 固定 Shell 的**第一带**。 | — |
222
+ | `TopNavigationPrimaryBar` | `PLATFORM.TOP_USER_BAR` —— GAP Design kit「集团顶部导航」,**只在集团版外壳出现** (本带 + 应用一级 + 应用二级,共 144)。 | — |
218
223
 
219
224
  ### Application Module · statistics(5)
220
225
 
@@ -223,18 +228,18 @@ import '@moheng-design/ui/styles.css'
223
228
  | `ApplicationMetricChart` | `chart` 语义:数值 + 内嵌迷你走势线。 | — |
224
229
  | `ApplicationMetricPrimarySecondary` | `primary-secondary` 语义:一个主数字 + 其拆解。 | — |
225
230
  | `ApplicationMetricStatus` | `status` 语义:功能状态 + 其计数 —— 逾期数、规则违反、系统健康度。 | `status`(normal / warning / danger / info) |
226
- | `ApplicationMetricStrip` | 指标区容器,同时承载 `numeric` 与 `icon` 两种基础语义。 | — |
231
+ | `ApplicationMetricStrip` | 指标区容器,同时承载 `numeric` 与 `icon` 两种基础语义。 | `state`(ready / loading / error) |
227
232
  | `ApplicationMetricTrend` | `trend` 语义:数值 + 环比变化量。 | `direction`(up / down / flat) |
228
233
 
229
234
  ### Application Module · content(7)
230
235
 
231
236
  | 组件 | 用途 | 常用 props |
232
237
  |---|---|---|
233
- | `ApplicationDataDisplay` | Canvas 的**数据展示区**。 | `state`(ready / loading / empty / error / no-permission / not-found) |
238
+ | `ApplicationDataDisplay` | Canvas 的**数据展示区**。 | `presentation`(DataTable / RecordList / CardList / KanbanBoard / Calendar / Chart / Timeline)、`state`(ready / loading / empty / error / no-permission / not-found) |
234
239
  | `ApplicationFilterList` | 完整的筛选维度列表 —— **「更多筛选」的面板主体**。 | — |
235
240
  | `ApplicationPageHeader` | Canvas 的**上下文区**(源仓库名 `application-page-header`)。 | `dataStatus`(normal / refreshing / failed)、`pageMode`(LIST / CARD / SPLIT / BOARD / CALENDAR) |
236
- | `ApplicationPageLayoutContainer` | 每个业务页面的脚手架 —— 直接放进 Content Canvas 内。 | — |
237
- | `ApplicationQueryToolbar` | **数据控制区** —— 统一承载 Canvas 五层模型的 L3 业务视图与 L4 数据控制。 | `presentation`(DataTable / CardList / KanbanBoard / Calendar / Chart / Timeline) |
241
+ | `ApplicationPageLayoutContainer` | 每个业务页面的脚手架 —— 直接放进 Content Canvas 内。 | `pageType`(WORKBENCH / MANAGEMENT / LEDGER / ANALYSIS / REPORT / DETAIL) |
242
+ | `ApplicationQueryToolbar` | **数据控制区** —— 统一承载 Canvas 五层模型的 L3 业务视图与 L4 数据控制。 | `presentation`(DataTable / RecordList / CardList / KanbanBoard / Calendar / Chart / Timeline) |
238
243
  | `ApplicationRecordDetailBody` | **唯一的**业务详情主体,由抽屉形态与独立详情页共用 ——「一份详情,两个载体」。 | — |
239
244
  | `ApplicationSplitListSidebar` | SPLIT 页面模式的**左栏**。 | — |
240
245
 
@@ -249,18 +254,18 @@ import '@moheng-design/ui/styles.css'
249
254
 
250
255
  | 组件 | 用途 | 常用 props |
251
256
  |---|---|---|
252
- | `ApplicationDetailDrawer` | DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后的列表。 | — |
253
- | `ApplicationFormDialog` | 业务对象的新建与编辑表单对话框。 | `size`(small / large) |
254
- | `ApplicationGlobalActionPanel` | 四个 popover 型全局动作**共享的同一个面板** —— 消息 / 待办 / 运行总览 / 风险预警。 | — |
257
+ | `ApplicationDetailDrawer` | DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后的列表。 | `side`(left / right) |
258
+ | `ApplicationFormDialog` | 业务对象的新建与编辑表单对话框。 | `size`(small / large / xlarge) |
259
+ | `ApplicationGlobalActionPanel` | 四个 popover 型全局动作**共享的同一个面板** —— 消息 / 待办 / 总览 / 风险预警。 | `state`(ready / loading / empty / error / no-permission) |
255
260
  | `PeoplePickerDialog` | 人员 / 组织选择器 —— 指派人、审核人、通知接收人、共享对象。 | — |
256
261
 
257
262
  ### Application Module · collaboration(3)
258
263
 
259
264
  | 组件 | 用途 | 常用 props |
260
265
  |---|---|---|
261
- | `ContactsCollaborationWorkspace` | 「人员与组织」工作台 —— **三栏**:组织树定位器 · 成员列表 · 成员详情。 | — |
262
- | `FilesCollaborationWorkspace` | 「文件」工作台 —— 左侧文件夹定位器 · 中间文件表 · 右侧可选预览栏。 | — |
263
- | `ScheduleCollaborationWorkspace` | 「日程」工作台 —— 粒度切换 · 月格 · 当日议程栏。 | `grain`(day / week / month) |
266
+ | `ContactsCollaborationWorkspace` | 「人员与组织」工作台 —— **三栏**:组织树定位器 · 成员列表 · 成员详情。 | `state`(ready / loading / empty / error / no-permission / not-found) |
267
+ | `FilesCollaborationWorkspace` | 「文件」工作台 —— 左侧文件夹定位器 · 中间文件表 · 右侧可选预览栏。 | `state`(ready / loading / empty / error / no-permission / not-found) |
268
+ | `ScheduleCollaborationWorkspace` | 「日程」工作台 —— 粒度切换 · 月格 · 当日议程栏。 | `grain`(day / week / month)、`state`(ready / loading / empty / error / no-permission / not-found) |
264
269
 
265
270
  ## 五层 Canvas 模型
266
271
 
@@ -279,26 +284,123 @@ Application
279
284
  └─ Overlay Dialog / Drawer / Popover / Menu / Toast
280
285
  ```
281
286
 
282
- ### Shell 四带
287
+ ### Shell 导航带
283
288
 
284
- 固定骨架,**没有左侧全局栏**。三条导航带 `position: fixed`,永不滚动。
289
+ 固定骨架,**没有左侧全局栏**。导航带永不滚动。几何以 GAP Design kit「框架结构」为准,外壳有两种形态:
290
+
291
+ | 形态 | 带(自上而下) | Standard 总高 | Compact 总高 |
292
+ |---|---|---:|---:|
293
+ | 基础版 | 应用一级 + 应用二级 | 96px | 80px |
294
+ | 集团版 | 集团顶部 + 应用一级 + 应用二级 | 144px | 120px |
285
295
 
286
296
  | 带 | 组件 | Standard | Compact |
287
297
  |---|---|---:|---:|
288
- | 顶部导航 `PLATFORM.TOP_USER_BAR` | `TopNavigationPrimaryBar` | 52px | 44px |
289
- | 应用一级导航 `APPLICATION.PRIMARY_NAV` | `ApplicationPrimaryNavigation` | 64px | 52px |
298
+ | 集团顶部导航 `PLATFORM.TOP_USER_BAR`(仅集团版) | `TopNavigationPrimaryBar` | 48px | 40px |
299
+ | 应用一级导航 `APPLICATION.PRIMARY_NAV` | `ApplicationPrimaryNavigation` | 48px | 40px |
290
300
  | 应用二级导航 `APPLICATION.SECONDARY_NAV` | `ApplicationSecondaryNavigation` | 48px | 40px |
291
301
  | Content Canvas | `ApplicationPageLayoutContainer` | 剩余视口 | 剩余视口 |
292
302
 
293
- **Content Canvas 是页面唯一的垂直滚动持有者。** 宿主 padding 为零 —— padding 属于页面内容根。
303
+ 账户头像在基础版里是 `ApplicationPrimaryNavigation` 的 `account`,在集团版里在 `TopNavigationPrimaryBar`,
304
+ 一个外壳只有一处。外壳总高读 `--ui-shell-application-total-height`:渲染了 `TopNavigationPrimaryBar` 时它自动计入
305
+ 集团顶栏,宿主不必区分两种形态。
306
+
307
+ Compact 档在视口宽 ≤1180px 或高 ≤720px 时生效(`--ui-viewport-compact-max-width` / `-height`),
308
+ 各带高度由同一组 `@media` 一并切换,宿主不得自行复刻断点。
309
+
310
+ 宿主 padding 为零 —— padding 属于页面内容根。
311
+
312
+ ### 宿主布局
313
+
314
+ 本库不提供宿主组件(07 · C-5:组件留到第二个真实项目再抽),导航带 + Canvas 的宿主由应用
315
+ 自己写,标准写法如下(类名由宿主自定,只读 `--application-*` 与 `--ui-*`):
316
+
317
+ ```css
318
+ html,
319
+ body {
320
+ block-size: 100%;
321
+ margin: 0;
322
+ }
323
+
324
+ .app-shell { /* 导航带 + Canvas,整体占满视口 */
325
+ display: flex;
326
+ flex-direction: column;
327
+ block-size: 100dvh;
328
+ background: var(--application-canvas);
329
+ }
330
+
331
+ .app-shell__bands { /* 包住全部导航带;不进滚动容器,即永不滚动 */
332
+ flex: none;
333
+ z-index: var(--ui-z-shell);
334
+ }
335
+
336
+ .app-shell__canvas { /* Content Canvas:必须是列向 flex */
337
+ display: flex;
338
+ flex: 1;
339
+ flex-direction: column;
340
+ min-block-size: 0;
341
+ overflow: auto;
342
+ }
343
+
344
+ .app-shell__page { /* 页面根(ApplicationPageLayoutContainer 的 className) */
345
+ flex: 1;
346
+ }
347
+ ```
348
+
349
+ **Canvas 必须是列向 flex 容器。** 写成块级 + `overflow: auto`(最自然的写法)时,
350
+ `ApplicationPageLayoutContainer` 按内容撑高,`ApplicationDataDisplay`「自身滚动、分页固定在底部」
351
+ 随之失效 —— 05 · P2-1 实测 46 行时分页被推到首屏以下 533px。页面根 `flex: 1` 让内容不足一屏时
352
+ 数据展示区的边框仍画到底。`DETAIL` 页的容器随内容增高,由同一个 Canvas 滚动,宿主不必区分页型。
353
+
354
+ **`GlobalSidebar` 与内容区并排**(工作台):两者包一层横向 flex 作为 Canvas 的直接子元素,
355
+ 菜单栏 `sticky` 停在 Canvas 顶部、自己不滚动,内容区随内容撑高、由 Canvas 滚动:
356
+
357
+ ```css
358
+ .workbench { /* Canvas 的直接子元素 */
359
+ display: flex;
360
+ flex: 1 0 auto;
361
+ align-items: flex-start;
362
+ }
363
+
364
+ .workbench__rail { /* GlobalSidebar 的 className */
365
+ position: sticky;
366
+ inset-block-start: 0;
367
+ flex: none;
368
+ block-size: calc(100dvh - var(--ui-shell-application-total-height));
369
+ }
370
+
371
+ .workbench__main { /* ApplicationPageLayoutContainer 的 className */
372
+ flex: 1;
373
+ min-inline-size: 0;
374
+ align-self: stretch;
375
+ }
376
+ ```
377
+
378
+ ### 纵向滚动归属
379
+
380
+ 每个页面**有且只有一个**页面级纵向滚动持有者,按页型划分(06 · D-4 裁决):
381
+
382
+ | 页面 | 纵向滚动持有者 | 理由 |
383
+ |---|---|---|
384
+ | 结果集页面(见下「五层认知模型」) | `ApplicationDataDisplay` 的主体 | 上下文区、工具栏、分页条与批量条固定,只有结果滚动 |
385
+ | `WORKBENCH` / `DETAIL` / `ANALYSIS` 多面板 / 无结果集页面 | Content Canvas | 内容是若干面板或分节,整页一起滚;放进 DataDisplay 会只剩约 290px 可视高度 |
386
+
294
387
  表格、看板、标签页、日历可以拥有正交的水平滚动或局部有界滚动;
295
- 不得堆叠无界的垂直滚动容器。
388
+ 不得堆叠无界的垂直滚动容器。多面板的 `ANALYSIS` 页不得把面板组塞进 `ApplicationDataDisplay`。
296
389
 
297
390
  Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑、通知铃铛、页面标题、卡片、阴影。
298
391
 
299
392
  ### 五层认知模型
300
393
 
301
- 新页面必须把五层**全部**声明为状态字段。缺一层即为结构不完整。
394
+ 必填字段按页面有没有**结果集**划分(06 · D-1 裁决)。判据是页面是否有一份由
395
+ `ApplicationQueryToolbar` 驱动、由 `ApplicationDataDisplay` 展示的记录集合:
396
+
397
+ | 页面 | 必须声明的字段 | 典型 |
398
+ |---|---|---|
399
+ | 结果集页面 | 五层**全部**,缺一层即为结构不完整 | `MANAGEMENT` / `LEDGER` / `REPORT` 的列表页;以查询结果为主体的 `ANALYSIS` 页(单模式时 `pageMode` 取 `LIST`,切换器不渲染) |
400
+ | 无结果集页面 | 只声明 `pageType`,其余四层**不写**;不得为凑字段塞一个 `ApplicationDataDisplay` 或空工具栏 | `WORKBENCH` 工作台、`DETAIL` 详情页、配置页、协作工作台、编辑器型工作面 |
401
+
402
+ 无结果集页面的 `pageType` 按所属业务取值:工作台取 `WORKBENCH`,详情页取 `DETAIL`,
403
+ 配置页与协作工作台取其所属模块的类型(多为 `MANAGEMENT`),报表设计器随报表取 `REPORT`。
302
404
 
303
405
  | 层 | 字段 | 取值 |
304
406
  |---|---|---|
@@ -306,7 +408,7 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
306
408
  | L2 页面模式 | `pageMode` | `LIST` / `CARD` / `SPLIT` / `BOARD` / `CALENDAR` |
307
409
  | L3 业务视图 | `businessView` | 2–4 个稳定工作视角(全部 / 我的责任 / 最近处理) |
308
410
  | L4 数据控制 | `dataControl` | search / filters / sort / pagination / appliedFilterTags |
309
- | L5 数据呈现 | `dataPresentation` | `DataTable` / `CardList` / `KanbanBoard` / `Calendar` / `Chart` / `Timeline` |
411
+ | L5 数据呈现 | `dataPresentation` | `DataTable` / `RecordList` / `CardList` / `KanbanBoard` / `Calendar` / `Chart` / `Timeline` |
310
412
 
311
413
  `DETAIL` 与 `COMPOSITE` **不是**页面模式,是特殊物理结构资产。
312
414
  `Embedded` 是 `integrationMode`,不是页面模式。
@@ -316,14 +418,76 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
316
418
  自上而下固定,不得重排:
317
419
 
318
420
  ```
319
- 上下文区 ApplicationPageHeader L1 / L2 / L3 的承载者
421
+ 内容根 ApplicationPageLayoutContainer L1,pageType 必填;包住以下四个区域
422
+ 上下文区 ApplicationPageHeader L2 / L3 的承载者
320
423
  指标区 ApplicationMetric*(可选) 不是每个页面都有
321
424
  数据控制 ApplicationQueryToolbar L4
322
425
  ApplicationFilterList L4 的已应用筛选标签
323
426
  数据展示 ApplicationDataDisplay L5
324
427
  ```
325
428
 
326
- `SPLIT` 模式另有左栏 `ApplicationSplitListSidebar`(360px,Compact 300px)。
429
+ 上表是结果集页面的顺序。`SPLIT` 与无结果集页面的结构见下两节。
430
+
431
+ ### SPLIT 的标准组件树
432
+
433
+ 工具栏服务右栏,但放在横跨两栏的 `dataControl` 槽位 —— 它管的是右栏的结果集,
434
+ 左栏目录只改变查询范围(06 · D-4 裁决):
435
+
436
+ ```
437
+ ApplicationPageLayoutContainer pageType, dataControl
438
+ ├─ header ApplicationPageHeader pageMode="SPLIT"
439
+ ├─ dataControl ApplicationQueryToolbar businessView、search / filters / sort、viewModeSwitch
440
+ │ └─ moreFilters Popover > ApplicationFilterList(不得用 Collapsible 就地展开)
441
+ └─ children Resizable 左栏宽度取 --ui-sidebar-list-width(360 / Compact 300)
442
+ ├─ ApplicationSplitListSidebar 目录定位,只改变查询范围
443
+ └─ ApplicationDataDisplay presentation = 当前 View Mode
444
+ └─ ApplicationRecordList / Table / 呈现配方
445
+ ```
446
+
447
+ 右栏需要再分「结果 / 概况」等内容标签时,`Tabs` 放在右栏顶部、`ApplicationDataDisplay`
448
+ 作为当前标签的面板;概况标签下工具栏仍在,但不得为它另起第二个工具栏。
449
+
450
+ ### 无结果集页面的结构
451
+
452
+ 这类页面只声明 `pageType`,由 Content Canvas 整页滚动,没有工具栏与数据展示区。
453
+
454
+ ```
455
+ WORKBENCH ApplicationPageLayoutContainer pageType="WORKBENCH"
456
+ ├─ header ApplicationPageHeader(标题、数据时刻、刷新;不渲染 Page Mode Switch)
457
+ └─ children 分区导航 GlobalSidebar + 面板网格(指标区、待办、动态、应用入口)
458
+
459
+ DETAIL ApplicationPageLayoutContainer pageType="DETAIL"
460
+ ├─ header ApplicationPageHeader(breadcrumb 返回来源列表;对象级动作放 actions)
461
+ └─ children ApplicationRecordDetailBody(分节;分节级动作放分节标题行)
462
+
463
+ 编辑器 ApplicationPageLayoutContainer pageType 随所属业务
464
+ ├─ header ApplicationPageHeader(标题、保存 / 发布等页面动作)
465
+ ├─ dataControl Menubar(编辑命令就是这页的「数据控制」)
466
+ └─ children 工作面:Resizable 两栏,各栏自带有界 ScrollArea
467
+ ```
468
+
469
+ **对象级动作的落点**:详情页与协作工作台里针对「当前对象」的动作(编辑、指派、删除)
470
+ 放 `ApplicationPageHeader` 的 `actions`;`ApplicationRecordDetailBody` 只放分节级动作。
471
+
472
+ ### 呈现配方
473
+
474
+ `KanbanBoard` / `Calendar` / `Timeline` 暂无专属组件,按下面的标准拼装写法承载
475
+ (06 · D-2 裁决:先登记配方,组件留到第二个真实项目再抽)。三者都放在
476
+ `ApplicationDataDisplay` 的 `children` 里,仅 `state="ready"` 时渲染,不得自画外框。
477
+
478
+ - **看板(`KanbanBoard`)**:`ScrollArea horizontal` 包一行等宽列,列宽取
479
+ `--ui-card-min-width`;每列是「列标题 + 计数」与一串 `Card density="sm" interactive`;
480
+ 卡片内勾选用 `ListSelectionCheckbox`,行级动作用 `DropdownMenu`(「更多 → 移至」代替拖拽)。
481
+ 看板是「不得嵌套 `ScrollArea`」的登记例外(07 · C-14):外层 `ScrollArea horizontal` 撑满数据展示区
482
+ 主体的高度、只管横向,每列的卡片串放进一个纵向 `ScrollArea`、高度取列的剩余高度,列内纵向滚动。
483
+ 横向滚动条因此始终贴在可视区底部,不会被推到五列溢出的纵向末尾(06 · P2-7)。除看板外仍不得嵌套。
484
+ - **月历(`Calendar`)**:自拼 7 列月格,`role="grid"` / `row` / `gridcell`,周一起始,
485
+ 月末空位补白格;每格最多列 3 条,其余收进「+N」按钮。月份游标(上一月 / 下一月 / 本月)
486
+ 放在月格上方、数据展示区之内,不进工具栏。不得用 Foundation `Calendar` 控件充当月格。
487
+ - **时间轴(`Timeline`)**:按日期分组,每组是 `<section aria-label>` + `Separator label`
488
+ (分组标题)+ `<ol>`;每条用 `Message`(作者、时间、正文)。时间轴只按时间排序,
489
+ 不提供行选择,切到时间轴时清空已选并不渲染批量条。
490
+
327
491
  `DETAIL` 结构用 `ApplicationRecordDetailBody`。
328
492
 
329
493
  ### 三个绝不能混为一谈的切换器
@@ -332,18 +496,27 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
332
496
  仅当页面真正开放 2 个以上模式时渲染,否则不占位。改 `pageMode`。
333
497
  - **View Mode Switch** —— 仅 `SPLIT` 右栏。改 `dataPresentation`,**绝不改** `pageMode`。
334
498
  - **Presentation Settings** —— 是一个*概念*,不是一个按钮名。
335
- 按钮必须按当前呈现方式命名:`列设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
499
+ 按钮必须按当前呈现方式命名:`列设置` / `列表设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
336
500
  **禁止通用的「视图设置」按钮。** 呈现设置不得改变搜索、筛选、业务视图或页面模式,
337
- 它只调整当前呈现方式的展示细节。
501
+ 它只调整当前呈现方式的展示细节。面板一律用 `Popover` 承载,与更多筛选同一承载(07 · C-7)。
338
502
 
339
503
  ### 六种数据状态
340
504
 
341
505
  `ApplicationDataDisplay` 的 `state` 取六值:
342
506
  `ready` / `loading` / `empty` / `error` / `no-permission` / `not-found`。
343
507
 
344
- **六种状态的文案绝不共用同一句话。** 「当前视角下无数据」「你没有权限」「请求失败」
508
+ **六种状态的文案绝不共用同一句话。** 「当前视角下无数据」「无权查看本模块」「请求失败」
345
509
  是三句不同的话,成因不同,用户的下一步动作也不同。
346
- 另有 Partial Failure —— 部分数据加载失败,不等同于 `error`。
510
+ 另有 Partial Failure —— 部分数据加载失败,不等同于 `error`:`state` 仍为 `ready`,
511
+ 呈现照常渲染,缺失的那部分用 `Alert` 放进 `ApplicationDataDisplay` 的 `notice` 槽位说明并给出重试。
512
+ `notice` 固定在批量条之下、呈现之上,不随内容滚动,只在 `ready` 态渲染。
513
+
514
+ **空态按成因分两句**(07 · C-6):有搜索或筛选生效时是「没有符合当前筛选条件的记录」,
515
+ 出路 `清除筛选`;当前视图下本就没有数据时是「当前视图下还没有记录」,出路 `新建`。
516
+ 空态只由 `ApplicationDataDisplay` 的 `empty` 槽位承担,被承载的 `Table` 不再另设 `empty`。
517
+
518
+ **非 ready 状态下的工具栏**:`no-permission` 与 `not-found` 时不渲染 `ApplicationQueryToolbar`
519
+ (查询条件对这两种状态没有意义);`error` 时保留,改条件即可重新查询。
347
520
 
348
521
  页面头部的数据状态(`ApplicationPageHeader` 的 `dataStatus`)另有三值:
349
522
  `normal`(附最后更新时间)/ `refreshing` / `failed`(附重试入口)。
@@ -351,8 +524,11 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
351
524
  ### 关键尺寸
352
525
 
353
526
  抽屉宽 680px(`--application-drawer-width: 1280px` 是宽/全屏变体);
354
- 表单对话框 720px / 960px;`SPLIT` 左栏 360px(Compact 300px);
527
+ 表单对话框 720px / 960px / 1280px;`SPLIT` 左栏 360px(Compact 300px);
355
528
  卡片网格默认 ≥1440 五列、Condensed 四列、Compact 三列,卡片最小宽 220px。
529
+ 列数读 `--ui-card-columns-default`,三档由 `viewport.css` 的 `@media` 在 `:root` 上改写(5 / 4 / 3),
530
+ 最小宽读 `--ui-card-min-width`,卡间距读 `--ui-card-gap`;系统内没有卡片网格组件,
531
+ `CARD` 呈现的网格由调用方用这三个 token 写,不得在组件或页面里另写断点改列数。
356
532
 
357
533
  ### Mock 数据
358
534
 
@@ -361,6 +537,9 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
361
537
  `示例应用`(应用名)· `应用说明信息`(应用描述)· `模块名称`(当前模块)·
362
538
  `模块 A` / `模块 B` / `模块 C`(模块菜单)· `Tab 1` / `Tab 2`(业务标签)· `企业名称`(品牌兜底)。
363
539
 
540
+ 业务记录的占位符(07 · C-8):`成员 A` / `成员 B` / `成员 C`(人名)· `对象 A` / `对象 B` / `对象 C`(业务对象名)·
541
+ `编号 0001` / `编号 0002`(记录编号,四位补零递增)。同类条目按字母或序号顺延,不得换用真实人名。
542
+
364
543
  `模块1` / `模块2` 作为标签文案被明令禁止。
365
544
 
366
545
 
@@ -387,8 +566,10 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
387
566
  | `--application-*` / `--ui-*` | 公共接口,稳定契约 | 应用代码、页面布局 |
388
567
 
389
568
  业务代码只读 `--application-*` 与 `--ui-*`。下探 `--ds-*` 等于依赖内部实现,
390
- 小版本即可能失效。唯一的例外是换肤入口 `--ds-color-theme-primary`,
391
- 应用层可以且应当覆盖它。
569
+ 小版本即可能失效。例外只有两处:换肤入口 `--ds-color-theme-primary`,
570
+ 应用层可以且应当覆盖它;焦点环几何 `--ds-focus-ring-width` 与 `--ds-focus-ring-offset`,
571
+ 自定义可聚焦元素画焦点环时读取(不得覆盖)—— 焦点环的粗细与偏移全产品必须一致,
572
+ 本库不为它另开别名,组件内部读的也是这两个。
392
573
 
393
574
  **任何情况下都不得在业务代码中写字面色值、圆角与间距去对齐组件。**
394
575
  需要与组件对齐时读同一个 token。
@@ -424,7 +605,9 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
424
605
 
425
606
  ### 滚动
426
607
 
427
- Content Canvas 是页面唯一的主垂直滚动权持有者。
608
+ 每个页面有且只有一个页面级纵向滚动持有者,按页型划分(06 · D-4):结果集页面由
609
+ `ApplicationDataDisplay` 的主体滚动,`WORKBENCH` / `DETAIL` / 多面板 `ANALYSIS` 等无结果集页面由
610
+ Content Canvas 滚动,见「五层 Canvas 模型」的「纵向滚动归属」。
428
611
  `ScrollArea` 与 `MessageScroller` 只用于**正交方向**(水平)或**局部有界**的溢出,
429
612
  且必须给出显式高度或最大高度。不得堆叠无界的垂直滚动容器。
430
613
 
@@ -441,7 +624,12 @@ Content Canvas 是页面唯一的主垂直滚动权持有者。
441
624
  Partial Failure 六种状态的文案各不相同,不得共用。
442
625
  Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
443
626
 
444
- > 逐组件的组合约定(91 个章节:何时使用、何时改用其他组件、禁止与使用边界)
627
+ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`,不写 `你没有权限`。
628
+ 表单与说明文案(02 §8):校验错误写字段名与不满足的条件(`任务名称不能为空`);
629
+ 确认说明写后果(`删除后 3 条记录不可恢复`),不写请求;占位文字写示例或范围
630
+ (`例如:季度巡检记录`),不写指令;无权限的出路点明找谁(`联系本模块管理员开通`)。
631
+
632
+ > 逐组件的组合约定(94 个章节:何时使用、何时改用其他组件、禁止与使用边界)
445
633
  > 见 `node_modules/@moheng-design/ui-skill/generated/reference.md`。
446
634
 
447
635
  ## 反例
@@ -461,18 +649,33 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
461
649
 
462
650
  ```jsx
463
651
  // 不要这样写
464
- <Button variant="icon"><Icon name="rotate-cw" size={16} /></Button>
465
- <Button size="icon"><Icon name="rotate-cw" size={16} /></Button>
652
+ <SystemButton intent="icon"><Icon name="refresh-cw" size={16} /></SystemButton>
653
+ <SystemButton size="icon"><Icon name="refresh-cw" size={16} /></SystemButton>
466
654
 
467
- // 要这样写 —— 尺寸与形状是两根轴,iconOnly 控制形状
468
- <Button iconOnly aria-label="刷新"><Icon name="rotate-cw" size={16} /></Button>
655
+ // 要这样写 —— 意图与形状是两根轴,iconOnly 控制形状
656
+ <SystemButton intent="quiet" iconOnly aria-label="刷新"><Icon name="refresh-cw" size={16} /></SystemButton>
469
657
  ```
470
658
 
471
- `variant` 只有 `primary` / `secondary` / `outline` / `ghost` / `destructive` / `link`;
472
- `size` 只有 `xs` / `sm` / `default` / `lg`。**shadcn 习惯的 `size="icon"` 在本库不存在。**
659
+ `SystemButton` 的 `intent` 只有 `primary` / `secondary` / `quiet` / `link` / `destructive`;
660
+ `size` 只有 `default` / `compact` / `sm`。**shadcn 习惯的 `size="icon"` 在本库不存在**,
661
+ Foundation `Button` 同样只用 `iconOnly` 表达等宽图标按钮。
473
662
 
474
663
  `iconOnly` 为 true 时按钮没有可见文字,**必须**另给 `aria-label`。
475
664
 
665
+ ### 业务页面用 Foundation Button
666
+
667
+ ```jsx
668
+ // 不要这样写 —— Button 只供库内组件使用
669
+ <Button variant="primary" onClick={create}>新建</Button>
670
+
671
+ // 要这样写 —— 业务页面的按钮一律用 SystemButton
672
+ <SystemButton intent="primary" onClick={create}>新建</SystemButton>
673
+ ```
674
+
675
+ `SystemButton` 是整个产品的默认动作按钮,承载应用意图、`loading` 与产品状态;
676
+ 改一次应用强调色,全部 `SystemButton` 同时换肤。lint 的 `no-native-button` 把原生
677
+ `<button>` 改写成的也是它。
678
+
476
679
  ### 内联 style
477
680
 
478
681
  ```jsx
@@ -493,10 +696,10 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
493
696
  ```jsx
494
697
  // 不要这样写
495
698
  const [hover, setHover] = useState(false)
496
- <Button onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}>
699
+ <SystemButton onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}>
497
700
 
498
701
  // 要这样写 —— 什么都不写,hover 已由 CSS 伪类实现
499
- <Button>提交</Button>
702
+ <SystemButton>提交</SystemButton>
500
703
  ```
501
704
 
502
705
  `useState` 会让组件强制成为 client component。状态一律用 CSS 伪类
@@ -508,7 +711,7 @@ const [hover, setHover] = useState(false)
508
711
  /* 不要这样写 —— 只会改到引用它的那部分组件 */
509
712
  :root { --application-accent: #16a34a; }
510
713
 
511
- /* 也不要这样写 —— 别名层整层声明在 :root,挂在容器上一律无效 */
714
+ /* 也不要这样写 —— 别名层整层声明在 :root,挂在容器上半生效 */
512
715
  <div className="dark">…</div>
513
716
 
514
717
  /* 要这样写 */
@@ -517,7 +720,8 @@ const [hover, setHover] = useState(false)
517
720
 
518
721
  `--ds-color-theme-primary` 是换肤契约的唯一入口。
519
722
  换肤与 `.dark` **必须挂在 `<html>` 上** —— `var()` 代换在声明所在元素就完成了,
520
- 挂在 `<body>` 或容器 div 上无效(已实测)。系统内不存在「局部暗色区块」这种用法。
723
+ 挂在 `<body>` 或容器 div 上是半生效(已实测):直接读 `--ds-*` 的部件变了,读 `--application-*`
724
+ 的部件不变。半生效比无效更糟 —— 看上去像是生效了。系统内不存在「局部暗色区块」这种用法。
521
725
 
522
726
  ### 手写表格结构
523
727
 
@@ -561,10 +765,10 @@ const [hover, setHover] = useState(false)
561
765
  ```jsx
562
766
  // 不要这样写
563
767
  import { Button } from '@/components/ui/button'
564
- import { Button } from '@moheng-design/ui/dist/components/foundation/actions/Button.js'
768
+ import { SystemButton } from '@moheng-design/ui/dist/components/application-atomic/SystemButton.js'
565
769
 
566
770
  // 要这样写
567
- import { Button } from '@moheng-design/ui'
771
+ import { SystemButton } from '@moheng-design/ui'
568
772
  ```
569
773
 
570
774
  `@/components/ui/` 目录通常是 `npx shadcn add` 生成的第二套组件源码,
@@ -577,10 +781,10 @@ import { Button } from '@moheng-design/ui'
577
781
 
578
782
  ```jsx
579
783
  // 不要这样写 —— 组件渲染出来是无样式的裸结构
580
- import { Button } from '@moheng-design/ui'
784
+ import { SystemButton } from '@moheng-design/ui'
581
785
 
582
786
  // 要这样写 —— 应用入口引一次即可
583
- import { Button } from '@moheng-design/ui'
787
+ import { SystemButton } from '@moheng-design/ui'
584
788
  import '@moheng-design/ui/styles.css'
585
789
  ```
586
790
 
@@ -590,16 +794,18 @@ import '@moheng-design/ui/styles.css'
590
794
  ### 通用的「视图设置」按钮
591
795
 
592
796
  ```jsx
593
- // 不要这样写
594
- <Button>视图设置</Button>
797
+ // 不要这样写 —— 自己拼一个设置按钮,名字还是通用的
798
+ <SystemButton>视图设置</SystemButton>
799
+ <SystemButton>自定义</SystemButton>
595
800
 
596
- // 要这样写 —— 按当前呈现方式命名
597
- <Button>列设置</Button> {/* DataTable */}
598
- <Button>看板设置</Button> {/* KanbanBoard */}
801
+ // 要这样写 —— 交给工具栏,它按当前呈现方式命名
802
+ <ApplicationQueryToolbar presentation="DataTable" onPresentationSettings={openColumns} /> {/* 列设置 */}
803
+ <ApplicationQueryToolbar presentation="KanbanBoard" onPresentationSettings={openBoard} /> {/* 看板设置 */}
599
804
  ```
600
805
 
601
- 呈现设置是一个*概念*,不是一个按钮名。按钮必须按当前呈现方式命名:
602
- `列设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
806
+ 呈现设置是一个*概念*,不是一个按钮名。工具栏的设置按钮按 GAP Design kit 是 32×32 纯图标,
807
+ 名字落在可访问名与悬停提示上,必须按当前呈现方式命名:
808
+ `列设置` / `列表设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
603
809
 
604
810
  ### 六种数据状态共用一句话
605
811
 
@@ -610,9 +816,11 @@ import '@moheng-design/ui/styles.css'
610
816
  // 要这样写 —— 成因不同,用户的下一步动作也不同
611
817
  <ApplicationDataDisplay
612
818
  state={state}
613
- empty={<Empty title="当前视角下无数据" description="切换业务视图或调整筛选条件" />}
614
- noPermission={<Empty title="没有查看权限" description="请联系管理员申请" />}
615
- error={<Empty title="加载失败" description="请稍后重试" />}
819
+ empty={filtered
820
+ ? <Empty title="没有符合当前筛选条件的记录" action={<SystemButton onClick={resetFilters}>清除筛选</SystemButton>} />
821
+ : <Empty title="当前视图下还没有记录" action={<SystemButton onClick={create}>新建</SystemButton>} />}
822
+ noPermission={<Empty title="无权查看本模块" description="联系本模块管理员开通" />}
823
+ error={<Empty title="加载失败" description="服务暂时不可用,可重试" />}
616
824
  />
617
825
  ```
618
826
 
@@ -631,7 +839,7 @@ Loading / Empty / Error / No Permission / Not Found / Partial Failure
631
839
  <ScrollArea horizontal>…</ScrollArea>
632
840
  ```
633
841
 
634
- Content Canvas 是页面唯一的主垂直滚动权持有者。
842
+ 页面级纵向滚动持有者每页只有一个:结果集页面是 `ApplicationDataDisplay` 的主体,其余页面是 Content Canvas。
635
843
  `ScrollArea` 与 `MessageScroller` 只用于正交方向或局部有界的溢出,且必须给出高度。
636
844
 
637
845
  ### 用 Emoji 或系统字符代替图标