@apexhub/apex-ui-react 0.0.0-stage → 1.2.2

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 +40727 -0
  5. package/dist/index.d.ts +6873 -0
  6. package/dist/index.mjs +40711 -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 +369 -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 +143 -0
  15. package/dist/llm/breadcrumb.txt +251 -0
  16. package/dist/llm/button.tokens.txt +470 -0
  17. package/dist/llm/button.txt +270 -0
  18. package/dist/llm/card.tokens.txt +29 -0
  19. package/dist/llm/card.txt +118 -0
  20. package/dist/llm/cascader.tokens.txt +261 -0
  21. package/dist/llm/cascader.txt +917 -0
  22. package/dist/llm/checkbox.tokens.txt +36 -0
  23. package/dist/llm/checkbox.txt +343 -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 +428 -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 +28 -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 +491 -0
  41. package/dist/llm/input.tokens.txt +136 -0
  42. package/dist/llm/input.txt +424 -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 +100 -0
  46. package/dist/llm/menu.txt +687 -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 +35 -0
  54. package/dist/llm/pagination.txt +217 -0
  55. package/dist/llm/popover.tokens.txt +18 -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 +26 -0
  60. package/dist/llm/radio.txt +385 -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 +831 -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 +1049 -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 +75 -0
  78. package/dist/llm/tag.txt +304 -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 +175 -0
  82. package/dist/llm/tree-select.txt +772 -0
  83. package/dist/llm/tree.tokens.txt +34 -0
  84. package/dist/llm/tree.txt +501 -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 +205 -0
  88. package/dist/llm/upload.txt +708 -0
  89. package/dist/llms-full.txt +16826 -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 +20095 -0
  99. package/dist/zh_CN.d.ts +191 -0
  100. package/llms-full.txt +16826 -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 +369 -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 +143 -0
  113. package/src/button/llm.txt +270 -0
  114. package/src/button/tokens.txt +470 -0
  115. package/src/card/llm.txt +118 -0
  116. package/src/card/tokens.txt +29 -0
  117. package/src/cascader/llm.txt +917 -0
  118. package/src/cascader/tokens.txt +261 -0
  119. package/src/checkbox/llm.txt +343 -0
  120. package/src/checkbox/tokens.txt +36 -0
  121. package/src/collapse/llm.txt +330 -0
  122. package/src/collapse/tokens.txt +84 -0
  123. package/src/date-picker/llm.txt +428 -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 +28 -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 +424 -0
  137. package/src/input/tokens.txt +136 -0
  138. package/src/input-number/llm.txt +491 -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 +687 -0
  143. package/src/menu/tokens.txt +100 -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 +217 -0
  151. package/src/pagination/tokens.txt +35 -0
  152. package/src/popover/llm.txt +233 -0
  153. package/src/popover/tokens.txt +18 -0
  154. package/src/progress/llm.txt +279 -0
  155. package/src/progress/tokens.txt +83 -0
  156. package/src/radio/llm.txt +385 -0
  157. package/src/radio/tokens.txt +26 -0
  158. package/src/rate/llm.txt +241 -0
  159. package/src/rate/tokens.txt +20 -0
  160. package/src/select/llm.txt +831 -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 +1049 -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 +304 -0
  175. package/src/tag/tokens.txt +75 -0
  176. package/src/tooltip/llm.txt +304 -0
  177. package/src/tooltip/tokens.txt +22 -0
  178. package/src/tree/llm.txt +501 -0
  179. package/src/tree/tokens.txt +34 -0
  180. package/src/tree-select/llm.txt +772 -0
  181. package/src/tree-select/tokens.txt +175 -0
  182. package/src/typography/llm.txt +413 -0
  183. package/src/typography/tokens.txt +60 -0
  184. package/src/upload/llm.txt +708 -0
  185. package/src/upload/tokens.txt +205 -0
@@ -0,0 +1,383 @@
1
+ # Notification
2
+
3
+ > Notification:操作完成后的全局反馈,需要用户注意到但不必立即处理时。
4
+
5
+ 包:`@apexhub/apex-ui-react`;版本:`1.2.2`(当前源码快照,发布状态以安装包版本为准)。
6
+
7
+ 公开导出:`notification`。
8
+
9
+ 以下 API 属于 Apex UI;不要据 antd 的同名组件推断额外属性或默认值。默认值列的空缺表示未声明,不代表 `false`。
10
+
11
+ ## 快速开始
12
+
13
+ ```tsx
14
+ import { Button, notification } from '@apexhub/apex-ui-react'
15
+
16
+ import { useEffect } from 'react'
17
+
18
+ import '@apexhub/apex-ui-react/style.css'
19
+
20
+ export default () => {
21
+ useEffect(() => () => notification.destroy(), [])
22
+
23
+ return (
24
+ <Button
25
+ type="primary"
26
+ onClick={() =>
27
+ notification.open({
28
+ title: '通知标题',
29
+ description: '这是一条普通通知的正文内容。',
30
+ })
31
+ }
32
+ >
33
+ 打开通知
34
+ </Button>
35
+ )
36
+ }
37
+ ```
38
+
39
+ ## 何时使用
40
+
41
+ - 操作完成后的全局反馈,需要用户注意到但不必立即处理时。
42
+ - 正文较长、需要标题 + 描述结构的提醒,比 Message 更适合承载多行内容时。
43
+ - 若只需一行轻量提示、自动消失即可,请使用 Message;若需阻断操作并等待确认,请使用 Modal。
44
+
45
+ ## API
46
+
47
+ 仅使用类型定义支持的属性;原生属性、ref 目标和事件签名因组件而异。关联类型用于解释字段结构;只有「导出类型」中的名称可从包根导入。
48
+
49
+ ### 使用入口
50
+
51
+ 通过 `notification` 使用,配置与方法见下方关联类型。
52
+
53
+ ### NotificationType
54
+
55
+ ```typescript
56
+ type NotificationType = 'info' | 'success' | 'error' | 'warning'
57
+ ```
58
+
59
+ ### NotificationPlacement
60
+
61
+ ```typescript
62
+ type NotificationPlacement = | 'top'
63
+ | 'topLeft'
64
+ | 'topRight'
65
+ | 'bottom'
66
+ | 'bottomLeft'
67
+ | 'bottomRight'
68
+ ```
69
+
70
+ ### NotificationOnClose
71
+
72
+ ```typescript
73
+ type NotificationOnClose = () => void
74
+ ```
75
+
76
+ ### NotificationHandle
77
+
78
+ Notification 调用返回句柄。
79
+
80
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
81
+ | --- | --- | --- | --- | --- |
82
+ | id | 当前通知的内部标识,仅用于调试与测试断言。 | `string` | 是 | — |
83
+ | close | 关闭当前通知;重复调用无副作用。 | `() => void` | 是 | — |
84
+
85
+ ### NotificationOpenConfig
86
+
87
+ Notification.open 配置。
88
+
89
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
90
+ | --- | --- | --- | --- | --- |
91
+ | title | 通知标题。 | `React.ReactNode` | 是 | `undefined` |
92
+ | description | 通知正文内容。 | `React.ReactNode` | 否 | `undefined` |
93
+ | duration | 自动关闭延时,单位秒;传 `0` 时不自动关闭。 | `number` | 否 | `4.5` |
94
+ | placement | 通知弹出位置。<br>- `top`:顶部居中<br>- `topLeft`:左上角<br>- `topRight`:右上角<br>- `bottom`:底部居中<br>- `bottomLeft`:左下角<br>- `bottomRight`:右下角 | `"top" \| "topLeft" \| "topRight" \| "bottom" \| "bottomLeft" \| "bottomRight"` | 否 | `'topRight'` |
95
+ | closable | 是否显示右上角关闭按钮。 | `boolean` | 否 | `true` |
96
+ | closeIcon | 自定义关闭图标;传 `false` / `null` 时隐藏关闭按钮。 | `React.ReactNode` | 否 | `undefined` |
97
+ | icon | 自定义语义图标;未传时快捷方法按类型渲染默认语义图标。 | `React.ReactNode` | 否 | `undefined` |
98
+ | onClose | 当前通知关闭后触发。 | `NotificationOnClose` | 否 | `undefined` |
99
+ | onClick | 点击当前通知时触发。 | `React.ComponentProps<'div'>['onClick']` | 否 | `undefined` |
100
+ | className | 当前通知根节点类名,作用于 `data-slot="notification"`。 | `React.ComponentProps<'div'>['className']` | 否 | `undefined` |
101
+ | style | 当前通知根节点样式;禁止硬编码色值,优先使用 CSS Token。 | `React.ComponentProps<'div'>['style']` | 否 | `undefined` |
102
+
103
+ ### NotificationApi
104
+
105
+ Notification 命令式 API。
106
+
107
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
108
+ | --- | --- | --- | --- | --- |
109
+ | open | 打开一条普通通知。 | `(config: NotificationOpenConfig) => NotificationHandle` | 是 | — |
110
+ | success | 打开成功通知。 | `(config: NotificationOpenConfig) => NotificationHandle` | 是 | — |
111
+ | error | 打开错误通知。 | `(config: NotificationOpenConfig) => NotificationHandle` | 是 | — |
112
+ | info | 打开普通信息通知。 | `(config: NotificationOpenConfig) => NotificationHandle` | 是 | — |
113
+ | warning | 打开警告通知。 | `(config: NotificationOpenConfig) => NotificationHandle` | 是 | — |
114
+ | destroy | 关闭所有通知。 | `() => void` | 是 | — |
115
+
116
+ ### 导出类型
117
+
118
+ 另可从 `@apexhub/apex-ui-react` 导入:`NotificationApi`、`NotificationHandle`、`NotificationOpenConfig`、`NotificationPlacement`、`NotificationType`(与上文子类型配合使用)。
119
+
120
+ ## 代码演示
121
+
122
+ ### 语义类型
123
+
124
+ `notification.success` / `error` / `info` / `warning` 按类型展示对应语义图标与样式。
125
+
126
+ ```tsx
127
+ import { Button, notification } from '@apexhub/apex-ui-react'
128
+
129
+ import { useEffect } from 'react'
130
+
131
+ const rowStyle = { display: 'flex', gap: 8, flexWrap: 'wrap' as const }
132
+
133
+ export default () => {
134
+ useEffect(() => () => notification.destroy(), [])
135
+
136
+ return (
137
+ <div style={rowStyle}>
138
+ <Button onClick={() => notification.success({ title: '成功', description: '操作已完成' })}>
139
+ success
140
+ </Button>
141
+ <Button onClick={() => notification.error({ title: '错误', description: '请稍后重试' })}>
142
+ error
143
+ </Button>
144
+ <Button onClick={() => notification.warning({ title: '警告', description: '请注意' })}>
145
+ warning
146
+ </Button>
147
+ <Button onClick={() => notification.info({ title: '信息', description: '普通提示' })}>
148
+ info
149
+ </Button>
150
+ </div>
151
+ )
152
+ }
153
+ ```
154
+
155
+ ### 弹出位置
156
+
157
+ 通过 `placement` 指定通知出现位置,支持六个角落与上下居中。
158
+
159
+ ```tsx
160
+ import type { NotificationPlacement } from '@apexhub/apex-ui-react'
161
+
162
+ import { Button, notification } from '@apexhub/apex-ui-react'
163
+
164
+ import { useEffect } from 'react'
165
+
166
+ const gridStyle = {
167
+ display: 'grid',
168
+ gridTemplateColumns: 'repeat(3, 7.5rem)',
169
+ gap: 8,
170
+ } as const
171
+
172
+ const rows: NotificationPlacement[][] = [
173
+ ['topLeft', 'top', 'topRight'],
174
+ ['bottomLeft', 'bottom', 'bottomRight'],
175
+ ]
176
+
177
+ export default () => {
178
+ useEffect(() => () => notification.destroy(), [])
179
+
180
+ return (
181
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 8, alignItems: 'center' }}>
182
+ {rows.map((row) => (
183
+ <div key={row.join('-')} style={gridStyle}>
184
+ {row.map((placement) => (
185
+ <Button
186
+ key={placement}
187
+ style={{ width: '100%' }}
188
+ onClick={() =>
189
+ notification.open({
190
+ title: placement,
191
+ description: '位置演示',
192
+ placement,
193
+ duration: 0,
194
+ })
195
+ }
196
+ >
197
+ {placement}
198
+ </Button>
199
+ ))}
200
+ </div>
201
+ ))}
202
+ </div>
203
+ )
204
+ }
205
+ ```
206
+
207
+ ### 自动关闭与常驻
208
+
209
+ `duration` 控制自动关闭秒数;设为 `0` 时不自动关闭,须手动关闭或调用 `destroy`。
210
+
211
+ ```tsx
212
+ import { Button, notification } from '@apexhub/apex-ui-react'
213
+
214
+ import { useEffect } from 'react'
215
+
216
+ const rowStyle = { display: 'flex', gap: 8, flexWrap: 'wrap' as const }
217
+
218
+ export default () => {
219
+ useEffect(() => () => notification.destroy(), [])
220
+
221
+ return (
222
+ <div style={rowStyle}>
223
+ <Button
224
+ onClick={() =>
225
+ notification.info({
226
+ title: '0.5s 后关闭',
227
+ description: '短时通知',
228
+ duration: 0.5,
229
+ })
230
+ }
231
+ >
232
+ 短时
233
+ </Button>
234
+ <Button
235
+ onClick={() =>
236
+ notification.info({
237
+ title: '常驻通知',
238
+ description: 'duration=0',
239
+ duration: 0,
240
+ })
241
+ }
242
+ >
243
+ 常驻
244
+ </Button>
245
+ </div>
246
+ )
247
+ }
248
+ ```
249
+
250
+ ### 可关闭
251
+
252
+ 默认展示右上角关闭按钮;`closable` 设为 `false` 可隐藏。
253
+
254
+ ```tsx
255
+ import { Button, notification } from '@apexhub/apex-ui-react'
256
+
257
+ import { useEffect } from 'react'
258
+
259
+ const rowStyle = { display: 'flex', gap: 8, flexWrap: 'wrap' as const }
260
+
261
+ export default () => {
262
+ useEffect(() => () => notification.destroy(), [])
263
+
264
+ return (
265
+ <div style={rowStyle}>
266
+ <Button
267
+ type="primary"
268
+ onClick={() =>
269
+ notification.info({
270
+ title: '可手动关闭',
271
+ description: '默认显示关闭按钮',
272
+ duration: 0,
273
+ })
274
+ }
275
+ >
276
+ 带关闭
277
+ </Button>
278
+ <Button
279
+ onClick={() =>
280
+ notification.info({
281
+ title: '不可关闭',
282
+ description: 'closable=false',
283
+ duration: 0,
284
+ closable: false,
285
+ })
286
+ }
287
+ >
288
+ 无关闭
289
+ </Button>
290
+ </div>
291
+ )
292
+ }
293
+ ```
294
+
295
+ ### 句柄关闭
296
+
297
+ `notification.open()` 返回的 `NotificationHandle` 提供 `close()` 方法,可在外部主动关闭单条通知。
298
+
299
+ ```tsx
300
+ import { Button, notification } from '@apexhub/apex-ui-react'
301
+
302
+ import { useEffect, useRef } from 'react'
303
+
304
+ const rowStyle = { display: 'flex', gap: 8, flexWrap: 'wrap' as const }
305
+
306
+ export default () => {
307
+ const closeRef = useRef<(() => void) | undefined>(undefined)
308
+
309
+ useEffect(() => () => notification.destroy(), [])
310
+
311
+ return (
312
+ <div style={rowStyle}>
313
+ <Button
314
+ type="primary"
315
+ onClick={() => {
316
+ closeRef.current = notification.warning({
317
+ title: '处理中',
318
+ description: '点击完成关闭',
319
+ duration: 0,
320
+ }).close
321
+ }}
322
+ >
323
+ 开始
324
+ </Button>
325
+ <Button onClick={() => closeRef.current?.()}>完成</Button>
326
+ </div>
327
+ )
328
+ }
329
+ ```
330
+
331
+ ### 销毁全部
332
+
333
+ `notification.destroy()` 关闭当前所有通知。
334
+
335
+ ```tsx
336
+ import { Button, notification } from '@apexhub/apex-ui-react'
337
+
338
+ import { useEffect } from 'react'
339
+
340
+ const rowStyle = { display: 'flex', gap: 8, flexWrap: 'wrap' as const }
341
+
342
+ export default () => {
343
+ useEffect(() => () => notification.destroy(), [])
344
+
345
+ return (
346
+ <div style={rowStyle}>
347
+ <Button
348
+ type="primary"
349
+ onClick={() => {
350
+ notification.info({ title: 'A', duration: 0 })
351
+ notification.success({ title: 'B', duration: 0 })
352
+ notification.warning({ title: 'C', duration: 0 })
353
+ }}
354
+ >
355
+ 弹出 3 条
356
+ </Button>
357
+ <Button onClick={() => notification.destroy()}>全部销毁</Button>
358
+ </div>
359
+ )
360
+ }
361
+ ```
362
+
363
+ ## DOM 结构
364
+
365
+ 源码声明的静态 `data-slot`:`notification-item`、`notification`、`notification-header`、`notification-icon`、`notification-title`、`notification-close`、`notification-description`、`notification-viewport`。具体节点随模式和状态出现,不表示固定嵌套顺序。
366
+
367
+ ## 样式定制
368
+
369
+ 优先使用本组件公开的尺寸、类型和状态属性。换肤与变量覆盖方式见 [主题指南](../../llms-theme.txt)。
370
+
371
+ 需要定制具体样式时再读取 [Token 明细](./tokens.txt),其中包含用途、定义值及适用作用域。常规组件使用无需加载该文件。
372
+
373
+ ## FAQ
374
+
375
+ ### 为什么 Notification 读不到 React 上下文?
376
+
377
+ v1 采用静态 singleton root 挂载,不经过组件树,因此无法读取 ApexProvider 等上下文。需要上下文时请等待后续 `useNotification` 能力,或改用声明式组件方案。
378
+
379
+
380
+
381
+ ### `duration={0}` 时如何关闭?
382
+
383
+ 可点击关闭按钮、调用返回句柄的 `close()`,或执行 `notification.destroy()` 关闭全部。
@@ -0,0 +1,79 @@
1
+ # Notification Token 明细
2
+
3
+ 包:`@apexhub/apex-ui-react`;版本:`1.2.2`(当前源码快照)。
4
+
5
+ 按需读取:[组件用法](./llm.txt) · [主题与覆盖规则](../../llms-theme.txt)。
6
+
7
+ 以下组件变量在设计 Token 源中已定义,并被组件或其共享样式使用;不包含仅在实现中声明的临时变量。用途来自实际 CSS 属性,不是对外新增的 Props。
8
+
9
+ 定义值依赖所列尺寸、变体、状态和媒体作用域;Alias 引用还会随 light/dark 主题改变。它们不是统一默认值或最终计算值。作用域用于解释定义位置,不代表内部选择器是稳定的定制 API。
10
+
11
+ | Token | 用途(CSS 属性) | 定义值 | 定义作用域 |
12
+ | --- | --- | --- | --- |
13
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-20)` | `.apex-font.apex-text-cn-body-font` |
14
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-18)` | `.apex-font.apex-text-cn-caption-font` |
15
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-36)` | `.apex-font.apex-text-cn-heading-1-font` |
16
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-28)` | `.apex-font.apex-text-cn-heading-2-font` |
17
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-24)` | `.apex-font.apex-text-cn-heading-3-font` |
18
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-24)` | `.apex-font.apex-text-cn-heading-4-font` |
19
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-20)` | `.apex-font.apex-text-en-body-font` |
20
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-18)` | `.apex-font.apex-text-en-caption-font` |
21
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-36)` | `.apex-font.apex-text-en-heading-1-font` |
22
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-28)` | `.apex-font.apex-text-en-heading-2-font` |
23
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-24)` | `.apex-font.apex-text-en-heading-3-font` |
24
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-24)` | `.apex-font.apex-text-en-heading-4-font` |
25
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-14)` | `.apex-font.apex-text-cn-body-font` |
26
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-12)` | `.apex-font.apex-text-cn-caption-font` |
27
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-24)` | `.apex-font.apex-text-cn-heading-1-font` |
28
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-18)` | `.apex-font.apex-text-cn-heading-2-font` |
29
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-16)` | `.apex-font.apex-text-cn-heading-3-font` |
30
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-16)` | `.apex-font.apex-text-cn-heading-4-font` |
31
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-14)` | `.apex-font.apex-text-en-body-font` |
32
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-12)` | `.apex-font.apex-text-en-caption-font` |
33
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-24)` | `.apex-font.apex-text-en-heading-1-font` |
34
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-18)` | `.apex-font.apex-text-en-heading-2-font` |
35
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-16)` | `.apex-font.apex-text-en-heading-3-font` |
36
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-16)` | `.apex-font.apex-text-en-heading-4-font` |
37
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-0)` | `.apex-font.apex-text-cn-body-font` |
38
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-0)` | `.apex-font.apex-text-cn-caption-font` |
39
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-0)` | `.apex-font.apex-text-cn-heading-1-font` |
40
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-0)` | `.apex-font.apex-text-cn-heading-2-font` |
41
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-8)` | `.apex-font.apex-text-cn-heading-3-font` |
42
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-0)` | `.apex-font.apex-text-cn-heading-4-font` |
43
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-1)` | `.apex-font.apex-text-en-body-font` |
44
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-1)` | `.apex-font.apex-text-en-caption-font` |
45
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-1)` | `.apex-font.apex-text-en-heading-1-font` |
46
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-1)` | `.apex-font.apex-text-en-heading-2-font` |
47
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-1)` | `.apex-font.apex-text-en-heading-3-font` |
48
+ | `--font-fontspacing` | `letter-spacing` | `var(--apex-fontspacing-1)` | `.apex-font.apex-text-en-heading-4-font` |
49
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-400)` | `.apex-font.apex-text-cn-body-font` |
50
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-400)` | `.apex-font.apex-text-cn-caption-font` |
51
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-600)` | `.apex-font.apex-text-cn-heading-1-font` |
52
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-600)` | `.apex-font.apex-text-cn-heading-2-font` |
53
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-600)` | `.apex-font.apex-text-cn-heading-3-font` |
54
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-400)` | `.apex-font.apex-text-cn-heading-4-font` |
55
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-400)` | `.apex-font.apex-text-en-body-font` |
56
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-400)` | `.apex-font.apex-text-en-caption-font` |
57
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-600)` | `.apex-font.apex-text-en-heading-1-font` |
58
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-600)` | `.apex-font.apex-text-en-heading-2-font` |
59
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-600)` | `.apex-font.apex-text-en-heading-3-font` |
60
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-400)` | `.apex-font.apex-text-en-heading-4-font` |
61
+ | `--notification-fill-default` | `background` | `var(--apex-fill-neutral-secondary)` | `.apex-notification.apex-default-notification` |
62
+ | `--notification-icon-error` | `color` | `var(--apex-icon-error-primary)` | `.apex-notification.apex-default-notification` |
63
+ | `--notification-icon-icon` | `font-size` | `var(--apex-icon-24)` | `.apex-notification.apex-default-notification` |
64
+ | `--notification-icon-info` | `color` | `var(--apex-icon-brand-primary)` | `.apex-notification.apex-default-notification` |
65
+ | `--notification-icon-success` | `color` | `var(--apex-icon-success-primary)` | `.apex-notification.apex-default-notification` |
66
+ | `--notification-icon-warning` | `color` | `var(--apex-icon-warning-primary)` | `.apex-notification.apex-default-notification` |
67
+ | `--notification-radius-radius` | `border-radius` | `var(--apex-radius-8)` | `.apex-notification.apex-default-notification` |
68
+ | `--notification-size-width` | `min-width` | `var(--apex-size-420)` | `.apex-notification.apex-default-notification` |
69
+ | `--notification-spacing-gap-container` | `gap` | `var(--apex-spacing-8)` | `.apex-notification.apex-default-notification` |
70
+ | `--notification-spacing-gap-header` | `gap` | `var(--apex-spacing-4)` | `.apex-notification.apex-default-notification` |
71
+ | `--notification-spacing-margin-x-container` | `left`、`max-width`、`right` | `var(--apex-spacing-16)` | `.apex-notification.apex-default-notification` |
72
+ | `--notification-spacing-margin-y-container` | `bottom`、`top` | `var(--apex-spacing-16)` | `.apex-notification.apex-default-notification` |
73
+ | `--notification-spacing-padding-x-container` | `padding` | `var(--apex-spacing-32)` | `.apex-notification.apex-default-notification` |
74
+ | `--notification-spacing-padding-x-left-content` | `padding-inline-start` | `var(--apex-spacing-28)` | `.apex-notification.apex-default-notification` |
75
+ | `--notification-spacing-padding-y-container` | `padding` | `var(--apex-spacing-24)` | `.apex-notification.apex-default-notification` |
76
+ | `--notification-stroke-default` | `border` | `var(--apex-fill-neutral-quinary)` | `.apex-notification.apex-default-notification` |
77
+ | `--notification-stroke-stroke` | `border` | `var(--apex-border-08)` | `.apex-notification.apex-default-notification` |
78
+ | `--notification-text-body` | `color` | `var(--apex-text-neutral-secondary)` | `.apex-notification.apex-default-notification` |
79
+ | `--notification-text-title` | `color` | `var(--apex-text-neutral-primary)` | `.apex-notification.apex-default-notification` |
@@ -0,0 +1,217 @@
1
+ # Pagination
2
+
3
+ > Pagination:数据量较大、需要分批次浏览列表或表格时。
4
+
5
+ 包:`@apexhub/apex-ui-react`;版本:`1.2.2`(当前源码快照,发布状态以安装包版本为准)。
6
+
7
+ 公开导出:`Pagination`。
8
+
9
+ 以下 API 属于 Apex UI;不要据 antd 的同名组件推断额外属性或默认值。默认值列的空缺表示未声明,不代表 `false`。
10
+
11
+ ## 快速开始
12
+
13
+ ```tsx
14
+ import { Pagination } from '@apexhub/apex-ui-react'
15
+
16
+ import '@apexhub/apex-ui-react/style.css'
17
+
18
+ export default () => <Pagination total={85} defaultCurrent={1} />
19
+ ```
20
+
21
+ ## 何时使用
22
+
23
+ - 数据量较大、需要分批次浏览列表或表格时。
24
+ - 需要让用户切换每页条数时;Vue 版也支持快速跳转到指定页。
25
+ - 纯滚动加载场景不必使用 Pagination;仅一页时可配合 `hideOnSinglePage` 隐藏分页器。
26
+
27
+ ## API
28
+
29
+ 仅使用类型定义支持的属性;原生属性、ref 目标和事件签名因组件而异。关联类型用于解释字段结构;只有「导出类型」中的名称可从包根导入。
30
+
31
+ ### Pagination
32
+
33
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
34
+ | --- | --- | --- | --- | --- |
35
+ | current | 受控当前页(从 1 开始) | `number` | 否 | — |
36
+ | defaultCurrent | 非受控初始页 | `number` | 否 | `1` |
37
+ | total | 总条数 | `number` | 否 | `0` |
38
+ | pageSize | 受控每页条数 | `PageSize` | 否 | — |
39
+ | defaultPageSize | 非受控初始 pageSize | `PageSize` | 否 | `10` |
40
+ | onChange | 页码或 pageSize 变更回调 | `(page: number, pageSize: PageSize) => void` | 否 | — |
41
+ | onShowSizeChange | pageSize 变更专用回调。<br>在切换每页条数时触发,参数为变更后的当前页与新的 pageSize。 | `(current: number, size: PageSize) => void` | 否 | — |
42
+ | pageSizeOptions | pageSize 切换器的可选档位。 | `number[]` | 否 | `[10, 20, 50, 100]` |
43
+ | disabled | 整体禁用 | `boolean` | 否 | `false` |
44
+ | showSizeChanger | 显示 pageSize 切换器。<br>未传 → total > 50 时自动 true;显式 false → 永远关;显式 true → 永远开 | `boolean` | 否 | — |
45
+ | showQuickJumper | 兼容旧调用方;当前 React 设计不渲染快速跳转输入 | `boolean` | 否 | — |
46
+ | showTotal | 兼容旧调用方;当前 React 设计不渲染总数区域 | `ShowTotalFn` | 否 | — |
47
+ | hideOnSinglePage | 总页数 ≤ 1 时不渲染整个组件 | `boolean` | 否 | `false` |
48
+ | itemRender | 自定义每项渲染。<br>所有可点项(prev/next/jump-prev/jump-next/page)都调用此函数。<br>业务方应用 React.cloneElement(originalElement, ...) 保留 a11y props。 | `ItemRender` | 否 | — |
49
+ | responsive | 开启容器宽度自适应(ResizeObserver 四档)。 | `boolean` | 否 | `false` |
50
+ | className | — | `string` | 否 | — |
51
+ | style | — | `React.CSSProperties` | 否 | — |
52
+ | ref | ref 指向根 <nav> 元素 | `React.Ref<HTMLElement>` | 否 | — |
53
+
54
+ ### PageSize
55
+
56
+ 每页条数。开放为任意正整数,配合 `pageSizeOptions` 自定义可选档位。
57
+
58
+ ```typescript
59
+ type PageSize = number
60
+ ```
61
+
62
+ ### ShowTotalFn
63
+
64
+ showTotal prop 的函数签名
65
+
66
+ ```typescript
67
+ type ShowTotalFn = (total: number, range: [number, number]) => ReactNode
68
+ ```
69
+
70
+ ### ItemRender
71
+
72
+ itemRender prop 的函数签名
73
+
74
+ ```typescript
75
+ type ItemRender = (page: number, type: PageItemType, originalElement: ReactNode) => ReactNode
76
+ ```
77
+
78
+ ### PageItemType
79
+
80
+ ```typescript
81
+ type PageItemType = 'page' | 'prev' | 'next' | 'jump-prev' | 'jump-next'
82
+ ```
83
+
84
+ ### 导出类型
85
+
86
+ 另可从 `@apexhub/apex-ui-react` 导入:`ItemRender`、`PageItem`、`PageSize`、`PaginationProps`、`ShowTotalFn`(与上文子类型配合使用)。
87
+
88
+ ## 代码演示
89
+
90
+ ### 每页条数切换
91
+
92
+ 数据量较大时(默认 `total > 50`)会自动显示条数切换器,也可通过 `showSizeChanger` 强制开启或关闭。
93
+
94
+ ```tsx
95
+ import { Pagination } from '@apexhub/apex-ui-react'
96
+
97
+ export default () => (
98
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
99
+ <Pagination total={100} />
100
+ <Pagination total={200} showSizeChanger />
101
+ <Pagination total={10} showSizeChanger />
102
+ <Pagination total={200} showSizeChanger={false} />
103
+ </div>
104
+ )
105
+ ```
106
+
107
+ ### 受控用法
108
+
109
+ 通过 `current` 与 `pageSize` 受控管理当前页和每页条数。
110
+
111
+ ```tsx
112
+ import type { PageSize } from '@apexhub/apex-ui-react'
113
+
114
+ import { Pagination } from '@apexhub/apex-ui-react'
115
+
116
+ import { useState } from 'react'
117
+
118
+ export default () => {
119
+ const [current, setCurrent] = useState(2)
120
+ const [pageSize, setPageSize] = useState<PageSize>(10)
121
+
122
+ return (
123
+ <Pagination
124
+ total={500}
125
+ current={current}
126
+ pageSize={pageSize}
127
+ showSizeChanger
128
+ onChange={(page, size) => {
129
+ setCurrent(page)
130
+ setPageSize(size)
131
+ }}
132
+ />
133
+ )
134
+ }
135
+ ```
136
+
137
+ ### 受控用法 (quick-jumper)
138
+
139
+ **快速跳转**
140
+
141
+ `showQuickJumper` 展示跳转输入框,输入页码后按 Enter 跳转。
142
+
143
+ ```tsx
144
+ import { Pagination } from '@apexhub/apex-ui-react'
145
+
146
+ import { useState } from 'react'
147
+
148
+ export default () => {
149
+ const [current, setCurrent] = useState(1)
150
+
151
+ return (
152
+ <Pagination
153
+ total={500}
154
+ current={current}
155
+ showQuickJumper
156
+ onChange={(page) => setCurrent(page)}
157
+ />
158
+ )
159
+ }
160
+ ```
161
+
162
+ ### 受控用法 (show-total)
163
+
164
+ **显示总数**
165
+
166
+ `showTotal` 自定义总数展示文案,接收 `(total, range) => 自定义节点`。
167
+
168
+ ```tsx
169
+ import { Pagination } from '@apexhub/apex-ui-react'
170
+
171
+ export default () => (
172
+ <Pagination
173
+ total={128}
174
+ showTotal={(total, range) => `共 ${total} 条,当前 ${range[0]}-${range[1]}`}
175
+ />
176
+ )
177
+ ```
178
+
179
+ ### 禁用
180
+
181
+ `disabled` 禁用整个分页器,所有交互不可点击。
182
+
183
+ ```tsx
184
+ import { Pagination } from '@apexhub/apex-ui-react'
185
+
186
+ export default () => <Pagination total={50} disabled />
187
+ ```
188
+
189
+ ## DOM 结构
190
+
191
+ 源码声明的静态 `data-slot`:`pagination-button`、`pagination-size-changer`、`pagination`、`pagination-list`、`pagination-item-prev`、`pagination-item`、`pagination-item-jump-prev`、`pagination-item-jump-next`、`pagination-item-next`、`pagination-jumper`、`pagination-total`。具体节点随模式和状态出现,不表示固定嵌套顺序。
192
+
193
+ ## 样式定制
194
+
195
+ 优先使用本组件公开的尺寸、类型和状态属性。换肤与变量覆盖方式见 [主题指南](../../llms-theme.txt)。
196
+
197
+ 需要定制具体样式时再读取 [Token 明细](./tokens.txt),其中包含用途、定义值及适用作用域。常规组件使用无需加载该文件。
198
+
199
+ ## FAQ
200
+
201
+ ### `showSizeChanger` 不传时什么时候会出现?
202
+
203
+ 未传时当 `total > 50` 自动显示条数切换器;显式传 `true` 永远显示,传 `false` 永远隐藏。
204
+
205
+
206
+ ### `itemRender` 自定义时需要注意什么?
207
+
208
+ 建议用 `React.cloneElement(originalElement, ...)` 包裹默认元素,保留 `aria-current` 等无障碍属性,而非完全重写节点。
209
+
210
+
211
+ ### `responsive` 如何工作?
212
+
213
+ 开启后组件通过 ResizeObserver 监听容器宽度,按阈值自动调整布局;Vue 版会逐步隐藏总数与条数切换器,React 版只调整当前实际渲染的控件。默认 `false`,须显式传入 `responsive`。
214
+
215
+ ### `pageSizeOptions` 可以自定义吗?
216
+
217
+ 可以。通过 `pageSizeOptions` 传入 `number[]` 自定义条数切换器档位,默认 `[10, 20, 50, 100]`。`pageSize` / `defaultPageSize` 为任意正整数,可与自定义档位配合使用。