@apexhub/apex-ui-react 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.
Files changed (185) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +37 -2
  3. package/dist/en_US.d.ts +191 -0
  4. package/dist/index.cjs +40692 -0
  5. package/dist/index.d.ts +6869 -0
  6. package/dist/index.mjs +40676 -0
  7. package/dist/llm/alert.tokens.txt +44 -0
  8. package/dist/llm/alert.txt +167 -0
  9. package/dist/llm/apex-provider.txt +368 -0
  10. package/dist/llm/auto-complete.tokens.txt +77 -0
  11. package/dist/llm/auto-complete.txt +373 -0
  12. package/dist/llm/avatar.tokens.txt +38 -0
  13. package/dist/llm/avatar.txt +199 -0
  14. package/dist/llm/breadcrumb.tokens.txt +193 -0
  15. package/dist/llm/breadcrumb.txt +251 -0
  16. package/dist/llm/button.tokens.txt +470 -0
  17. package/dist/llm/button.txt +262 -0
  18. package/dist/llm/card.tokens.txt +27 -0
  19. package/dist/llm/card.txt +95 -0
  20. package/dist/llm/cascader.tokens.txt +253 -0
  21. package/dist/llm/cascader.txt +898 -0
  22. package/dist/llm/checkbox.tokens.txt +28 -0
  23. package/dist/llm/checkbox.txt +332 -0
  24. package/dist/llm/collapse.tokens.txt +84 -0
  25. package/dist/llm/collapse.txt +330 -0
  26. package/dist/llm/date-picker.tokens.txt +171 -0
  27. package/dist/llm/date-picker.txt +424 -0
  28. package/dist/llm/divider.tokens.txt +22 -0
  29. package/dist/llm/divider.txt +161 -0
  30. package/dist/llm/drawer.tokens.txt +71 -0
  31. package/dist/llm/drawer.txt +369 -0
  32. package/dist/llm/dropdown.tokens.txt +59 -0
  33. package/dist/llm/dropdown.txt +420 -0
  34. package/dist/llm/form.tokens.txt +26 -0
  35. package/dist/llm/form.txt +341 -0
  36. package/dist/llm/grid.txt +419 -0
  37. package/dist/llm/image.tokens.txt +28 -0
  38. package/dist/llm/image.txt +428 -0
  39. package/dist/llm/input-number.tokens.txt +159 -0
  40. package/dist/llm/input-number.txt +486 -0
  41. package/dist/llm/input.tokens.txt +136 -0
  42. package/dist/llm/input.txt +422 -0
  43. package/dist/llm/layout.tokens.txt +29 -0
  44. package/dist/llm/layout.txt +298 -0
  45. package/dist/llm/menu.tokens.txt +87 -0
  46. package/dist/llm/menu.txt +680 -0
  47. package/dist/llm/message.tokens.txt +25 -0
  48. package/dist/llm/message.txt +301 -0
  49. package/dist/llm/modal.tokens.txt +96 -0
  50. package/dist/llm/modal.txt +584 -0
  51. package/dist/llm/notification.tokens.txt +79 -0
  52. package/dist/llm/notification.txt +383 -0
  53. package/dist/llm/pagination.tokens.txt +33 -0
  54. package/dist/llm/pagination.txt +208 -0
  55. package/dist/llm/popover.tokens.txt +28 -0
  56. package/dist/llm/popover.txt +233 -0
  57. package/dist/llm/progress.tokens.txt +83 -0
  58. package/dist/llm/progress.txt +279 -0
  59. package/dist/llm/radio.tokens.txt +21 -0
  60. package/dist/llm/radio.txt +348 -0
  61. package/dist/llm/rate.tokens.txt +20 -0
  62. package/dist/llm/rate.txt +241 -0
  63. package/dist/llm/select.tokens.txt +160 -0
  64. package/dist/llm/select.txt +830 -0
  65. package/dist/llm/skeleton.tokens.txt +15 -0
  66. package/dist/llm/skeleton.txt +275 -0
  67. package/dist/llm/spin.tokens.txt +21 -0
  68. package/dist/llm/spin.txt +294 -0
  69. package/dist/llm/steps.tokens.txt +30 -0
  70. package/dist/llm/steps.txt +300 -0
  71. package/dist/llm/switch.tokens.txt +38 -0
  72. package/dist/llm/switch.txt +216 -0
  73. package/dist/llm/table.tokens.txt +94 -0
  74. package/dist/llm/table.txt +1046 -0
  75. package/dist/llm/tabs.tokens.txt +78 -0
  76. package/dist/llm/tabs.txt +306 -0
  77. package/dist/llm/tag.tokens.txt +76 -0
  78. package/dist/llm/tag.txt +305 -0
  79. package/dist/llm/tooltip.tokens.txt +22 -0
  80. package/dist/llm/tooltip.txt +304 -0
  81. package/dist/llm/tree-select.tokens.txt +174 -0
  82. package/dist/llm/tree-select.txt +762 -0
  83. package/dist/llm/tree.tokens.txt +36 -0
  84. package/dist/llm/tree.txt +505 -0
  85. package/dist/llm/typography.tokens.txt +60 -0
  86. package/dist/llm/typography.txt +413 -0
  87. package/dist/llm/upload.tokens.txt +201 -0
  88. package/dist/llm/upload.txt +706 -0
  89. package/dist/llms-full.txt +16689 -0
  90. package/dist/llms-theme.txt +32 -0
  91. package/dist/llms.txt +59 -0
  92. package/dist/locale/en_US.cjs +160 -0
  93. package/dist/locale/en_US.d.ts +4 -0
  94. package/dist/locale/en_US.mjs +161 -0
  95. package/dist/locale/zh_CN.cjs +160 -0
  96. package/dist/locale/zh_CN.d.ts +4 -0
  97. package/dist/locale/zh_CN.mjs +161 -0
  98. package/dist/style.css +19619 -0
  99. package/dist/zh_CN.d.ts +191 -0
  100. package/llms-full.txt +16689 -0
  101. package/llms-theme.txt +32 -0
  102. package/llms.txt +59 -0
  103. package/package.json +118 -3
  104. package/src/alert/llm.txt +167 -0
  105. package/src/alert/tokens.txt +44 -0
  106. package/src/apex-provider/llm.txt +368 -0
  107. package/src/auto-complete/llm.txt +373 -0
  108. package/src/auto-complete/tokens.txt +77 -0
  109. package/src/avatar/llm.txt +199 -0
  110. package/src/avatar/tokens.txt +38 -0
  111. package/src/breadcrumb/llm.txt +251 -0
  112. package/src/breadcrumb/tokens.txt +193 -0
  113. package/src/button/llm.txt +262 -0
  114. package/src/button/tokens.txt +470 -0
  115. package/src/card/llm.txt +95 -0
  116. package/src/card/tokens.txt +27 -0
  117. package/src/cascader/llm.txt +898 -0
  118. package/src/cascader/tokens.txt +253 -0
  119. package/src/checkbox/llm.txt +332 -0
  120. package/src/checkbox/tokens.txt +28 -0
  121. package/src/collapse/llm.txt +330 -0
  122. package/src/collapse/tokens.txt +84 -0
  123. package/src/date-picker/llm.txt +424 -0
  124. package/src/date-picker/tokens.txt +171 -0
  125. package/src/divider/llm.txt +161 -0
  126. package/src/divider/tokens.txt +22 -0
  127. package/src/drawer/llm.txt +369 -0
  128. package/src/drawer/tokens.txt +71 -0
  129. package/src/dropdown/llm.txt +420 -0
  130. package/src/dropdown/tokens.txt +59 -0
  131. package/src/form/llm.txt +341 -0
  132. package/src/form/tokens.txt +26 -0
  133. package/src/grid/llm.txt +419 -0
  134. package/src/image/llm.txt +428 -0
  135. package/src/image/tokens.txt +28 -0
  136. package/src/input/llm.txt +422 -0
  137. package/src/input/tokens.txt +136 -0
  138. package/src/input-number/llm.txt +486 -0
  139. package/src/input-number/tokens.txt +159 -0
  140. package/src/layout/llm.txt +298 -0
  141. package/src/layout/tokens.txt +29 -0
  142. package/src/menu/llm.txt +680 -0
  143. package/src/menu/tokens.txt +87 -0
  144. package/src/message/llm.txt +301 -0
  145. package/src/message/tokens.txt +25 -0
  146. package/src/modal/llm.txt +584 -0
  147. package/src/modal/tokens.txt +96 -0
  148. package/src/notification/llm.txt +383 -0
  149. package/src/notification/tokens.txt +79 -0
  150. package/src/pagination/llm.txt +208 -0
  151. package/src/pagination/tokens.txt +33 -0
  152. package/src/popover/llm.txt +233 -0
  153. package/src/popover/tokens.txt +28 -0
  154. package/src/progress/llm.txt +279 -0
  155. package/src/progress/tokens.txt +83 -0
  156. package/src/radio/llm.txt +348 -0
  157. package/src/radio/tokens.txt +21 -0
  158. package/src/rate/llm.txt +241 -0
  159. package/src/rate/tokens.txt +20 -0
  160. package/src/select/llm.txt +830 -0
  161. package/src/select/tokens.txt +160 -0
  162. package/src/skeleton/llm.txt +275 -0
  163. package/src/skeleton/tokens.txt +15 -0
  164. package/src/spin/llm.txt +294 -0
  165. package/src/spin/tokens.txt +21 -0
  166. package/src/steps/llm.txt +300 -0
  167. package/src/steps/tokens.txt +30 -0
  168. package/src/switch/llm.txt +216 -0
  169. package/src/switch/tokens.txt +38 -0
  170. package/src/table/llm.txt +1046 -0
  171. package/src/table/tokens.txt +94 -0
  172. package/src/tabs/llm.txt +306 -0
  173. package/src/tabs/tokens.txt +78 -0
  174. package/src/tag/llm.txt +305 -0
  175. package/src/tag/tokens.txt +76 -0
  176. package/src/tooltip/llm.txt +304 -0
  177. package/src/tooltip/tokens.txt +22 -0
  178. package/src/tree/llm.txt +505 -0
  179. package/src/tree/tokens.txt +36 -0
  180. package/src/tree-select/llm.txt +762 -0
  181. package/src/tree-select/tokens.txt +174 -0
  182. package/src/typography/llm.txt +413 -0
  183. package/src/typography/tokens.txt +60 -0
  184. package/src/upload/llm.txt +706 -0
  185. package/src/upload/tokens.txt +201 -0
@@ -0,0 +1,294 @@
1
+ # Spin
2
+
3
+ > Spin:局部区域正在加载数据,需要覆盖指示器且不阻断整页时。
4
+
5
+ 包:`@apexhub/apex-ui-react`;版本:`1.2.0`(当前源码快照,发布状态以安装包版本为准)。
6
+
7
+ 公开导出:`Spin`。
8
+
9
+ 以下 API 属于 Apex UI;不要据 antd 的同名组件推断额外属性或默认值。默认值列的空缺表示未声明,不代表 `false`。
10
+
11
+ ## 快速开始
12
+
13
+ ```tsx
14
+ import { Spin } from '@apexhub/apex-ui-react'
15
+
16
+ import '@apexhub/apex-ui-react/style.css'
17
+
18
+ export default () => <Spin aria-label="加载中" />
19
+ ```
20
+
21
+ ## 何时使用
22
+
23
+ - 局部区域正在加载数据,需要覆盖指示器且不阻断整页时。
24
+ - 需要将现有内容包裹起来,在加载期间降低透明度并禁用交互时。
25
+ - 若有明确进度百分比,请使用 Progress;若只需角落轻提示,请使用 Message。
26
+
27
+ ## API
28
+
29
+ 仅使用类型定义支持的属性;原生属性、ref 目标和事件签名因组件而异。关联类型用于解释字段结构;只有「导出类型」中的名称可从包根导入。
30
+
31
+ ### Spin
32
+
33
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
34
+ | --- | --- | --- | --- | --- |
35
+ | spinning | 是否处于加载中状态 | `boolean` | 否 | `true` |
36
+ | delay | 延迟显示 loading(毫秒) | `number` | 否 | — |
37
+ | description | 描述文案 | `React.ReactNode` | 否 | — |
38
+ | indicator | 自定义指示器 | `React.ReactNode` | 否 | — |
39
+ | size | 组件尺寸 | `"small" \| "medium" \| "large"` | 否 | `'medium'` |
40
+ | fullscreen | 是否全屏显示 | `boolean` | 否 | `false` |
41
+ | fill | 包裹内容时,作为 flex 子项填满父级剩余空间,并向内容容器传递 flex 高度链 | `boolean` | 否 | `false` |
42
+ | children | 被包裹的内容 | `React.ReactNode` | 否 | — |
43
+ | className | 根节点类名(作用于 `data-slot="spin"` 的 Spin 根,非 fullscreen 遮罩层) | `string` | 否 | — |
44
+ | style | 根节点内联样式(作用于 `data-slot="spin"` 的 Spin 根) | `React.CSSProperties` | 否 | — |
45
+ | ref | 根节点 ref(React 19 普通 prop)。<br>- 默认 / 包裹模式:挂在 `data-slot="spin"`<br>- `fullscreen` 且处于 loading:挂在 `data-slot="spin-mask"`(portal 到 `document.body`) | `React.Ref<HTMLDivElement>` | 否 | — |
46
+
47
+ ### SpinSize
48
+
49
+ ```typescript
50
+ type SpinSize = 'small' | 'medium' | 'large'
51
+ ```
52
+
53
+ ### 导出类型
54
+
55
+ 另可从 `@apexhub/apex-ui-react` 导入:`SpinProps`、`SpinSize`(与上文子类型配合使用)。
56
+
57
+ ## 代码演示
58
+
59
+ ### 尺寸
60
+
61
+ 提供 `small`、`medium` 和 `large` 三种尺寸。
62
+
63
+ ```tsx
64
+ import { Spin } from '@apexhub/apex-ui-react'
65
+
66
+ export default () => (
67
+ <div style={{ display: 'flex', gap: 24, alignItems: 'center' }}>
68
+ <Spin size="small" aria-label="小号加载" />
69
+ <Spin size="medium" aria-label="中号加载" />
70
+ <Spin size="large" aria-label="大号加载" />
71
+ </div>
72
+ )
73
+ ```
74
+
75
+ ### 描述文案
76
+
77
+ 通过 `description` 为加载状态增加说明文字。
78
+
79
+ ```tsx
80
+ import { Spin } from '@apexhub/apex-ui-react'
81
+
82
+ export default () => (
83
+ <div style={{ display: 'flex', gap: 32, alignItems: 'flex-start' }}>
84
+ <Spin size="small" description="加载中…" aria-label="小号加载" />
85
+ <Spin size="medium" description="加载中…" aria-label="中号加载" />
86
+ <Spin size="large" description="加载中…" aria-label="大号加载" />
87
+ </div>
88
+ )
89
+ ```
90
+
91
+ ### 包裹内容
92
+
93
+ 将内容放入 Spin 内部,可让现有区域进入加载状态,并通过外部按钮切换加载中状态。
94
+
95
+ ```tsx
96
+ import { Button, Spin } from '@apexhub/apex-ui-react'
97
+
98
+ import { useState } from 'react'
99
+
100
+ export default () => {
101
+ const [spinning, setSpinning] = useState(false)
102
+
103
+ return (
104
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 12, alignItems: 'flex-start' }}>
105
+ <Button onClick={() => setSpinning((current) => !current)}>
106
+ {spinning ? '停止加载' : '开始加载'}
107
+ </Button>
108
+ <Spin
109
+ spinning={spinning}
110
+ description="加载内容中…"
111
+ aria-label="卡片加载"
112
+ style={{ width: 360 }}
113
+ >
114
+ <div
115
+ style={{
116
+ padding: 'var(--apex-spacing-16)',
117
+ border: 'var(--apex-border-1) solid var(--apex-stroke-neutral-quinary)',
118
+ borderRadius: 'var(--apex-radius-8)',
119
+ backgroundColor: 'var(--apex-fill-neutral-primary)',
120
+ }}
121
+ >
122
+ <strong>Alert message title</strong>
123
+ <p style={{ marginBlockEnd: 0 }}>Further details about this loading area.</p>
124
+ </div>
125
+ </Spin>
126
+ </div>
127
+ )
128
+ }
129
+ ```
130
+
131
+ ### 填满父级
132
+
133
+ 在定高的纵向 flex 布局中,使用 `fill` 让 Spin 填满父级剩余空间,并将高度约束传递给内部滚动区域。
134
+
135
+ ```tsx
136
+ import { Spin, Switch } from '@apexhub/apex-ui-react'
137
+
138
+ import { useState } from 'react'
139
+
140
+ export default () => {
141
+ const [spinning, setSpinning] = useState(true)
142
+
143
+ return (
144
+ <div
145
+ style={{
146
+ display: 'flex',
147
+ flexDirection: 'column',
148
+ width: 480,
149
+ maxWidth: '100%',
150
+ height: 240,
151
+ border: 'var(--apex-border-1) solid var(--apex-stroke-neutral-quinary)',
152
+ }}
153
+ >
154
+ <div
155
+ style={{
156
+ flexShrink: 0,
157
+ display: 'flex',
158
+ alignItems: 'center',
159
+ justifyContent: 'space-between',
160
+ padding: 'var(--apex-spacing-8)',
161
+ }}
162
+ >
163
+ <span>固定顶部区域</span>
164
+ <Switch checked={spinning} onChange={setSpinning} aria-label="切换填充区域加载状态" />
165
+ </div>
166
+ <Spin fill spinning={spinning} aria-label="填充区域加载">
167
+ <div style={{ flex: 1, minHeight: 0, overflow: 'auto' }}>
168
+ <div style={{ height: 480, padding: 'var(--apex-spacing-12)' }}>
169
+ 内容高度超过剩余空间时,仅在此区域滚动。
170
+ </div>
171
+ </div>
172
+ </Spin>
173
+ </div>
174
+ )
175
+ }
176
+ ```
177
+
178
+ ### 延迟显示
179
+
180
+ `delay` 可以延迟显示加载效果,用于减少短时间请求带来的闪烁。
181
+
182
+ ```tsx
183
+ import { Button, Spin } from '@apexhub/apex-ui-react'
184
+
185
+ import { useState } from 'react'
186
+
187
+ export default () => {
188
+ const [spinning, setSpinning] = useState(false)
189
+
190
+ return (
191
+ <div style={{ display: 'flex', gap: 16, alignItems: 'center' }}>
192
+ <Button onClick={() => setSpinning((current) => !current)}>
193
+ {spinning ? '停止加载' : '开始加载'}
194
+ </Button>
195
+ <Spin spinning={spinning} delay={500} aria-label="延迟加载" />
196
+ <span>delay=500ms</span>
197
+ </div>
198
+ )
199
+ }
200
+ ```
201
+
202
+ ### 自定义指示符
203
+
204
+ 通过 `indicator` 替换默认加载图标。
205
+
206
+ ```tsx
207
+ import { Spin } from '@apexhub/apex-ui-react'
208
+
209
+ const indicator = (
210
+ <span
211
+ style={{
212
+ display: 'inline-flex',
213
+ width: 24,
214
+ height: 24,
215
+ alignItems: 'center',
216
+ justifyContent: 'center',
217
+ }}
218
+ >
219
+ ...
220
+ </span>
221
+ )
222
+
223
+ export default () => (
224
+ <Spin indicator={indicator} description="自定义指示符" aria-label="自定义加载" />
225
+ )
226
+ ```
227
+
228
+ ### 全屏加载
229
+
230
+ `fullscreen` 用于展示覆盖页面的加载状态。示例可点击任意位置或按 `Esc` 手动关闭。
231
+
232
+ ```tsx
233
+ import { Button, Spin } from '@apexhub/apex-ui-react'
234
+
235
+ import { useEffect, useState } from 'react'
236
+
237
+ export default () => {
238
+ const [open, setOpen] = useState(false)
239
+
240
+ useEffect(() => {
241
+ if (!open) return undefined
242
+
243
+ const close = () => setOpen(false)
244
+ const handleKeyDown = (event: KeyboardEvent) => {
245
+ if (event.key === 'Escape') {
246
+ close()
247
+ }
248
+ }
249
+
250
+ window.addEventListener('pointerdown', close)
251
+ window.addEventListener('keydown', handleKeyDown)
252
+ return () => {
253
+ window.removeEventListener('pointerdown', close)
254
+ window.removeEventListener('keydown', handleKeyDown)
255
+ }
256
+ }, [open])
257
+
258
+ return (
259
+ <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
260
+ <Button onClick={() => setOpen(true)} disabled={open}>
261
+ 显示全屏加载
262
+ </Button>
263
+ <span>{open ? '点击任意位置或按 Esc 关闭' : '点击按钮查看全屏加载'}</span>
264
+ {open ? <Spin fullscreen spinning description="全屏加载中…" aria-label="全屏加载" /> : null}
265
+ </div>
266
+ )
267
+ }
268
+ ```
269
+
270
+ ## DOM 结构
271
+
272
+ 源码声明的静态 `data-slot`:`spin-indicator`、`spin-description`、`spin-section`、`spin`、`spin-mask`。具体节点随模式和状态出现,不表示固定嵌套顺序。
273
+
274
+ ## 样式定制
275
+
276
+ 优先使用本组件公开的尺寸、类型和状态属性。换肤与变量覆盖方式见 [主题指南](../../llms-theme.txt)。
277
+
278
+ 需要定制具体样式时再读取 [Token 明细](./tokens.txt),其中包含用途、定义值及适用作用域。常规组件使用无需加载该文件。
279
+
280
+ ## FAQ
281
+
282
+ ### `fullscreen` 时遮罩挂载在哪里?
283
+
284
+ `fullscreen` 且 `spinning` 为 `true` 时,遮罩通过 Portal 挂载到 `document.body`。
285
+
286
+
287
+ ### 包裹内容时为什么点不了里面的按钮?
288
+
289
+ 加载中会降低内容透明度并禁用内容区域交互,这是预期行为;加载完成后 `spinning={false}` 即可恢复。
290
+
291
+
292
+ ### 为什么不提供 `percent` 进度环?
293
+
294
+ Spin 仅表达不确定等待;有具体百分比时请使用 Progress 组件。
@@ -0,0 +1,21 @@
1
+ # Spin Token 明细
2
+
3
+ 包:`@apexhub/apex-ui-react`;版本:`1.2.0`(当前源码快照)。
4
+
5
+ 按需读取:[组件用法](./llm.txt) · [主题与覆盖规则](../../llms-theme.txt)。
6
+
7
+ 以下组件变量在设计 Token 源中已定义,并被组件或其共享样式使用;不包含仅在实现中声明的临时变量。用途来自实际 CSS 属性,不是对外新增的 Props。
8
+
9
+ 定义值依赖所列尺寸、变体、状态和媒体作用域;Alias 引用还会随 light/dark 主题改变。它们不是统一默认值或最终计算值。作用域用于解释定义位置,不代表内部选择器是稳定的定制 API。
10
+
11
+ | Token | 用途(CSS 属性) | 定义值 | 定义作用域 |
12
+ | --- | --- | --- | --- |
13
+ | `--overlay-fill-default` | `background-color` | `var(--apex-fill-neutral-overlay)` | `.apex-overlay.apex-default-overlay` |
14
+ | `--spin-fill-default` | `color` | `var(--apex-fill-brand-primary)` | `.apex-spin.apex-default-spin` |
15
+ | `--spin-spacing-gap` | `gap` | `var(--apex-spacing-6)` | `.apex-spin.apex-lg-spin` |
16
+ | `--spin-spacing-gap` | `gap` | `var(--apex-spacing-4)` | `.apex-spin.apex-md-spin` |
17
+ | `--spin-spacing-gap` | `gap` | `var(--apex-spacing-4)` | `.apex-spin.apex-sm-spin` |
18
+ | `--spin-spacing-height` | `font-size`、`height`、`width` | `var(--apex-size-48)` | `.apex-spin.apex-lg-spin` |
19
+ | `--spin-spacing-height` | `font-size`、`height`、`width` | `var(--apex-size-32)` | `.apex-spin.apex-md-spin` |
20
+ | `--spin-spacing-height` | `font-size`、`height`、`width` | `var(--apex-size-16)` | `.apex-spin.apex-sm-spin` |
21
+ | `--spin-text-default` | `color` | `var(--apex-text-neutral-primary)` | `.apex-spin.apex-default-spin` |
@@ -0,0 +1,300 @@
1
+ # Steps
2
+
3
+ > Steps:分步表单、向导、下单流程等需要展示当前所处阶段时。
4
+
5
+ 包:`@apexhub/apex-ui-react`;版本:`1.2.0`(当前源码快照,发布状态以安装包版本为准)。
6
+
7
+ 公开导出:`Steps`。
8
+
9
+ 以下 API 属于 Apex UI;不要据 antd 的同名组件推断额外属性或默认值。默认值列的空缺表示未声明,不代表 `false`。
10
+
11
+ ## 快速开始
12
+
13
+ ```tsx
14
+ import { Steps } from '@apexhub/apex-ui-react'
15
+
16
+ import '@apexhub/apex-ui-react/style.css'
17
+
18
+ export default () => (
19
+ <Steps
20
+ current={1}
21
+ items={[
22
+ { title: '已完成', content: '这一步已经处理完毕。' },
23
+ { title: '进行中', content: '当前正在进行的步骤。' },
24
+ { title: '等待中', content: '后续待处理的步骤。' },
25
+ ]}
26
+ />
27
+ )
28
+ ```
29
+
30
+ ## 何时使用
31
+
32
+ - 分步表单、向导、下单流程等需要展示当前所处阶段时。
33
+ - 需要让用户了解整体进度,并可在已完成步骤间跳转时(配合 变更事件)。
34
+ - 若步骤极少且无需可视化进度,用 Tabs 或分页可能更合适。
35
+
36
+ ## API
37
+
38
+ 仅使用类型定义支持的属性;原生属性、ref 目标和事件签名因组件而异。关联类型用于解释字段结构;只有「导出类型」中的名称可从包根导入。
39
+
40
+ ### Steps
41
+
42
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
43
+ | --- | --- | --- | --- | --- |
44
+ | items | 步骤列表。 | `StepItem[]` | 否 | `[]` |
45
+ | current | 受控当前步骤索引(从 0 起)。<br>未传时组件以非受控模式运行,内部状态初始为 `0`。 | `number` | 否 | — |
46
+ | initial | 步骤序号起始偏移(从 0 起),用于默认类型图标内显示的步骤编号:`index + initial + 1`。 | `number` | 否 | `0` |
47
+ | status | 当前步骤的全局状态;可覆盖由 `current` 推导出的进行中态。<br>- `wait` / `process` / `finish` / `error` | `"wait" \| "process" \| "finish" \| "error"` | 否 | `'process'` |
48
+ | orientation | 步骤条方向。 | `"horizontal" \| "vertical"` | 否 | `'horizontal'` |
49
+ | responsive | 视口宽度小于 532px 时是否自动切换为纵向。 | `boolean` | 否 | `true` |
50
+ | size | 步骤图标尺寸。 | `"medium" \| "small"` | 否 | `'medium'` |
51
+ | titlePlacement | 标题区域与图标的排布方向。 | `"horizontal" \| "vertical"` | 否 | `'horizontal'` |
52
+ | iconRender | 自定义图标渲染;`items[].icon` 存在时优先使用 `icon`。 | `StepIconRender` | 否 | — |
53
+ | onChange | 切换步骤时的回调。 | `(current: number) => void` | 否 | — |
54
+ | className | 根节点类名 | `string` | 否 | — |
55
+ | style | 根节点内联样式;禁止硬编码色值 | `React.CSSProperties` | 否 | — |
56
+ | ref | 根节点 ref | `React.Ref<HTMLDivElement>` | 否 | — |
57
+
58
+ ### StepStatus
59
+
60
+ 单个步骤的状态。
61
+
62
+ ```typescript
63
+ type StepStatus = 'wait' | 'process' | 'finish' | 'error'
64
+ ```
65
+
66
+ ### StepsSize
67
+
68
+ 步骤图标尺寸
69
+
70
+ ```typescript
71
+ type StepsSize = 'medium' | 'small'
72
+ ```
73
+
74
+ ### StepsOrientation
75
+
76
+ 步骤条整体方向
77
+
78
+ ```typescript
79
+ type StepsOrientation = 'horizontal' | 'vertical'
80
+ ```
81
+
82
+ ### StepsTitlePlacement
83
+
84
+ 标题与图标区域的排布方向
85
+
86
+ ```typescript
87
+ type StepsTitlePlacement = 'horizontal' | 'vertical'
88
+ ```
89
+
90
+ ### StepItem
91
+
92
+ 单个步骤项。
93
+
94
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
95
+ | --- | --- | --- | --- | --- |
96
+ | title | 步骤标题。 | `React.ReactNode` | 否 | — |
97
+ | subTitle | 步骤副标题。 | `React.ReactNode` | 否 | — |
98
+ | content | 步骤描述内容(可选)。 | `React.ReactNode` | 否 | — |
99
+ | icon | 步骤图标;优先级高于 `iconRender` 的默认节点。 | `React.ReactNode` | 否 | — |
100
+ | status | 步骤状态;未配置时由 `Steps.current` 与根级 `status` 自动推导。 | `"wait" \| "process" \| "finish" \| "error"` | 否 | `'wait'` |
101
+ | disabled | 禁用点击。 | `boolean` | 否 | `false` |
102
+
103
+ ### StepIconRenderInfo
104
+
105
+ `iconRender` 回调的上下文信息。
106
+
107
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
108
+ | --- | --- | --- | --- | --- |
109
+ | index | 步骤索引(从 0 起) | `number` | 是 | — |
110
+ | active | 是否为当前激活步骤 | `boolean` | 是 | — |
111
+ | item | 当前步骤项数据 | `StepItem` | 是 | — |
112
+
113
+ ### StepIconRender
114
+
115
+ 自定义步骤图标渲染。
116
+
117
+ ```typescript
118
+ type StepIconRender = (
119
+ originNode: React.ReactNode,
120
+ info: StepIconRenderInfo,
121
+ ) => React.ReactNode
122
+ ```
123
+
124
+ ### 导出类型
125
+
126
+ 另可从 `@apexhub/apex-ui-react` 导入:`StepIconRender`、`StepIconRenderInfo`、`StepItem`、`StepStatus`、`StepsOrientation`、`StepsProps`、`StepsSize`、`StepsTitlePlacement`(与上文子类型配合使用)。
127
+
128
+ ## 代码演示
129
+
130
+ ### 步骤切换
131
+
132
+ 配合 `current` 与 变更事件 受控驱动,常用于「上一步 / 下一步」向导。
133
+
134
+ ```tsx
135
+ import { Button, Steps } from '@apexhub/apex-ui-react'
136
+
137
+ import { useState } from 'react'
138
+
139
+ const items = [{ title: '第一步' }, { title: '第二步' }, { title: '第三步' }]
140
+
141
+ export default () => {
142
+ const [current, setCurrent] = useState(0)
143
+ const maxStep = items.length - 1
144
+
145
+ return (
146
+ <div>
147
+ <Steps current={current} onChange={setCurrent} items={items} />
148
+ <div style={{ display: 'flex', gap: 8, marginTop: 16 }}>
149
+ <Button disabled={current <= 0} onClick={() => setCurrent((step) => step - 1)}>
150
+ 上一步
151
+ </Button>
152
+ <Button
153
+ type="primary"
154
+ disabled={current >= maxStep}
155
+ onClick={() => setCurrent((step) => step + 1)}
156
+ >
157
+ 下一步
158
+ </Button>
159
+ </div>
160
+ </div>
161
+ )
162
+ }
163
+ ```
164
+
165
+ ### 尺寸
166
+
167
+ 通过 `size` 在 `medium`(默认)与 `small` 两种图标尺寸间切换。
168
+
169
+ ```tsx
170
+ import { Steps } from '@apexhub/apex-ui-react'
171
+
172
+ const items = [{ title: '已完成' }, { title: '进行中' }, { title: '等待中' }]
173
+
174
+ export default () => (
175
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 24 }}>
176
+ <Steps size="medium" current={1} items={items} />
177
+ <Steps size="small" current={1} items={items} />
178
+ </div>
179
+ )
180
+ ```
181
+
182
+ ### 纵向步骤条
183
+
184
+ 设置 `orientation="vertical"` 纵向排列;默认 `responsive` 开启时,窄屏会自动转为纵向。
185
+
186
+ ```tsx
187
+ import { Steps } from '@apexhub/apex-ui-react'
188
+
189
+ export default () => (
190
+ <div style={{ height: 320 }}>
191
+ <Steps
192
+ orientation="vertical"
193
+ current={1}
194
+ items={[
195
+ { title: '已完成', content: '这一步已经处理完毕。' },
196
+ { title: '进行中', content: '当前正在进行的步骤。' },
197
+ { title: '等待中', content: '后续待处理的步骤。' },
198
+ ]}
199
+ />
200
+ </div>
201
+ )
202
+ ```
203
+
204
+ ### 错误状态
205
+
206
+ 通过 `status="error"` 标记当前步骤出错,也可在 `items[].status` 上单独指定某一步的状态。
207
+
208
+ ```tsx
209
+ import { Steps } from '@apexhub/apex-ui-react'
210
+
211
+ export default () => (
212
+ <Steps
213
+ current={1}
214
+ status="error"
215
+ items={[{ title: '已完成' }, { title: '当前步骤出错' }, { title: '等待中' }]}
216
+ />
217
+ )
218
+ ```
219
+
220
+ ### 描述与副标题
221
+
222
+ `subTitle` 展示标题旁的次要信息,`content` 展示步骤的描述内容。
223
+
224
+ ```tsx
225
+ import { Steps } from '@apexhub/apex-ui-react'
226
+
227
+ export default () => (
228
+ <Steps
229
+ current={1}
230
+ items={[
231
+ { title: '登录', subTitle: '已于 08:00 完成', content: '填写账号与密码。' },
232
+ { title: '验证', subTitle: '剩余 00:30', content: '输入短信验证码。' },
233
+ { title: '完成', content: '所有步骤已结束。' },
234
+ ]}
235
+ />
236
+ )
237
+ ```
238
+
239
+ ### 自定义图标
240
+
241
+ `items[].icon` 直接替换某一步的图标;`iconRender` 可统一改写默认图标节点。
242
+
243
+ ```tsx
244
+ import { Steps } from '@apexhub/apex-ui-react'
245
+
246
+ export default () => (
247
+ <Steps
248
+ current={1}
249
+ iconRender={(origin, info) => (info.active ? '●' : origin)}
250
+ items={[{ title: '登录', icon: '👤' }, { title: '验证' }, { title: '完成', icon: '✓' }]}
251
+ />
252
+ )
253
+ ```
254
+
255
+ ### 禁用步骤
256
+
257
+ 在 `items[].disabled` 上禁用某一步,该步不可点击也不会触发 变更事件。
258
+
259
+ ```tsx
260
+ import { Steps } from '@apexhub/apex-ui-react'
261
+
262
+ export default () => (
263
+ <Steps
264
+ current={0}
265
+ onChange={(next) => console.log('切换到', next)}
266
+ items={[{ title: '可点击' }, { title: '已禁用', disabled: true }, { title: '等待中' }]}
267
+ />
268
+ )
269
+ ```
270
+
271
+ ## DOM 结构
272
+
273
+ 源码声明的静态 `data-slot`:`steps-item`、`steps-item-wrapper`、`steps-item-icon`、`steps-item-header`、`steps-item-title`、`steps-item-subtitle`、`steps-item-section`、`steps-item-content`、`steps-item-rail`、`steps`。具体节点随模式和状态出现,不表示固定嵌套顺序。
274
+
275
+ ## 样式定制
276
+
277
+ 优先使用本组件公开的尺寸、类型和状态属性。换肤与变量覆盖方式见 [主题指南](../../llms-theme.txt)。
278
+
279
+ 需要定制具体样式时再读取 [Token 明细](./tokens.txt),其中包含用途、定义值及适用作用域。常规组件使用无需加载该文件。
280
+
281
+ ## FAQ
282
+
283
+ ### 为什么没有 `defaultCurrent`?
284
+
285
+ 非受控模式下内部初始步骤固定为 `0`;若需从其他步骤开始,请使用受控 `current`。
286
+
287
+ ### `initial` 和 `current` 有什么区别?
288
+
289
+ `current` 决定当前激活到哪一步;`initial` 只影响序号展示(如图标内数字从 `initial + 1` 起算),不改变激活步骤。
290
+
291
+
292
+ ### 点击步骤没反应?
293
+
294
+ 须传入 `onChange` 才会响应点击;未传 `onChange` 时步骤条为只读展示。被 `disabled` 标记的步骤也不可点击。
295
+
296
+
297
+
298
+ ### 为什么没有 antd 的 `type="dot"` 点状步骤?
299
+
300
+ v1 仅提供默认序号图标步骤条,不提供点状(dot)类型;需要更紧凑展示时可使用 `size="small"` 或自定义 `iconRender`。
@@ -0,0 +1,30 @@
1
+ # Steps Token 明细
2
+
3
+ 包:`@apexhub/apex-ui-react`;版本:`1.2.0`(当前源码快照)。
4
+
5
+ 按需读取:[组件用法](./llm.txt) · [主题与覆盖规则](../../llms-theme.txt)。
6
+
7
+ 以下组件变量在设计 Token 源中已定义,并被组件或其共享样式使用;不包含仅在实现中声明的临时变量。用途来自实际 CSS 属性,不是对外新增的 Props。
8
+
9
+ 定义值依赖所列尺寸、变体、状态和媒体作用域;Alias 引用还会随 light/dark 主题改变。它们不是统一默认值或最终计算值。作用域用于解释定义位置,不代表内部选择器是稳定的定制 API。
10
+
11
+ | Token | 用途(CSS 属性) | 定义值 | 定义作用域 |
12
+ | --- | --- | --- | --- |
13
+ | `--steps-fill-active` | `background-color`、`border-color` | `var(--apex-fill-brand-primary)` | `.apex-steps.apex-default-steps` |
14
+ | `--steps-fill-completed` | `background-color` | `var(--apex-fill-brand-alpha-primary)` | `.apex-steps.apex-default-steps` |
15
+ | `--steps-fill-default` | `background-color`、`border-color` | `var(--apex-fill-neutral-quinary)` | `.apex-steps.apex-default-steps` |
16
+ | `--steps-fill-disabled` | `background-color`、`border-color` | `var(--apex-fill-error-alpha-secondary)` | `.apex-steps.apex-default-steps` |
17
+ | `--steps-icon-active` | `color` | `var(--apex-icon-neutral-quaternary-stable)` | `.apex-steps.apex-default-steps` |
18
+ | `--steps-icon-completed` | `color` | `var(--apex-icon-brand-primary)` | `.apex-steps.apex-default-steps` |
19
+ | `--steps-icon-default` | `color` | `var(--apex-icon-neutral-tertiary)` | `.apex-steps.apex-default-steps` |
20
+ | `--steps-spacing-content` | `height`、`left`、`margin-inline-start`、`top`、`width` | `var(--apex-size-32)` | `.apex-steps.apex-default-steps` |
21
+ | `--steps-spacing-gap` | `gap` | `var(--apex-size-8)` | `.apex-steps.apex-default-steps` |
22
+ | `--steps-spacing-gap-content-stroke` | `column-gap`、`left`、`margin-inline-end`、`outline-offset`、`top` | `var(--apex-spacing-8)` | `.apex-steps.apex-default-steps` |
23
+ | `--steps-spacing-gap-content-text` | `gap`、`row-gap` | `var(--apex-spacing-8)` | `.apex-steps.apex-default-steps` |
24
+ | `--steps-spacing-gap-text` | `gap`、`margin-inline-start` | `var(--apex-spacing-8)` | `.apex-steps.apex-default-steps` |
25
+ | `--steps-stroke-completed` | `border-color`、`outline` | `var(--apex-stroke-brand-primary)` | `.apex-steps.apex-default-steps` |
26
+ | `--steps-stroke-disabled` | `border-color` | `var(--apex-stroke-error-primary)` | `.apex-steps.apex-default-steps` |
27
+ | `--steps-stroke-pending` | `border-color`、`border-left`、`border-top` | `var(--apex-stroke-neutral-quinary)` | `.apex-steps.apex-default-steps` |
28
+ | `--steps-stroke-stroke` | `border`、`border-left`、`border-top`、`outline` | `var(--apex-border-1)` | `.apex-steps.apex-default-steps` |
29
+ | `--steps-text-description` | `color` | `var(--apex-text-neutral-tertiary)` | `.apex-steps.apex-default-steps` |
30
+ | `--steps-text-title` | `color` | `var(--apex-text-neutral-primary)` | `.apex-steps.apex-default-steps` |