@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.
- package/README.md +11 -4
- package/bin/lib/audit.mjs +21 -5
- package/bin/lib/feedback.mjs +20 -3
- package/bin/lib/install.mjs +6 -2
- package/bin/lib/upgrade.mjs +35 -8
- package/generated/SKILL.md +291 -83
- package/generated/contracts.json +2118 -703
- package/generated/plugin-data.js +512 -47
- package/generated/reference.md +1299 -513
- package/generated/rules.json +525 -48
- package/generated/skills/moheng-ui-audit/SKILL.md +16 -5
- package/generated/skills/moheng-ui-bootstrap/SKILL.md +10 -6
- package/generated/skills/moheng-ui-feedback/SKILL.md +8 -3
- package/generated/skills/moheng-ui-page/SKILL.md +37 -13
- package/generated/skills/moheng-ui-review/SKILL.md +8 -5
- package/generated/skills/moheng-ui-upgrade/SKILL.md +6 -4
- package/generated/unenforced.json +20 -5
- package/handwritten/anti-patterns.md +45 -25
- package/handwritten/canvas-model.md +189 -15
- package/handwritten/conventions.md +330 -194
- package/handwritten/skills/audit.md +9 -1
- package/handwritten/skills/bootstrap.md +8 -4
- package/handwritten/skills/feedback.md +6 -1
- package/handwritten/skills/page.md +33 -9
- package/handwritten/skills/upgrade.md +5 -3
- package/handwritten/unenforced.md +6 -3
- package/package.json +3 -3
package/generated/SKILL.md
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: moheng-ui
|
|
3
|
-
description: 用 @moheng-design/ui 写 React 界面时加载。含
|
|
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
|
-
适用版本:
|
|
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()`
|
|
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 自定义属性表达,共
|
|
49
|
+
组件的全部颜色、尺度与层级由 CSS 自定义属性表达,共 389 条。
|
|
49
50
|
覆盖样式、与组件对齐尺度时读它们,**不得写字面色值、尺寸、圆角、间距**。
|
|
50
51
|
|
|
51
|
-
消费方可用的是 `--application-*`(
|
|
52
|
-
`--ds-*`(
|
|
53
|
-
|
|
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-*`**(
|
|
58
|
-
- **`--ui-*`**(
|
|
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
|
-
|
|
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>` | `<
|
|
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
|
|
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
|
-
|
|
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
|
|
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(
|
|
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` | 键盘优先的命令面板 ——
|
|
152
|
+
| `Command` | 键盘优先的命令面板 —— 以 `dialog` 形态作为全局搜索与执行入口。 | `groups`* |
|
|
150
153
|
| `ContextMenu` | 内容区域上的右键菜单 —— 行、卡片、看板块。 | `items`* |
|
|
151
154
|
| `Menubar` | 桌面风格的水平菜单条,用于编辑器型工作面 —— 报表设计器、看板配置器。 | `menus`* |
|
|
152
|
-
| `NavigationMenu` | 水平导航,条目可展开富内容面板。 | `items
|
|
153
|
-
| `Pagination` |
|
|
154
|
-
| `Sidebar` | Content Canvas 内部的垂直导航面 ——
|
|
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(
|
|
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` | 从任意边缘滑出的面板,用于**辅助性内容** ——
|
|
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(
|
|
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 /
|
|
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` ——
|
|
215
|
-
| `ApplicationSecondaryNavigation` | `APPLICATION.SECONDARY_NAV` ——
|
|
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` ——
|
|
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
|
-
|
|
289
|
+
固定骨架,**没有左侧全局栏**。导航带永不滚动。几何以 GAP Design kit「框架结构」为准,外壳有两种形态:
|
|
290
|
+
|
|
291
|
+
| 形态 | 带(自上而下) | Standard 总高 | Compact 总高 |
|
|
292
|
+
|---|---|---:|---:|
|
|
293
|
+
| 基础版 | 应用一级 + 应用二级 | 96px | 80px |
|
|
294
|
+
| 集团版 | 集团顶部 + 应用一级 + 应用二级 | 144px | 120px |
|
|
285
295
|
|
|
286
296
|
| 带 | 组件 | Standard | Compact |
|
|
287
297
|
|---|---|---:|---:|
|
|
288
|
-
|
|
|
289
|
-
| 应用一级导航 `APPLICATION.PRIMARY_NAV` | `ApplicationPrimaryNavigation` |
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
<
|
|
465
|
-
<
|
|
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
|
-
// 要这样写 ——
|
|
468
|
-
<
|
|
655
|
+
// 要这样写 —— 意图与形状是两根轴,iconOnly 控制形状
|
|
656
|
+
<SystemButton intent="quiet" iconOnly aria-label="刷新"><Icon name="refresh-cw" size={16} /></SystemButton>
|
|
469
657
|
```
|
|
470
658
|
|
|
471
|
-
`
|
|
472
|
-
`size` 只有 `
|
|
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
|
-
<
|
|
699
|
+
<SystemButton onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}>
|
|
497
700
|
|
|
498
701
|
// 要这样写 —— 什么都不写,hover 已由 CSS 伪类实现
|
|
499
|
-
<
|
|
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 {
|
|
768
|
+
import { SystemButton } from '@moheng-design/ui/dist/components/application-atomic/SystemButton.js'
|
|
565
769
|
|
|
566
770
|
// 要这样写
|
|
567
|
-
import {
|
|
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 {
|
|
784
|
+
import { SystemButton } from '@moheng-design/ui'
|
|
581
785
|
|
|
582
786
|
// 要这样写 —— 应用入口引一次即可
|
|
583
|
-
import {
|
|
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
|
-
<
|
|
797
|
+
// 不要这样写 —— 自己拼一个设置按钮,名字还是通用的
|
|
798
|
+
<SystemButton>视图设置</SystemButton>
|
|
799
|
+
<SystemButton>自定义</SystemButton>
|
|
595
800
|
|
|
596
|
-
// 要这样写 ——
|
|
597
|
-
<
|
|
598
|
-
<
|
|
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={
|
|
614
|
-
|
|
615
|
-
|
|
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 或系统字符代替图标
|