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