@apexhub/apex-ui-skill 0.0.0-stage → 1.2.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/LICENSE +21 -0
- package/README.md +11 -2
- package/apex-ui/SKILL.md +135 -0
- package/apex-ui/evals/evals.json +78 -0
- package/apex-ui/references/audit-npm.md +471 -0
- package/apex-ui/references/audit.md +38 -0
- package/apex-ui/references/conventions.md +81 -0
- package/apex-ui/references/design-rules.md +188 -0
- package/apex-ui/references/pages.md +289 -0
- package/apex-ui/references/pitfalls.md +55 -0
- package/apex-ui/references/rewrite-prefix.md +55 -0
- package/apex-ui/references/selection.md +111 -0
- package/apex-ui/references/setup.md +51 -0
- package/apex-ui/references/source-install.md +146 -0
- package/apex-ui/references/theming.md +56 -0
- package/apex-ui/references/troubleshooting.md +24 -0
- package/apex-ui/references/update.md +93 -0
- package/apex-ui/rules/agents.md +27 -0
- package/apex-ui/rules/claude.md +27 -0
- package/apex-ui/scripts/report-usage.mjs +229 -0
- package/apex-ui/skill.json +49 -0
- package/package.json +27 -3
- package/scripts/install-skills.mjs +226 -0
- package/scripts/lib/detect.mjs +109 -0
- package/scripts/lib/discover.mjs +30 -0
- package/scripts/lib/install.mjs +159 -0
- package/scripts/lib/logo.mjs +33 -0
- package/scripts/lib/parse-args.mjs +56 -0
- package/scripts/lib/prompt.mjs +158 -0
- package/scripts/lib/targets.mjs +78 -0
- package/scripts/lib/ui.mjs +340 -0
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
# 界面规范:做出来的页面要符合 Apex UI 设计标准
|
|
2
|
+
|
|
3
|
+
> **本文件职责**:Apex UI 设计规范里和写页面有关的规则。新做页面、往页面里加一块内容之前读一遍;
|
|
4
|
+
> 做完按文末「交付前自查」过一遍。组件的具体属性仍以该组件的 `llm.txt` 为准。
|
|
5
|
+
|
|
6
|
+
## 怎么用这些规则
|
|
7
|
+
|
|
8
|
+
- 用户没说的地方按这里做,不用拿这些细节去问用户。
|
|
9
|
+
- 用户明确提了不一样的要求,照用户说的做。
|
|
10
|
+
- 规则没写、又会影响用户看到的结果(数据口径、要不要二次确认、点了之后去哪)时,不要自己编:
|
|
11
|
+
选最简单、不多加行为的做法,做完用一句话告诉用户这里是你的假设。
|
|
12
|
+
- 不要加用户没要的功能:排序、行选择、批量操作、自动关闭、默认选中、点击跳转、自动提交。
|
|
13
|
+
|
|
14
|
+
## 整体观感
|
|
15
|
+
|
|
16
|
+
- 这是企业后台的风格:克制、以中性色和文字层级为主。不用渐变、发光、大阴影和装饰性颜色。
|
|
17
|
+
- 紫色品牌色只用于主操作、当前选中和当前导航,不当装饰用。
|
|
18
|
+
- 不要把每一块内容都包进 `Card`。表格、筛选区、连续阅读的内容直接放在页面上;只有内容需要作为
|
|
19
|
+
独立的信息单元(指标卡、摘要、可点击的条目)时才用 `Card`,不要卡片套卡片。
|
|
20
|
+
- 层次靠标题、间距和对齐来分,其次才是 `Divider` 和边框。
|
|
21
|
+
- 页面本身不出现横向滚动条;表格太宽时让表格自己横向滚动(`scroll.x`)。一个页面只有一个主要的
|
|
22
|
+
纵向滚动区域。
|
|
23
|
+
- 做完在亮色和暗色下各看一眼;只要求了一种主题时至少保证这一种正确。
|
|
24
|
+
|
|
25
|
+
## 颜色、间距、圆角、字号
|
|
26
|
+
|
|
27
|
+
自己写样式时一律用 Token,不写十六进制颜色和随手的像素值。设计稿里的名字和 CSS 变量一一对应:
|
|
28
|
+
`fill/neutral/primary` 就是 `var(--apex-fill-neutral-primary)`,`spacing/16` 就是
|
|
29
|
+
`var(--apex-spacing-16)`。变量不确定是否存在时到组件目录的 `theme/aliases.css` 里搜,不要编名字。
|
|
30
|
+
|
|
31
|
+
| 用途 | 可用的值 |
|
|
32
|
+
| --- | --- |
|
|
33
|
+
| 间距 `--apex-spacing-*` | 0、2、4、6、8、12、16、24、28、32、40、48 |
|
|
34
|
+
| 圆角 `--apex-radius-*` | 0、2、4、8、12、32、999 |
|
|
35
|
+
| 背景 | `--apex-fill-neutral-*`,品牌和语义色是 `--apex-fill-brand-*`、`-success-`、`-warning-`、`-error-` |
|
|
36
|
+
| 文字 | `--apex-text-neutral-primary`(正文)、`-secondary`(次要)、`-tertiary`(辅助)、`-disabled` |
|
|
37
|
+
| 边框 | `--apex-stroke-neutral-*` |
|
|
38
|
+
|
|
39
|
+
- 间距的用法:组件内部和紧挨着的元素用 8 或 12;同一组里的元素之间用 16;页面区块之间用 24 或更大。
|
|
40
|
+
不要全页都用同一个间距。
|
|
41
|
+
- 文字用 `Typography`,不自己设字号和字重:页面标题 `Typography.Title level={1}`(24px),区块标题
|
|
42
|
+
`level={2}`(18px)或 `level={3}`(16px),正文 14px,辅助说明 12px。不要为了塞下内容把字缩小。
|
|
43
|
+
- 阴影只属于浮层(`Modal`、`Drawer`、`Popover`、下拉面板),组件已经带好;不要给 `Card` 和普通容器
|
|
44
|
+
另加阴影。
|
|
45
|
+
- 状态不能只靠颜色表达,要配文字或图标。
|
|
46
|
+
|
|
47
|
+
## 按钮与操作
|
|
48
|
+
|
|
49
|
+
- 同一块操作区域只有一个主按钮,按操作的重要程度选类型:
|
|
50
|
+
|
|
51
|
+
| 操作 | 写法 |
|
|
52
|
+
| --- | --- |
|
|
53
|
+
| 这一块最重要的操作:新建、提交、保存、下一步 | `type="primary"` |
|
|
54
|
+
| 次要操作:取消、返回、导出、预览 | 默认类型(不传 `type`) |
|
|
55
|
+
| 表格行里的查看、编辑等 | `type="text"` 或 `type="link"`,或只有图标的按钮 |
|
|
56
|
+
| 删除、移除等不可恢复的操作 | `type="danger"` |
|
|
57
|
+
|
|
58
|
+
- 尺寸:页面上、表单里、弹窗和抽屉底部的按钮用默认尺寸;表格行里和紧凑的工具区用
|
|
59
|
+
`size="small"`。同一排按钮尺寸一致。不要用样式另改按钮的高度和内边距。
|
|
60
|
+
- 危险操作先用 `Modal.useModal()` 的确认框确认:写清楚操作的是哪个对象、有什么后果,主按钮写具体
|
|
61
|
+
动作(「删除」),不写「确定」。
|
|
62
|
+
- 提交过程中按钮传 `loading`,防止重复提交;不能操作时传 `disabled`。两者含义不同,不互相代替。
|
|
63
|
+
- 按钮按重要程度排列,按钮之间用统一间距,不用空格调位置。
|
|
64
|
+
- 只有图标的按钮必须有 `aria-label`,并用 `Tooltip` 说明用途。
|
|
65
|
+
- 按钮是用来执行动作的;单纯跳到另一个页面用链接或导航组件(或 `Button` 的 `href`)。
|
|
66
|
+
- 文案用明确的动词:「新建用户」「导出」,不用「确定」「操作」这种说不清的词。
|
|
67
|
+
|
|
68
|
+
## 表格
|
|
69
|
+
|
|
70
|
+
- 先想好列:每列是什么数据、怎么对齐。数量、金额、百分比 `align: 'right'`;编号、日期、状态和其他
|
|
71
|
+
文字靠左;操作列放最右边。
|
|
72
|
+
- 长文字用列的 `ellipsis` 截断(自带悬停显示全文),不换行撑高行,也不缩小字号。
|
|
73
|
+
- 状态列用 `Tag` 加文字,颜色按含义选:`success` 成功或正常,`warning` 需要关注,`error` 失败或
|
|
74
|
+
风险,`brand` 强调,`default` 中性。数值上涨不一定是好事,待处理也不一定是警告,按业务含义选。
|
|
75
|
+
- 分页:改每页条数后回到第一页;搜索或筛选条件变化后回到第一页;没有数据时不显示页码
|
|
76
|
+
(`hideOnSinglePage`)。页码、每页条数、总数要和真实请求一致。
|
|
77
|
+
- 加载中用 `Table` 的 `loading`;没有数据用自带的空状态(可用 `emptyText` 换文案);请求失败要显示
|
|
78
|
+
错误说明和「重试」按钮。**请求失败不能显示成空表格或 0。**
|
|
79
|
+
|
|
80
|
+
## 搜索与筛选
|
|
81
|
+
|
|
82
|
+
- 关键词搜索用一个 `Input`(前面可放搜索图标),边输入边搜索时要做防抖。清空关键词后恢复默认
|
|
83
|
+
列表;搜不到结果时的提示要带上当前关键词,或给一个清除条件的入口。
|
|
84
|
+
- 多个筛选条件放在表格上方排成一行(`Select`、`DatePicker` 等),不用包 `Card`。常用条件直接
|
|
85
|
+
展示;条件很多或逻辑复杂时收进 `Drawer`,并在入口上显示已生效条件的数量。
|
|
86
|
+
- 筛选**选了就生效**:每次选择或取消后立即更新结果,不加「应用」「确定」按钮;多选下拉选完保持
|
|
87
|
+
打开。
|
|
88
|
+
- 只提供一个「重置」按钮,把整组条件恢复成默认值。不要另加「清空」按钮。
|
|
89
|
+
- 切换 `Tabs`、关闭筛选面板时,保留已经生效的筛选条件和输入内容。
|
|
90
|
+
|
|
91
|
+
## 表单
|
|
92
|
+
|
|
93
|
+
- 默认用上下排列的表单(`layout="vertical"`);字段多时按业务关系分组。同一个表单里标签的对齐方式
|
|
94
|
+
保持一致。
|
|
95
|
+
- 每个字段都有 `label`;`placeholder` 只是示例提示,不能代替 `label`。
|
|
96
|
+
- 必填项在规则里写 `required`,由 `Form` 显示必填标记,不手写星号。
|
|
97
|
+
- 控件按数据选:单行文字 `Input`,多行文字 `Input type="textarea"`;数量、金额、比例用
|
|
98
|
+
`InputNumber`,电话、编号这类可能以 0 开头的用 `Input`;开和关二选一用 `Switch`;几个里选一个用
|
|
99
|
+
`Radio`,可以选多个用 `Checkbox`;选项多用 `Select`。
|
|
100
|
+
- `InputNumber` 的最小值、最大值、步长、小数位和单位来自业务,用户没给就不设,不要猜。
|
|
101
|
+
- 错误提示要说清楚哪里不对、怎么改,不只写「格式错误」。不要在用户刚输入第一个字时就报错。
|
|
102
|
+
- 只能看不能改、但允许复制的字段用 `readOnly`;完全不能操作的用 `disabled`。
|
|
103
|
+
- 日期:一个日期用 `DatePicker`;起止区间用 `RangePicker`,不用两个单独的 `DatePicker` 拼;只需要
|
|
104
|
+
日期时不要打开时间选择(`showTime`)。快捷范围(`presets`,如「本月」「上月」)只在用户提到时加,
|
|
105
|
+
选中后输入框显示真实的起止日期。
|
|
106
|
+
- 提交失败时滚动到第一个出错的字段(`form.scrollToFirstError()`);提交中主按钮 `loading`。
|
|
107
|
+
- 「重置」的意思是恢复成表单最初的值,不是清空。
|
|
108
|
+
- 字数达到上限时要让用户看得到(`count`),不要悄悄截断。
|
|
109
|
+
|
|
110
|
+
## 弹窗、抽屉和提示
|
|
111
|
+
|
|
112
|
+
- 短的、需要集中完成的事(确认、几个字段的新建或编辑)用 `Modal`;内容多、要对照后面的列表、
|
|
113
|
+
看详情时用 `Drawer`;普通说明和操作结果不要用 `Modal` 打断用户。
|
|
114
|
+
- `Modal` 里的按钮:新建数据时主按钮写「提交」,编辑已有数据时写「保存」,次按钮都是「取消」。
|
|
115
|
+
用 `Modal` 自带的底部按钮(`okText`、`cancelText`、`onOk`),不在内容区另放一排按钮。
|
|
116
|
+
- 弹窗里由系统自动带出的、或不允许修改的字段用 `disabled`,仍然保留 `label`;等用户填写的字段保持
|
|
117
|
+
正常可编辑。
|
|
118
|
+
- 提交成功后关闭弹窗并用 `message` 提示结果;提交失败时不关闭,保留已填的内容。请求没成功之前不要
|
|
119
|
+
关闭弹窗,也不要提示成功。
|
|
120
|
+
- 有未保存内容的编辑弹窗和危险操作的确认弹窗,不允许点遮罩直接关闭(`mask={{ closable: false }}`)。
|
|
121
|
+
- 弹窗宽度用自带的 `size`(`sm` / `md` / `lg` / `xl`),不自己写宽度;内容长时让内容区在弹窗内部
|
|
122
|
+
滚动,标题和底部按钮保持可见。
|
|
123
|
+
- 不在 `Modal` 里再开 `Modal`,不在 `Drawer` 里再开 `Drawer`;次级内容在当前面板里展开或切换。
|
|
124
|
+
- 只是告知结果、不需要用户做选择时,用 `message` 或 `Alert`,不要弹一个要点「确定」才能关的弹窗。
|
|
125
|
+
- `Drawer` 有没保存的修改时,关闭前先确认。底部同样是一个主按钮加「取消」。
|
|
126
|
+
- 里面有表单或按钮的 `Popover` 用点击触发(`trigger="click"`)。
|
|
127
|
+
- `Tooltip` 只放一句短话,不放多段说明、列表、链接和按钮;需要这些时用 `Popover`;再多就用
|
|
128
|
+
`Drawer` 或 `Modal`。重要信息不能只放在 `Tooltip` 里。
|
|
129
|
+
- 放在浮层(`Popover`、下拉面板)里面的 `Input`、`Select`、`InputNumber` 用 `variant="elevated"`;
|
|
130
|
+
页面和普通表单里用默认值。
|
|
131
|
+
|
|
132
|
+
## 反馈和三种状态
|
|
133
|
+
|
|
134
|
+
- 刚做完的操作的结果用 `message`(保存成功、删除失败),相同的提示不要重复弹。停留时间:成功和
|
|
135
|
+
普通提示 3 秒(默认值),警告和错误 5 秒(`message.error('保存失败,请重试', 5)`)。文案先说结果,
|
|
136
|
+
必要时补一句原因或下一步;需要一直留在页面上
|
|
137
|
+
的重要信息或风险用 `Alert`;跨页面的、后台任务完成之类的事件用 `notification`。
|
|
138
|
+
- 每块有数据的区域都要分别处理**加载中、没有数据、出错**三种情况,三者看起来必须不一样。
|
|
139
|
+
- 整页第一次打开时用 `Spin`;页面框架已经出来后,筛选、翻页、切换页签引起的局部刷新用
|
|
140
|
+
`Skeleton` 或 `Table` 的 `loading`,其他已经加载好的区域保持可用。骨架的形状和位置尽量贴近真实
|
|
141
|
+
内容,数据回来后页面不跳动;同一块区域不要同时出现 `Spin` 和 `Skeleton`。上传、导出这类有进度的
|
|
142
|
+
任务用 `Progress`,不用骨架。
|
|
143
|
+
- 操作真正成功之后才提示成功。开关这类点了就保存的控件,保存失败要变回原来的值并提示。
|
|
144
|
+
|
|
145
|
+
## 几个组件的固定用法
|
|
146
|
+
|
|
147
|
+
- `Tabs`:只用来切换同一块区域里的同级内容,不当步骤条、主导航或按钮用。页面级的切换用默认的
|
|
148
|
+
下划线样式(`type="line"`);标签文字要短、说法对称(概览 / 成员 / 设置)。
|
|
149
|
+
- `Steps`:只用于有先后顺序的流程,每一步的状态对应真实进度;默认不能点击跳步,用户要求才加。
|
|
150
|
+
- `Breadcrumb`:从根到当前页依次排列,上级可以点,当前页不可点。
|
|
151
|
+
- `Dropdown` 放一组操作,`Select` 用来选值,两者不混用。危险操作在菜单里单独分组。
|
|
152
|
+
- 菜单(`Menu` 和 `Dropdown` 的菜单项):每一项都要有真实的操作或跳转目标,没有行为的内容不要做成
|
|
153
|
+
菜单项;当前所在的导航项保持选中;不能用的项传 `disabled`;文案用动词或明确的目的地。
|
|
154
|
+
- `notification`:标题说发生了什么,描述只写必要的摘要,需要用户处理时给出操作入口;相同的事件
|
|
155
|
+
合并,不重复弹。只有确实有详情可看时才让整条通知可以点击。
|
|
156
|
+
- `Divider`:只在同一个容器里需要分组时用,不要在每个元素之间都加;竖向分隔线两侧要留出间距,
|
|
157
|
+
不贴着文字或图标。
|
|
158
|
+
- `Tree` 勾选时父子联动(默认行为,不要开 `checkStrictly`);展开和选中互不影响。
|
|
159
|
+
- `Cascader` 选到最后一级立即生效并关闭。
|
|
160
|
+
- `Avatar`:离职、停用的人用 `gray`;图片加载失败时会显示传入的文字(一般放名字首字),不要把它当成停用。头像默认
|
|
161
|
+
不可点击。
|
|
162
|
+
- `Tag` 只做轻量标记,不当按钮用;可以移除时才显示关闭图标。多个放不下时换行。
|
|
163
|
+
- `Switch`:只用于点了马上生效的开和关;旁边的文字写打开之后会发生什么,不写「是 / 否」。
|
|
164
|
+
- `Card`:整张卡片可以点击时,卡片里的按钮和链接要单独响应,不能连带触发整卡的跳转;用不到的
|
|
165
|
+
标题区、底部区不要留空占位。
|
|
166
|
+
- `Checkbox` 的半选状态(`indeterminate`)由子项的勾选结果算出来,不当成一个单独的值保存。
|
|
167
|
+
|
|
168
|
+
## 设计规范里有、组件库里没有的
|
|
169
|
+
|
|
170
|
+
| 规范里的名字 | 怎么做 |
|
|
171
|
+
| --- | --- |
|
|
172
|
+
| Search 搜索 | `Input` 加搜索图标,规则见「搜索与筛选」 |
|
|
173
|
+
| Filter Group 筛选组 | 一行 `Select` / `DatePicker` 加一个「重置」按钮,规则见「搜索与筛选」 |
|
|
174
|
+
| Status 状态 | `Tag` 加文字,颜色见「表格」 |
|
|
175
|
+
| 通知列表(带已读 / 未读、时间、未读数量) | 组件库的 `notification` 只是弹出的提示。需要通知列表时用现有组件在项目里拼:每条有标题、摘要、时间和已读状态,未读数量和入口上的数字保持一致,加载、没有通知、出错分别处理 |
|
|
176
|
+
| Data Viz 图表 | 只展示完成度用 `Progress`。需要折线图、柱状图、饼图等图表时直接安装并使用 `echarts`,不用问用户,也不要换别的图表库;按数据关系选图:趋势用折线,类别比较用柱状,占比用饼图或环形图(类别少时);图表颜色从 Token 读取,亮色暗色都要对;坐标轴、单位、图例写全,同样处理加载、无数据、出错;标题写清指标,副标题写时间范围和单位;鼠标悬停的提示里有系列名、数值和单位;不用 3D 效果,纵轴不做容易误导的截断 |
|
|
177
|
+
|
|
178
|
+
## 交付前自查
|
|
179
|
+
|
|
180
|
+
1. 每块操作区域只有一个主按钮;危险操作有确认。
|
|
181
|
+
2. 没有写死的颜色和像素间距;没有给卡片另加阴影;没有多余的卡片嵌套。
|
|
182
|
+
3. 表格:数字靠右、操作列在最右、长文字有截断;加载、空、出错三种情况都处理了。
|
|
183
|
+
4. 筛选即时生效,只有一个「重置」;改筛选条件或每页条数后回到第一页。
|
|
184
|
+
5. 表单每个字段有 `label`,必填有标记,提交中按钮有 `loading`。
|
|
185
|
+
6. 弹窗按钮是「提交 / 取消」或「保存 / 取消」;危险操作的确认按钮写的是具体动作。
|
|
186
|
+
7. 状态都带文字,不是只有颜色;只有图标的按钮有 `aria-label`。
|
|
187
|
+
8. 页面没有横向滚动条。
|
|
188
|
+
9. 没有用户没要的排序、选择、批量操作、自动跳转。
|
|
@@ -0,0 +1,289 @@
|
|
|
1
|
+
# 常见页面的搭法
|
|
2
|
+
|
|
3
|
+
> **本文件职责**:用户说“做一个列表页 / 表单页 / 后台”时,从这里拿骨架再改。这些代码随仓库测试
|
|
4
|
+
> 一起做类型检查。属性不够用时读对应组件的 `llm.txt`。
|
|
5
|
+
> 骨架只保证写法正确;按钮主次、对齐、筛选和分页行为、加载和出错的处理按 `design-rules.md` 补全。
|
|
6
|
+
|
|
7
|
+
## 列表页(搜索、表格、编辑弹窗)
|
|
8
|
+
|
|
9
|
+
用 Input 搜索、Table 展示数据,Modal 里用 Form 编辑。
|
|
10
|
+
|
|
11
|
+
```tsx
|
|
12
|
+
import { useState } from 'react'
|
|
13
|
+
import { Button } from '@/components/apex/button'
|
|
14
|
+
import { Form, useForm } from '@/components/apex/form'
|
|
15
|
+
import { Input } from '@/components/apex/input'
|
|
16
|
+
import { Modal } from '@/components/apex/modal'
|
|
17
|
+
import { Table, type TableColumn } from '@/components/apex/table'
|
|
18
|
+
|
|
19
|
+
type User = { key: string; name: string; email: string; department: string }
|
|
20
|
+
const initialRows: User[] = [
|
|
21
|
+
{ key: '1', name: '张伟', email: 'zhang@example.com', department: '产品部' },
|
|
22
|
+
]
|
|
23
|
+
|
|
24
|
+
export default function ListPage() {
|
|
25
|
+
const [rows, setRows] = useState(initialRows)
|
|
26
|
+
const [search, setSearch] = useState('')
|
|
27
|
+
const [editing, setEditing] = useState<User | null>(null)
|
|
28
|
+
const [loading, setLoading] = useState(false)
|
|
29
|
+
const [form] = useForm<User>()
|
|
30
|
+
const columns: TableColumn<User>[] = [
|
|
31
|
+
{ key: 'name', title: '姓名' },
|
|
32
|
+
{ key: 'email', title: '邮箱' },
|
|
33
|
+
{ key: 'department', title: '部门' },
|
|
34
|
+
{
|
|
35
|
+
key: 'actions',
|
|
36
|
+
title: '操作',
|
|
37
|
+
render: (_, record) => (
|
|
38
|
+
<Button
|
|
39
|
+
type="link"
|
|
40
|
+
onClick={() => {
|
|
41
|
+
form.setFieldsValue(record)
|
|
42
|
+
setEditing(record)
|
|
43
|
+
}}
|
|
44
|
+
>
|
|
45
|
+
编辑
|
|
46
|
+
</Button>
|
|
47
|
+
),
|
|
48
|
+
},
|
|
49
|
+
]
|
|
50
|
+
return (
|
|
51
|
+
<div>
|
|
52
|
+
<Input
|
|
53
|
+
placeholder="按姓名搜索"
|
|
54
|
+
value={search}
|
|
55
|
+
onChange={(event) => setSearch(event.target.value)}
|
|
56
|
+
/>
|
|
57
|
+
<Table
|
|
58
|
+
columns={columns}
|
|
59
|
+
data={rows.filter((row) => row.name.includes(search))}
|
|
60
|
+
loading={loading}
|
|
61
|
+
pagination={{ defaultPageSize: 10 }}
|
|
62
|
+
/>
|
|
63
|
+
<Modal
|
|
64
|
+
title="编辑用户"
|
|
65
|
+
open={editing !== null}
|
|
66
|
+
okText="保存"
|
|
67
|
+
cancelText="取消"
|
|
68
|
+
okButtonProps={{ loading }}
|
|
69
|
+
onOk={() => form.submit()}
|
|
70
|
+
onCancel={() => setEditing(null)}
|
|
71
|
+
>
|
|
72
|
+
<Form
|
|
73
|
+
form={form}
|
|
74
|
+
onFinish={async (values) => {
|
|
75
|
+
setLoading(true)
|
|
76
|
+
try {
|
|
77
|
+
await Promise.resolve()
|
|
78
|
+
setRows((previous) =>
|
|
79
|
+
previous.map((row) => (row.key === editing?.key ? { ...row, ...values } : row)),
|
|
80
|
+
)
|
|
81
|
+
setEditing(null)
|
|
82
|
+
} finally {
|
|
83
|
+
setLoading(false)
|
|
84
|
+
}
|
|
85
|
+
}}
|
|
86
|
+
>
|
|
87
|
+
<Form.Item name="name" label="姓名" rules={[{ required: true, message: '请输入姓名' }]}>
|
|
88
|
+
<Input />
|
|
89
|
+
</Form.Item>
|
|
90
|
+
<Form.Item name="email" label="邮箱">
|
|
91
|
+
<Input />
|
|
92
|
+
</Form.Item>
|
|
93
|
+
<Form.Item name="department" label="部门">
|
|
94
|
+
<Input />
|
|
95
|
+
</Form.Item>
|
|
96
|
+
</Form>
|
|
97
|
+
</Modal>
|
|
98
|
+
</div>
|
|
99
|
+
)
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## 表单页
|
|
104
|
+
|
|
105
|
+
用 Form 组织 Input、Select 和 Switch,提交后用 message 提示。
|
|
106
|
+
|
|
107
|
+
```tsx
|
|
108
|
+
import { Button } from '@/components/apex/button'
|
|
109
|
+
import { Form } from '@/components/apex/form'
|
|
110
|
+
import { Input } from '@/components/apex/input'
|
|
111
|
+
import { message } from '@/components/apex/message'
|
|
112
|
+
import { Select } from '@/components/apex/select'
|
|
113
|
+
import { Switch } from '@/components/apex/switch'
|
|
114
|
+
|
|
115
|
+
const roles = [
|
|
116
|
+
{ value: 'member', label: '成员' },
|
|
117
|
+
{ value: 'admin', label: '管理员' },
|
|
118
|
+
]
|
|
119
|
+
|
|
120
|
+
export default function FormPage() {
|
|
121
|
+
return (
|
|
122
|
+
<Form
|
|
123
|
+
layout="vertical"
|
|
124
|
+
initialValues={{ enabled: true }}
|
|
125
|
+
onFinish={() => {
|
|
126
|
+
message.success('已保存')
|
|
127
|
+
}}
|
|
128
|
+
>
|
|
129
|
+
<Form.Item name="name" label="姓名" rules={[{ required: true, message: '请输入姓名' }]}>
|
|
130
|
+
<Input placeholder="请输入姓名" />
|
|
131
|
+
</Form.Item>
|
|
132
|
+
<Form.Item name="role" label="角色">
|
|
133
|
+
<Select options={roles} />
|
|
134
|
+
</Form.Item>
|
|
135
|
+
<Form.Item name="enabled" label="启用" valuePropName="checked">
|
|
136
|
+
<Switch />
|
|
137
|
+
</Form.Item>
|
|
138
|
+
<Form.Item>
|
|
139
|
+
<Button type="primary" htmlType="submit">
|
|
140
|
+
保存
|
|
141
|
+
</Button>
|
|
142
|
+
</Form.Item>
|
|
143
|
+
</Form>
|
|
144
|
+
)
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## 详情页
|
|
149
|
+
|
|
150
|
+
用 Card、Row / Col、Typography 和 Tag 展示详情,Button 返回。
|
|
151
|
+
|
|
152
|
+
```tsx
|
|
153
|
+
import { Button } from '@/components/apex/button'
|
|
154
|
+
import { Card } from '@/components/apex/card'
|
|
155
|
+
import { Col, Row } from '@/components/apex/grid'
|
|
156
|
+
import { Tag } from '@/components/apex/tag'
|
|
157
|
+
import { Typography } from '@/components/apex/typography'
|
|
158
|
+
|
|
159
|
+
const fields = [
|
|
160
|
+
['姓名', '张伟'],
|
|
161
|
+
['邮箱', 'zhang@example.com'],
|
|
162
|
+
['部门', '产品部'],
|
|
163
|
+
['岗位', '产品经理'],
|
|
164
|
+
['城市', '上海'],
|
|
165
|
+
['入职日期', '2026-01-01'],
|
|
166
|
+
]
|
|
167
|
+
|
|
168
|
+
export default function DetailPage() {
|
|
169
|
+
return (
|
|
170
|
+
<Card title="用户详情" extra={<Button onClick={() => window.history.back()}>返回</Button>}>
|
|
171
|
+
<Tag color="success">已启用</Tag>
|
|
172
|
+
<Row gutter={[16, 16]}>
|
|
173
|
+
{fields.map(([label, value]) => (
|
|
174
|
+
<Col key={label} span={12}>
|
|
175
|
+
<Typography.Text>
|
|
176
|
+
{label}:{value}
|
|
177
|
+
</Typography.Text>
|
|
178
|
+
</Col>
|
|
179
|
+
))}
|
|
180
|
+
</Row>
|
|
181
|
+
</Card>
|
|
182
|
+
)
|
|
183
|
+
}
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
## 后台整体框架
|
|
187
|
+
|
|
188
|
+
用 Layout 组织页头、侧栏和内容,Menu 导航,Card 展示内容。
|
|
189
|
+
|
|
190
|
+
```tsx
|
|
191
|
+
import { useState } from 'react'
|
|
192
|
+
import { Card } from '@/components/apex/card'
|
|
193
|
+
import { Layout } from '@/components/apex/layout'
|
|
194
|
+
import { Menu, type MenuItemType } from '@/components/apex/menu'
|
|
195
|
+
|
|
196
|
+
const items: MenuItemType[] = [
|
|
197
|
+
{ key: 'overview', label: '概览', icon: '概' },
|
|
198
|
+
{
|
|
199
|
+
key: 'workspace',
|
|
200
|
+
label: '工作台',
|
|
201
|
+
icon: '工',
|
|
202
|
+
children: [
|
|
203
|
+
{ key: 'users', label: '用户管理' },
|
|
204
|
+
{ key: 'orders', label: '订单管理' },
|
|
205
|
+
],
|
|
206
|
+
},
|
|
207
|
+
]
|
|
208
|
+
|
|
209
|
+
export default function AppLayout() {
|
|
210
|
+
const [selected, setSelected] = useState(['overview'])
|
|
211
|
+
return (
|
|
212
|
+
<Layout style={{ minHeight: '100vh' }}>
|
|
213
|
+
<Layout.Header>管理后台</Layout.Header>
|
|
214
|
+
<Layout hasSider>
|
|
215
|
+
<Layout.Sider width="auto">
|
|
216
|
+
<Menu
|
|
217
|
+
items={items}
|
|
218
|
+
collapsed={false}
|
|
219
|
+
theme="light"
|
|
220
|
+
selectedKeys={selected}
|
|
221
|
+
onSelect={({ selectedKeys }) => setSelected(selectedKeys)}
|
|
222
|
+
/>
|
|
223
|
+
</Layout.Sider>
|
|
224
|
+
<Layout.Content style={{ padding: 'var(--apex-spacing-16)' }}>
|
|
225
|
+
<Card title="工作台">从左侧选择需要查看的内容。</Card>
|
|
226
|
+
</Layout.Content>
|
|
227
|
+
</Layout>
|
|
228
|
+
</Layout>
|
|
229
|
+
)
|
|
230
|
+
}
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
## 登录页
|
|
234
|
+
|
|
235
|
+
用居中的 Card 放 Form 和 Input,Button 展示提交状态。
|
|
236
|
+
|
|
237
|
+
```tsx
|
|
238
|
+
import { useState } from 'react'
|
|
239
|
+
import { Button } from '@/components/apex/button'
|
|
240
|
+
import { Card } from '@/components/apex/card'
|
|
241
|
+
import { Form } from '@/components/apex/form'
|
|
242
|
+
import { Input } from '@/components/apex/input'
|
|
243
|
+
import { message } from '@/components/apex/message'
|
|
244
|
+
|
|
245
|
+
export default function LoginPage() {
|
|
246
|
+
const [loading, setLoading] = useState(false)
|
|
247
|
+
return (
|
|
248
|
+
<div style={{ minHeight: '100vh', display: 'grid', placeItems: 'center' }}>
|
|
249
|
+
<Card title="登录" style={{ width: 'min(100%, 360px)' }}>
|
|
250
|
+
<Form
|
|
251
|
+
layout="vertical"
|
|
252
|
+
onFinish={async () => {
|
|
253
|
+
setLoading(true)
|
|
254
|
+
try {
|
|
255
|
+
await Promise.resolve()
|
|
256
|
+
message.success('示例提交成功,请接入项目的登录服务')
|
|
257
|
+
} finally {
|
|
258
|
+
setLoading(false)
|
|
259
|
+
}
|
|
260
|
+
}}
|
|
261
|
+
>
|
|
262
|
+
<Form.Item
|
|
263
|
+
name="username"
|
|
264
|
+
label="用户名"
|
|
265
|
+
rules={[{ required: true, message: '请输入用户名' }]}
|
|
266
|
+
>
|
|
267
|
+
<Input />
|
|
268
|
+
</Form.Item>
|
|
269
|
+
<Form.Item
|
|
270
|
+
name="password"
|
|
271
|
+
label="密码"
|
|
272
|
+
rules={[
|
|
273
|
+
{ required: true, message: '请输入密码' },
|
|
274
|
+
{ min: 6, message: '密码至少 6 位' },
|
|
275
|
+
]}
|
|
276
|
+
>
|
|
277
|
+
<Input type="password" />
|
|
278
|
+
</Form.Item>
|
|
279
|
+
<Form.Item>
|
|
280
|
+
<Button type="primary" htmlType="submit" loading={loading}>
|
|
281
|
+
登录
|
|
282
|
+
</Button>
|
|
283
|
+
</Form.Item>
|
|
284
|
+
</Form>
|
|
285
|
+
</Card>
|
|
286
|
+
</div>
|
|
287
|
+
)
|
|
288
|
+
}
|
|
289
|
+
```
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# 容易写错的地方
|
|
2
|
+
|
|
3
|
+
> **本文件职责**:Apex UI 的 API 名字和 antd 很像,但不是 antd。这里列出最常被写错的地方。
|
|
4
|
+
> 写任何组件之前先看这一页;具体属性以该组件的 `llm.txt` 为准。
|
|
5
|
+
|
|
6
|
+
## 和 antd 不一样的写法
|
|
7
|
+
|
|
8
|
+
| 不要这样写 | 应该这样写 |
|
|
9
|
+
| --- | --- |
|
|
10
|
+
| `<Table dataSource={rows} />` | `<Table data={rows} />` |
|
|
11
|
+
| 列定义用 `dataIndex: 'name'` | 列定义用 `key: 'name'`,表头用 `title` |
|
|
12
|
+
| `<Button size="large">`、`ghost`、`dashed`、`shape` | `size` 只有 `small` 和 `medium`;没有 `ghost`、`dashed`、`shape` |
|
|
13
|
+
| `<Tabs.TabPane>`、`<Collapse.Panel>`、`<Steps.Step>` | 用 `items` 数组配置 |
|
|
14
|
+
| `<Space>` | 没有这个组件,用 flex 容器加 `gap` |
|
|
15
|
+
| 把 `message` 当组件放进 JSX,或写成大写 `Message` | `message` 是小写单例,直接调用 `message.success('已保存')` |
|
|
16
|
+
| 不传 `theme` 以为是亮色 | 不传时默认暗色,亮色要写 `<ApexProvider theme="light">` |
|
|
17
|
+
|
|
18
|
+
```tsx
|
|
19
|
+
// ✅ 表格
|
|
20
|
+
import { Table } from '@/components/apex/table'
|
|
21
|
+
|
|
22
|
+
const columns = [
|
|
23
|
+
{ key: 'name', title: '姓名' },
|
|
24
|
+
{ key: 'age', title: '年龄', align: 'right' as const },
|
|
25
|
+
]
|
|
26
|
+
const rows = [{ key: '1', name: '张伟', age: 32 }]
|
|
27
|
+
|
|
28
|
+
export const UserTable = () => <Table columns={columns} data={rows} />
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
命令式确认框优先用 `Modal.useModal()`,这样能拿到当前的主题和语言。
|
|
32
|
+
|
|
33
|
+
## 没有这些组件
|
|
34
|
+
|
|
35
|
+
下面这些组件 Apex UI 里**没有**,不要导入,也不要为它们安装别的组件库。按右边的办法做。
|
|
36
|
+
|
|
37
|
+
| 没有的组件 | 怎么办 |
|
|
38
|
+
| --- | --- |
|
|
39
|
+
| Space | flex 容器加 `gap`,或 `Grid` 的 `Row` / `Col` |
|
|
40
|
+
| Empty | 表格用 `Table` 自带的空数据展示;其他地方用 `Typography` 写一行说明 |
|
|
41
|
+
| Badge | 用 `Tag` |
|
|
42
|
+
| Popconfirm | 用 `Modal.useModal()` 的确认框 |
|
|
43
|
+
| Descriptions | 用 `Row` / `Col` 加 `Typography` |
|
|
44
|
+
| Statistic | 用 `Card` 加 `Typography` |
|
|
45
|
+
| Result | 用 `Alert`,或 `Typography` 加 `Button` |
|
|
46
|
+
| List | 用 `Table`,或 `Card` 加 flex 布局 |
|
|
47
|
+
| Segmented | 用 `Radio` 的 `RadioGroup`,或 `Tabs` |
|
|
48
|
+
| Slider | 用 `InputNumber` |
|
|
49
|
+
| Timeline | 按 `selection.md`「组件不存在时怎么办」在项目里拼一个 |
|
|
50
|
+
|
|
51
|
+
## 写完自查
|
|
52
|
+
|
|
53
|
+
- 没有任何一行从 `@apexhub/apex-ui-react` 或 `antd` 导入。
|
|
54
|
+
- 没有 `as any`、`@ts-ignore`。
|
|
55
|
+
- 用到的每个属性都能在该组件的 `llm.txt` 里找到。
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# 前缀重写插件
|
|
2
|
+
|
|
3
|
+
`@apexhub/apex-ui-rewrite-prefix-plugin` 在 Vite 构建期把 `apex-*` 类名、CSS 变量和日志品牌改成团队前缀。
|
|
4
|
+
业务代码仍从 `@apexhub/apex-ui-react` 导入,源码中的默认前缀也保持不变。
|
|
5
|
+
|
|
6
|
+
## 何时使用
|
|
7
|
+
|
|
8
|
+
- 生产产物需要自有命名空间。
|
|
9
|
+
- 多个微前端需要彼此隔离的 class、Token 和浮层根。
|
|
10
|
+
- 需要检查构建产物中是否残留 Apex 标识。
|
|
11
|
+
|
|
12
|
+
当前版本支持 Vite 4–7;未经过 Vite 构建的 CDN 或远程资源不会被改写。
|
|
13
|
+
|
|
14
|
+
## 接入
|
|
15
|
+
|
|
16
|
+
没有具体前缀时先向用户询问。前缀必须是 2–32 位小写 kebab-case,不能使用 `react`、`vite`、
|
|
17
|
+
`radix` 或 `headlessui` 等保留词。
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
pnpm add -D @apexhub/apex-ui-rewrite-prefix-plugin
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
```ts
|
|
24
|
+
import { rewriteApexPrefix } from '@apexhub/apex-ui-rewrite-prefix-plugin'
|
|
25
|
+
import react from '@vitejs/plugin-react'
|
|
26
|
+
import { defineConfig } from 'vite'
|
|
27
|
+
|
|
28
|
+
export default defineConfig({
|
|
29
|
+
plugins: [
|
|
30
|
+
rewriteApexPrefix({ prefix: 'YOUR_PREFIX' }),
|
|
31
|
+
react(),
|
|
32
|
+
],
|
|
33
|
+
build: { sourcemap: false },
|
|
34
|
+
esbuild: { keepNames: false },
|
|
35
|
+
})
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
`YOUR_PREFIX` 必须替换成用户给出的值,不要擅自填示例前缀。业务代码继续这样写:
|
|
39
|
+
|
|
40
|
+
```tsx
|
|
41
|
+
import { ApexProvider, Button } from '@apexhub/apex-ui-react'
|
|
42
|
+
import '@apexhub/apex-ui-react/style.css'
|
|
43
|
+
|
|
44
|
+
export function App() {
|
|
45
|
+
return <ApexProvider><Button type="primary">提交</Button></ApexProvider>
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## API 与验收
|
|
50
|
+
|
|
51
|
+
`rewriteApexPrefix({ prefix, consoleBrand?, cleanBundle? })` 接受技术前缀、可选日志品牌和构建检查开关。
|
|
52
|
+
生产构建建议使用 `cleanBundle` 默认值、关闭 source map,并确认最终 JS、CSS、HTML 和 JSON 中没有
|
|
53
|
+
旧的 `apex-*` 或 `--apex-*` 标识。具体审计报告由插件写入 `.artifacts/`,该目录适合作为本地构建产物。
|
|
54
|
+
|
|
55
|
+
恢复默认命名空间时删除插件并重新构建。
|