@moheng-design/ui-skill 3.0.0 → 3.1.1

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 CHANGED
@@ -81,7 +81,9 @@ export default { plugins: moheng.plugins, rules: moheng.consumer }
81
81
  三条命令的分工是同一句话:**数字由命令算,技能只解释。** `audit` 用 `migration` 档跑
82
82
  ESLint 并按规则 / 文件聚合,写 `moheng-audit.json`;`feedback` 扫对本库规则的
83
83
  `eslint-disable` 与 `TODO(moheng)` 标记,写 `moheng-feedback.md` 草稿;`upgrade` 比对
84
- 新旧两份 `contracts.json`,写 `moheng-upgrade.md`。三者都不改源文件,也不自动提交任何东西。
84
+ 新旧两份 `contracts.json`(组件 props 与同文件子类型的字段),写 `moheng-upgrade.md`。三者都不改源文件,也不自动提交任何东西。
85
+ 命令行只有「一个参数都不带」时才落到缺省的 `install`;`-h` / `--help` 只打印用法,
86
+ 带了参数却没有命令名、或带了该命令不认识的参数时报错退出,不执行任何有写入副作用的命令。
85
87
 
86
88
  附属技能的手写稿自带 frontmatter,正文用 `<!-- @generated: xxx -->` 占位符引用生成数据
87
89
  (版本号、规则数、autofix 规则清单、未强制约束表、五层模型字段、Module 组件清单、
@@ -191,7 +193,7 @@ SKILL.md 头部写死了版本号与校验指令,agent 读到版本不一致
191
193
  | `pnpm generate` | 生成 `generated/` 全部产物 |
192
194
  | `pnpm check:generate` | 只校验不落盘,供 CI 用 |
193
195
  | `pnpm extract` | 只跑契约提取,供排查用 |
194
- | `pnpm test` | 四份测试共 180 条:生成器负向 25 条 + lint 行为 135 条 + 命令行为 20 条 |
196
+ | `pnpm test` | 四份测试共 191 条:生成器负向 26 条 + lint 行为 135 条 + 命令行为 30 条 |
195
197
 
196
198
  ### 生成器必须能失败
197
199
 
@@ -206,7 +208,7 @@ SKILL.md 头部写死了版本号与校验指令,agent 读到版本不一致
206
208
  7. 手写文件在,但内容为空
207
209
  8. `anti-patterns.md` 的成对反例少于 8 组,或 `canvas-model.md` 未写全五层模型的五个字段名
208
210
  9. 契约的 JSDoc 里出现 Emoji(组件、prop、辅助类型及其成员四层全查)
209
- 10. 技能族:`unenforced.md` 没有一行完整的表行,或某份技能稿缺 frontmatter、引用未知占位符、与主技能重名
211
+ 10. 技能族:`unenforced.md` 没有一行完整的表行,或某份技能稿缺 frontmatter、引用未知占位符、代码块未闭合或闭合标记后跟正文、与主技能重名
210
212
 
211
213
  第 1 条尤其重要:组件加进去了、类型也导出了、构建也过了,唯独 Skill 不知道它,
212
214
  而**没有任何环节会报错** —— agent 就当那个组件不存在。
@@ -221,7 +223,7 @@ U+FE0F —— 跟在 `⚠` 后构成 emoji 呈现的形态 —— 两份对外
221
223
  另外两份只查文件在不在。实测把它们清空后生成器照样退出 0,SKILL.md 从 39.4 KB 缩到 26.6 KB,
222
224
  「五层 Canvas 模型」与「反例」两整节只剩空标题。**文件在而内容没了,与文件不在等价。**
223
225
 
224
- `test/generate.negative.mjs` 逐条制造上述违规并断言生成器确实失败,共 25 条(含 1 条正向哨兵)。
226
+ `test/generate.negative.mjs` 逐条制造上述违规并断言生成器确实失败,共 26 条(含 1 条正向哨兵)。
225
227
  **一个从不失败的校验器等于没有校验,而它失败与否看不出来** —— 正向跑一次永远是绿的。
226
228
 
227
229
  另两份是 lint 行为测试 —— `test/eslint-rules.test.mjs` 88 条、`test/stylelint-rules.test.mjs` 47 条。
package/bin/cli.js CHANGED
@@ -11,25 +11,76 @@
11
11
  * 算数。数字由命令算、agent 只解释 —— 这是 §1.4「Skill 是引导,工具才是事实」在
12
12
  * 这几个技能上的落法。
13
13
  *
14
- * 命令本体各在 bin/lib/ 下一个文件。本文件只做分发。
14
+ * 命令本体各在 bin/lib/ 下一个文件。本文件只做分发与参数校验。
15
+ *
16
+ * ── 只有「什么都不带」才落到 install ──────────────────────────────────
17
+ *
18
+ * 此前命令取「第一个不以 - 开头的参数」,取不到就执行 install。于是 `--help` 也取不到、
19
+ * 也执行了 install,在当前目录写出整套 .claude/skills/(业财平台 round-02 工具链问题,
20
+ * 在 apps/web 下误触发过一次)。缺省命令有写入副作用,因此现在的规则是:
21
+ *
22
+ * - `-h` / `--help` 打印用法后退出,不执行任何命令
23
+ * - 一个参数都没有时执行 install(README 与 bootstrap 技能写的就是这种用法)
24
+ * - 带了参数却没有命令名、或带了该命令不认识的参数时报错退出,不执行任何命令
15
25
  */
16
26
 
17
- const argv = process.argv.slice(2)
18
- const command = argv.find((a) => !a.startsWith('-')) ?? 'install'
19
- const rest = argv.filter((a) => a !== command)
27
+ const USAGE = [
28
+ '用法:npx @moheng-design/ui-skill <命令> [选项]',
29
+ '',
30
+ ' install [--force | -f] 把 SKILL.md 与附属技能拷进 .claude/skills/(不带任何参数时的缺省命令)',
31
+ ' audit 存量项目审计,写出 moheng-audit.json',
32
+ ' feedback 收集绕过与标记,写出 moheng-feedback.md 草稿',
33
+ ' upgrade --from <旧契约> [--to <新契约>] 契约差异,写出 moheng-upgrade.md',
34
+ '',
35
+ ' -h, --help 打印本说明,不执行任何命令',
36
+ ].join('\n')
20
37
 
38
+ /** 每个命令认得的开关与带值选项。带值选项后面那个参数是它的值,不当作命令名或多余参数。 */
21
39
  const COMMANDS = {
22
- install: () => import('./lib/install.mjs'),
23
- audit: () => import('./lib/audit.mjs'),
24
- feedback: () => import('./lib/feedback.mjs'),
25
- upgrade: () => import('./lib/upgrade.mjs'),
40
+ install: { load: () => import('./lib/install.mjs'), flags: ['--force', '-f'], valued: [] },
41
+ audit: { load: () => import('./lib/audit.mjs'), flags: [], valued: [] },
42
+ feedback: { load: () => import('./lib/feedback.mjs'), flags: [], valued: [] },
43
+ upgrade: { load: () => import('./lib/upgrade.mjs'), flags: [], valued: ['--from', '--to'] },
26
44
  }
27
45
 
28
- if (!COMMANDS[command]) {
29
- console.error(`未知命令 ${command}。可用命令:${Object.keys(COMMANDS).join(' / ')}`)
46
+ const ALL_VALUED = new Set(Object.values(COMMANDS).flatMap((c) => c.valued))
47
+
48
+ const fail = (message) => {
49
+ console.error(`✗ ${message}\n\n${USAGE}`)
30
50
  process.exit(1)
31
51
  }
32
52
 
33
- const { run } = await COMMANDS[command]()
53
+ const argv = process.argv.slice(2)
54
+
55
+ if (argv.includes('-h') || argv.includes('--help')) {
56
+ console.log(USAGE)
57
+ process.exit(0)
58
+ }
59
+
60
+ /* 位置参数:不以 - 开头、且不是某个带值选项的值。第一个是命令名,其余都是多余参数。 */
61
+ const positionals = argv.filter((a, i) => !a.startsWith('-') && !ALL_VALUED.has(argv[i - 1]))
62
+
63
+ if (argv.length > 0 && positionals.length === 0) {
64
+ fail(`缺少命令名(收到 ${argv.join(' ')})。只有不带任何参数时才执行缺省的 install。`)
65
+ }
66
+
67
+ const command = positionals[0] ?? 'install'
68
+ const spec = COMMANDS[command]
69
+ if (!spec) fail(`未知命令 ${command}。可用命令:${Object.keys(COMMANDS).join(' / ')}`)
70
+
71
+ if (positionals.length > 1) fail(`多余的参数:${positionals.slice(1).join(' ')}`)
72
+
73
+ argv.forEach((a, i) => {
74
+ if (!a.startsWith('-')) return
75
+ if (spec.flags.includes(a)) return
76
+ if (spec.valued.includes(a)) {
77
+ if (argv[i + 1] === undefined || argv[i + 1].startsWith('-')) fail(`${a} 后面缺少取值`)
78
+ return
79
+ }
80
+ fail(`${command} 不认识参数 ${a}`)
81
+ })
82
+
83
+ const rest = argv.filter((a) => a !== command)
84
+ const { run } = await spec.load()
34
85
  const code = await run(rest)
35
86
  process.exit(code ?? 0)
@@ -7,6 +7,9 @@
7
7
  * --to <新版 contracts.json> 可选,默认本包 generated/contracts.json
8
8
  *
9
9
  * 比四层:组件增删、prop 增删与必填翻转、枚举值增删、类型与弃用标记的变化。
10
+ * 子类型(同一契约文件里的非 Props 接口,如 `TableColumn`、`Metric`、`DetailSection`)的
11
+ * 字段同样比:增删、必填翻转、类型变化。此前只比组件顶层 props,2.0.0 → 3.0.0 的
12
+ * `TableColumn.fixed`、`Metric.description` 都没进报告(业财平台 round-02 工具链问题)。
10
13
  * 契约是唯一事实来源(§6.2),差异从它算,不从 CHANGELOG 抄。
11
14
  */
12
15
 
@@ -35,6 +38,22 @@ export async function run(argv) {
35
38
  const before = load(fromPath)
36
39
  const after = load(toPath)
37
40
 
41
+ /* 子类型按接口名去重:同一文件的几个组件共享同一组 helpers(metrics.ts 的 Metric 挂在五个组件下),
42
+ * 逐组件比会把同一处变化报五遍。记下第一个挂载它的组件,报告里写明去哪个组件的文档查。 */
43
+ const helpersOf = (components) => {
44
+ const map = new Map()
45
+ for (const c of components.values()) {
46
+ for (const h of c.helpers ?? []) if (!map.has(h.name)) map.set(h.name, { ...h, owner: c.name })
47
+ }
48
+ return map
49
+ }
50
+ const helpersBefore = helpersOf(before)
51
+ const helpersAfter = helpersOf(after)
52
+ /* 旧版 contracts.json 一个子类型都没记时,子类型差异无从算起 —— 不比,并在报告里写明,
53
+ * 免得把全部子类型误报成「新增」 */
54
+ const compareHelpers = helpersBefore.size > 0
55
+ const code = (s) => `\`${s}\``
56
+
38
57
  const lines = ['# @moheng-design/ui 契约差异', '', `- 旧:${fromPath}`, `- 新:${toPath}`, '']
39
58
  let changes = 0
40
59
  const section = (title, items) => {
@@ -94,6 +113,36 @@ export async function run(argv) {
94
113
  }
95
114
  }
96
115
 
116
+ if (compareHelpers) {
117
+ for (const [hname, next] of helpersAfter) {
118
+ const prev = helpersBefore.get(hname)
119
+ if (!prev) continue
120
+ const where = `(${next.owner} 的子类型)`
121
+ const prevFields = new Map(prev.members.map((m) => [m.name, m]))
122
+ const nextFields = new Map(next.members.map((m) => [m.name, m]))
123
+ for (const f of prevFields.keys()) {
124
+ if (!nextFields.has(f)) removedProps.push(`${code(`${hname}.${f}`)}${where}`)
125
+ }
126
+ for (const [f, nf] of nextFields) {
127
+ const pf = prevFields.get(f)
128
+ const id = code(`${hname}.${f}`)
129
+ if (!pf) {
130
+ if (nf.required) requiredFlips.push(`${id} 为新增的必填字段${where}`)
131
+ else addedProps.push(`${id}${where}`)
132
+ continue
133
+ }
134
+ if (!pf.required && nf.required) requiredFlips.push(`${id} 变为必填${where}`)
135
+ /* 必填变可选不破坏旧代码,但读取方可能依赖它恒有值(DetailSection.title 那类),列进新增一节提醒 */
136
+ if (pf.required && !nf.required) addedProps.push(`${id} 变为可选${where}`)
137
+ if (pf.type !== nf.type) retyped.push(`${id}:${code(pf.type)} → ${code(nf.type)}${where}`)
138
+ }
139
+ }
140
+ section(
141
+ '删除的子类型(引用处必须改)',
142
+ [...helpersBefore.keys()].filter((n) => !helpersAfter.has(n)).map((n) => `${code(n)}(原属 ${helpersBefore.get(n).owner})`),
143
+ )
144
+ }
145
+
97
146
  section('删除的 prop(props-whitelist 会报)', removedProps)
98
147
  section('变为必填的 prop(引用处必须补)', requiredFlips)
99
148
  section('删除的枚举值(prop-enum 会报)', removedValues)
@@ -102,7 +151,16 @@ export async function run(argv) {
102
151
  section('标为弃用的 prop(下一次升级前迁走)', deprecated)
103
152
  section('新增的 prop', addedProps)
104
153
  section('新增的枚举值', addedValues)
154
+ if (compareHelpers) {
155
+ section(
156
+ '新增的子类型',
157
+ [...helpersAfter.keys()].filter((n) => !helpersBefore.has(n)).map((n) => `${code(n)}(${helpersAfter.get(n).owner})`),
158
+ )
159
+ }
105
160
 
161
+ if (!compareHelpers) {
162
+ lines.push('> 旧版 contracts.json 没有记录子类型(列定义、指标项、分节这类接口),本报告只比较了组件顶层 props;子类型的变化请读 reference.md。', '')
163
+ }
106
164
  if (changes === 0) lines.push('两份契约没有差异。', '')
107
165
 
108
166
  const outPath = join(process.cwd(), 'moheng-upgrade.md')
@@ -7,7 +7,7 @@ description: 用 @moheng-design/ui 写 React 界面时加载。含 94 个组件
7
7
 
8
8
  # @moheng-design/ui 使用指南
9
9
 
10
- 适用版本:v3.0.0
10
+ 适用版本:v3.1.1
11
11
 
12
12
  > 请先确认项目 `package.json` 中 `@moheng-design/ui` 的版本与本文件声明一致。
13
13
  > 若不一致,以 `node_modules/@moheng-design/ui-skill/generated/reference.md` 为准 ——
@@ -46,20 +46,20 @@ import '@moheng-design/ui/styles.css'
46
46
 
47
47
  ### 可用的 token
48
48
 
49
- 组件的全部颜色、尺度与层级由 CSS 自定义属性表达,共 389 条。
49
+ 组件的全部颜色、尺度与层级由 CSS 自定义属性表达,共 396 条。
50
50
  覆盖样式、与组件对齐尺度时读它们,**不得写字面色值、尺寸、圆角、间距**。
51
51
 
52
- 消费方可用的是 `--application-*`(101 条)与 `--ui-*`(145 条),共 246 条。
53
- `--ds-*`(143 条)是 Foundation 内部实现,不构成公开接口,
52
+ 消费方可用的是 `--application-*`(103 条)与 `--ui-*`(145 条),共 248 条。
53
+ `--ds-*`(148 条)是 Foundation 内部实现,不构成公开接口,
54
54
  任意小版本都可能改动。例外是上一节的换肤入口 `--ds-color-theme-primary`,
55
55
  与只读的焦点环几何 `--ds-focus-ring-width` / `--ds-focus-ring-offset`。
56
56
 
57
57
  命名形如 `--<层>-<分组>-<项>`。消费方可用的分组与条数:
58
58
 
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`
59
+ - **`--application-*`**(103 条)—— `categorical` 20、`radius` 10、`font-size` 6、`line-height` 6、`space` 6、`button` 4、`font-weight` 4、`form-dialog` 3;另有 44 条不带分组段,形如 `--application-canvas`
60
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
61
61
 
62
- 389 条 token 的完整名值表见
62
+ 396 条 token 的完整名值表见
63
63
  `node_modules/@moheng-design/ui-skill/generated/reference.md` 的「Token 全表」一节 ——
64
64
  该文件随包分发,不会过期。两层各自的取用规则见下文「组合约定」。
65
65
 
@@ -112,13 +112,13 @@ import '@moheng-design/ui/styles.css'
112
112
 
113
113
  | 组件 | 用途 | 常用 props |
114
114
  |---|---|---|
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) |
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 / eye / file-text / funnel / info / kanban / layout-grid / list / message-square / minus / paperclip / pencil / plus / refresh-cw / search / settings / shield-check / sliders-horizontal / trash-2 / triangle-alert / upload / x)、`size`(14 / 16 / 18 / 20 / 24) |
116
116
 
117
117
  ### Foundation · actions(4)
118
118
 
119
119
  | 组件 | 用途 | 常用 props |
120
120
  |---|---|---|
121
- | `Button` | Foundation 按钮 —— 按钮排版、几何、圆角与基础交互的唯一 Foundation Owner。 | `children`*、`variant`(primary / secondary / outline / ghost / destructive / destructive-outline / link)、`size`(xs / sm / default / lg) |
121
+ | `Button` | Foundation 按钮 —— 按钮排版、几何、圆角与基础交互的唯一 Foundation Owner。 | `children`*、`variant`(primary / secondary / outline / ghost / ghost-accent / destructive / destructive-outline / link)、`size`(xs / sm / default / lg) |
122
122
  | `ButtonGroup` | 把一组相关 Button 合并为一个分段控件或间隔簇。 | `orientation`(horizontal / vertical) |
123
123
  | `Toggle` | 单个两态可按下控件 —— 用于一个独立的格式或显示开关。 | `size`(sm / default / lg) |
124
124
  | `ToggleGroup` | 一组分段式开关,用于**一个局部显示选择** —— 密度、对齐方式、局部视图标记。 | `items`*、`type`(single / multiple)、`size`(sm / default / lg) |
@@ -130,12 +130,12 @@ import '@moheng-design/ui/styles.css'
130
130
  | `Calendar` | 月格日期选择器,**周一为一周起始**(一…日)。 | — |
131
131
  | `Checkbox` | 独立的布尔选择,16px 方形,4px 圆角,选中时填充强调色。 | — |
132
132
  | `Combobox` | 输入即筛选的单选控件 —— 选项多到不便逐条扫视,但又不构成一次数据查询时使用。 | `options`* |
133
- | `DateInput` | 单个日期的录入控件:与 `Input` 同高同壳(32px、12px 圆角、1px 描边),右侧带 16px 日历图标,点击弹出 `Calendar` 月格,选中即回填并收起。 | — |
133
+ | `DateInput` | 单个日期的录入控件:与 `Input` 同高同壳(32px、12px 圆角、1px 描边),右侧带 16px 日历图标(文字1,与值间隔 4,GAP Design kit「表单/选择」),点击弹出 `Calendar` 月格,选中即回填并收起。 | — |
134
134
  | `Field` | 表单行:标签 + 控件 + 一行说明**或**错误。 | — |
135
135
  | `Input` | 单行文本控件。 | — |
136
136
  | `InputGroup` | 单一焦点壳,包裹前置/后置附加物与一个控件 —— 图标、单位、提交按钮。 | — |
137
137
  | `InputOTP` | 定长验证码输入 —— 每个字符一个 40px 方框,光标自动前进。 | — |
138
- | `Label` | 独立控件标签,14/20 字号,色值 `--ds-color-text-label`。 | — |
138
+ | `Label` | 独立控件标签,14/20 字号,文字2(`--ds-color-text-secondary`,GAP Design kit「字段名称」)。 | — |
139
139
  | `NativeSelect` | 平台原生 `<select>`,套用已登记的外壳样式。 | `options`* |
140
140
  | `RadioGroup` | 在 2–5 个可见选项中互斥择一,用于表单与筛选面板。 | `items`*、`orientation`(vertical / horizontal) |
141
141
  | `Select` | 自绘单选下拉 —— 表单与筛选行中的默认选择控件。 | `options`* |
@@ -209,14 +209,14 @@ import '@moheng-design/ui/styles.css'
209
209
  | `SearchField` | 共享的紧凑搜索入口 —— **产品内每一处纯文本搜索**: 查询工具栏、目录搜索、人员与文件选择器。 | `ariaLabel`* |
210
210
  | `SidebarAppLinkButton` | 应用快捷入口 —— 从工作台侧栏或应用切换器跳转到另一个应用。 | — |
211
211
  | `SidebarRailButton` | 工作台菜单栏条目 —— 56px 宽的列内,图标在上、标签在下。 | — |
212
- | `SystemButton` | 应用语义按钮 —— **整个产品的默认动作按钮**。 | `intent`(primary / secondary / quiet / link / destructive / destructive-outline)、`size`(default / compact / sm) |
212
+ | `SystemButton` | 应用语义按钮 —— **整个产品的默认动作按钮**。 | `intent`(primary / secondary / quiet / quiet-accent / link / destructive / destructive-outline)、`size`(default / compact / sm) |
213
213
 
214
214
  ### Application Module · navigation(5)
215
215
 
216
216
  | 组件 | 用途 | 常用 props |
217
217
  |---|---|---|
218
218
  | `ApplicationModuleSwitcher` | 应用二级导航的**左半部分** —— 你在哪个模块,以及如何切换。 | — |
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) |
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 / eye / file-text / funnel / info / kanban / layout-grid / list / message-square / minus / paperclip / pencil / plus / refresh-cw / search / settings / shield-check / sliders-horizontal / trash-2 / triangle-alert / upload / x)、`activeAction`(messages / todos / overview / risk / settings) |
220
220
  | `ApplicationSecondaryNavigation` | `APPLICATION.SECONDARY_NAV` —— GAP Design kit「应用二级导航」,外壳的最后一带 (基础版第二带、集团版第三带)。 | — |
221
221
  | `GlobalSidebar` | 工作台左侧 72px 菜单栏,由 `SidebarRailButton` 构成。 | — |
222
222
  | `TopNavigationPrimaryBar` | `PLATFORM.TOP_USER_BAR` —— GAP Design kit「集团顶部导航」,**只在集团版外壳出现** (本带 + 应用一级 + 应用二级,共 144)。 | — |
@@ -410,6 +410,18 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
410
410
  | L4 数据控制 | `dataControl` | search / filters / sort / pagination / appliedFilterTags |
411
411
  | L5 数据呈现 | `dataPresentation` | `DataTable` / `RecordList` / `CardList` / `KanbanBoard` / `Calendar` / `Chart` / `Timeline` |
412
412
 
413
+ 结果集页面里有两种层的内容「只有一种」的情形,写法固定,不算缺层:
414
+
415
+ - **单视角**:结果集没有多个稳定工作视角时(需求写明「无页签」),`businessView` 这一层的取值是
416
+ 「单视角」。不传 `businessViews` / `businessView` / `onBusinessViewChange`,工具栏第一行不渲染;
417
+ 不得为凑出一行虚构一个只有「全部」的标签。这一层没有可写的 prop,是五层里唯一只在页面的
418
+ 五层声明注释里记下取值(`businessView: 单视角`)的情形。
419
+ - **只有分页**:结果集没有搜索、筛选、排序时,`dataControl` 只含 pagination。不渲染
420
+ `ApplicationQueryToolbar`(它的第二行恒有搜索框,不得为凑工具栏放一个用不上的搜索),
421
+ `ApplicationPageLayoutContainer` 不传 `dataControl`,`ListTablePagination` 照常进
422
+ `ApplicationDataDisplay` 的 `pagination`;`dataPresentation` 只落在 `ApplicationDataDisplay` 的
423
+ `presentation`。这种页面通常也是单视角。
424
+
413
425
  `DETAIL` 与 `COMPOSITE` **不是**页面模式,是特殊物理结构资产。
414
426
  `Embedded` 是 `integrationMode`,不是页面模式。
415
427
 
@@ -457,7 +469,8 @@ WORKBENCH ApplicationPageLayoutContainer pageType="WORKBENCH"
457
469
  └─ children 分区导航 GlobalSidebar + 面板网格(指标区、待办、动态、应用入口)
458
470
 
459
471
  DETAIL ApplicationPageLayoutContainer pageType="DETAIL"
460
- ├─ header ApplicationPageHeader(breadcrumb 返回来源列表;对象级动作放 actions)
472
+ ├─ header ApplicationPageHeader(onBack 回到来源列表;只有要展示多级路径时才改用 breadcrumb,
473
+ │ 两者不得同时传;对象级动作放 actions)
461
474
  └─ children ApplicationRecordDetailBody(分节;分节级动作放分节标题行)
462
475
 
463
476
  编辑器 ApplicationPageLayoutContainer pageType 随所属业务
@@ -540,6 +553,15 @@ DETAIL ApplicationPageLayoutContainer pageType="DETAIL"
540
553
  业务记录的占位符(07 · C-8):`成员 A` / `成员 B` / `成员 C`(人名)· `对象 A` / `对象 B` / `对象 C`(业务对象名)·
541
554
  `编号 0001` / `编号 0002`(记录编号,四位补零递增)。同类条目按字母或序号顺延,不得换用真实人名。
542
555
 
556
+ 未登记的类型按两条规则生成,同样逐字复用、按字母顺延:
557
+
558
+ - **名称类**写「类型名 + 空格 + 字母」:`部门 A` / `部门 B`(组织部门)· `城市 A`(地区)· `规格 A`(规格型号)·
559
+ `项目 A`(项目)。不得借用 `对象 A` 充当部门或城市 —— 读者分不清那一列是什么。
560
+ - **定长编码类**按真实位数写,用 0 补齐、末位按序号顺延,让列宽与真实数据一致:
561
+ `913100000000000001` / `913100000000000002`(统一社会信用代码 / 纳税人识别号,18 位)·
562
+ `6222000000000001`(银行卡号,16 位)。
563
+ 不得用随手敲的数字串,也不得用真实存在的编码。
564
+
543
565
  `模块1` / `模块2` 作为标签文案被明令禁止。
544
566
 
545
567
 
@@ -627,7 +649,8 @@ Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
627
649
  UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`,不写 `你没有权限`。
628
650
  表单与说明文案(02 §8):校验错误写字段名与不满足的条件(`任务名称不能为空`);
629
651
  确认说明写后果(`删除后 3 条记录不可恢复`),不写请求;占位文字写示例或范围
630
- (`例如:季度巡检记录`),不写指令;无权限的出路点明找谁(`联系本模块管理员开通`)。
652
+ (`例如:季度巡检记录`),不写指令 —— 唯一的例外是组件内置的 `ListTablePagination` 跳页框,
653
+ 它照 GAP Design kit 写「请输入」,调用方不得仿照;无权限的出路点明找谁(`联系本模块管理员开通`)。
631
654
 
632
655
  > 逐组件的组合约定(94 个章节:何时使用、何时改用其他组件、禁止与使用边界)
633
656
  > 见 `node_modules/@moheng-design/ui-skill/generated/reference.md`。