@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,373 @@
1
+ # AutoComplete
2
+
3
+ > AutoComplete:为自由文本输入提供历史记录、关键词或搜索建议。没有匹配建议时,输入内容仍会保留。
4
+
5
+ 包:`@apexhub/apex-ui-react`;版本:`1.2.0`(当前源码快照,发布状态以安装包版本为准)。
6
+
7
+ 公开导出:`AutoComplete`。
8
+
9
+ 以下 API 属于 Apex UI;不要据 antd 的同名组件推断额外属性或默认值。默认值列的空缺表示未声明,不代表 `false`。
10
+
11
+ ## 快速开始
12
+
13
+ ```tsx
14
+ import { AutoComplete } from '@apexhub/apex-ui-react'
15
+
16
+ import '@apexhub/apex-ui-react/style.css'
17
+
18
+ const options = [{ value: '北京' }, { value: '上海' }, { value: '杭州' }]
19
+
20
+ export default function Demo() {
21
+ return (
22
+ <AutoComplete
23
+ aria-label="城市建议"
24
+ options={options}
25
+ placeholder="输入城市,也可以填写其他城市"
26
+ allowClear
27
+ />
28
+ )
29
+ }
30
+ ```
31
+
32
+ ## 何时使用
33
+
34
+ - 为自由文本输入提供历史记录、关键词或搜索建议。没有匹配建议时,输入内容仍会保留。
35
+ - 必须从固定选项中选择值时使用 Select;仅录入文字且不需要建议时使用 Input。
36
+ - React 和 Vue 均提供 AutoComplete;以下可运行示例使用 React。
37
+
38
+ ## API
39
+
40
+ 仅使用类型定义支持的属性;原生属性、ref 目标和事件签名因组件而异。关联类型用于解释字段结构;只有「导出类型」中的名称可从包根导入。
41
+
42
+ ### AutoComplete
43
+
44
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
45
+ | --- | --- | --- | --- | --- |
46
+ | defaultValue | 非受控初始输入文字。 | `string` | 否 | `''` |
47
+ | options | 候选数据,最多一层分组。 | `AutoCompleteOptionItem[]` | 否 | `[]` |
48
+ | filterOption | 本地过滤;false 用于远程搜索。默认按 value 不区分大小写包含匹配。 | `boolean \| ((input: string, option: AutoCompleteOption) => boolean)` | 否 | `true` |
49
+ | open | 展开意图;无候选时面板仍隐藏。 | `boolean` | 否 | — |
50
+ | closeOnScroll | 外部滚动祖先滚动时关闭;内部列表滚动不关闭。触发器完全不可见时始终请求关闭。 | `boolean` | 否 | `false` |
51
+ | defaultOpen | 非受控初始展开意图。 | `boolean` | 否 | `false` |
52
+ | defaultActiveFirstOption | 展开或输入变化时激活首个可用候选。 | `boolean` | 否 | `true` |
53
+ | placement | 面板位置。 | `"bottomLeft" \| "bottomRight" \| "topLeft" \| "topRight"` | 否 | `'bottomLeft'` |
54
+ | popupMatchSelectWidth | true 跟随输入宽度,false 按内容宽度,number 指定像素;均受视口约束。 | `boolean \| number` | 否 | `true` |
55
+ | onChange | 用户操作导致文字变化;程序赋值不触发。 | `(value: string) => void` | 否 | — |
56
+ | onSearch | 输入及清除触发;组合输入结束后触发一次,选择不触发。 | `(value: string) => void` | 否 | — |
57
+ | onSelect | 选择候选,包括选择同值候选。 | `(value: string, option: AutoCompleteOption) => void` | 否 | — |
58
+ | onOpenChange | 用户请求改变展开意图。 | `(open: boolean) => void` | 否 | — |
59
+ | onPressEnter | 仅非组合输入且 Enter 未选择建议时触发;选择建议会阻止原生表单提交。 | `React.KeyboardEventHandler<HTMLInputElement>` | 否 | — |
60
+ | onFocus | 焦点进入整个控件时触发。 | `React.FocusEventHandler<HTMLElement>` | 否 | — |
61
+ | onBlur | 焦点离开整个控件时触发,内部清除按钮不触发。 | `React.FocusEventHandler<HTMLElement>` | 否 | — |
62
+ | allowClear | 自定义清除按钮;`true` 使用默认图标 | `boolean \| InputAllowClear` | 否 | `false` |
63
+ | disabled | 是否禁用 | `boolean` | 否 | `false` |
64
+ | readOnly | 只读:不可修改,无 hover 交互态,仅展示。与 `disabled` 正交。 | `boolean` | 否 | `false` |
65
+ | id | 表单控件 id,透传至原生 `<input>` 或 `<textarea>` | `string` | 否 | — |
66
+ | name | 表单字段名,透传至原生 `<input>` 或 `<textarea>` | `string` | 否 | — |
67
+ | maxLength | 允许输入的最大字符数(原生 `maxLength`) | `number` | 否 | — |
68
+ | prefix | 前缀内容(如图标) | `React.ReactNode` | 否 | — |
69
+ | status | 设置校验 / 状态样式 | `"error" \| "completed" \| "loading"` | 否 | — |
70
+ | size | 控件尺寸(单行与 textarea 共用):`small` 24px / `medium` 28px / `large` 32px | `"small" \| "medium" \| "large"` | 否 | `'medium'` |
71
+ | variant | 表面变体:`default` 用 `.apex-default-input`,`elevated` 用 `.apex-elevated-input` | `"default" \| "elevated"` | 否 | `'default'` |
72
+ | suffix | 后缀内容(如图标) | `React.ReactNode` | 否 | — |
73
+ | value | 受控模式下的输入内容 | `string` | 否 | — |
74
+ | onClear | 点击清除按钮时的回调 | `() => void` | 否 | — |
75
+ | ref | 转发至原生 `<input>` 的 ref | `React.Ref<HTMLInputElement>` | 否 | — |
76
+
77
+ ### AutoCompleteOption
78
+
79
+ 自动补全候选;value 在所有分组中唯一且稳定。
80
+
81
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
82
+ | --- | --- | --- | --- | --- |
83
+ | value | 选择后填入输入框的文字,同时用于默认过滤。 | `string` | 是 | — |
84
+ | label | 展示内容,默认使用 value;不应包含可交互控件。 | `React.ReactNode` | 否 | — |
85
+ | disabled | 禁止激活和选择。 | `boolean` | 否 | `false` |
86
+
87
+ ### AutoCompleteGroup
88
+
89
+ 一层候选分组。
90
+
91
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
92
+ | --- | --- | --- | --- | --- |
93
+ | label | 分组标题。 | `React.ReactNode` | 是 | — |
94
+ | options | 当前分组的候选。 | `AutoCompleteOption[]` | 是 | — |
95
+
96
+ ### AutoCompleteOptionItem
97
+
98
+ 普通候选或分组。
99
+
100
+ ```typescript
101
+ type AutoCompleteOptionItem = AutoCompleteOption | AutoCompleteGroup
102
+ ```
103
+
104
+ ### AutoCompletePlacement
105
+
106
+ 建议面板相对输入框的位置。
107
+
108
+ ```typescript
109
+ type AutoCompletePlacement = 'bottomLeft' | 'bottomRight' | 'topLeft' | 'topRight'
110
+ ```
111
+
112
+ 其他组件的类型不在此展开:`InputSingleLineProps` 见 `../input/llm.txt`。
113
+
114
+ ### 导出类型
115
+
116
+ 另可从 `@apexhub/apex-ui-react` 导入:`AutoCompleteGroup`、`AutoCompleteOption`、`AutoCompleteOptionItem`、`AutoCompletePlacement`、`AutoCompleteProps`(与上文子类型配合使用)。
117
+
118
+ ## 代码演示
119
+
120
+ ### 受控与选择事件
121
+
122
+ `value` 与输入变更事件 管理输入内容。选择事件 仅在选择建议时触发,程序赋值不触发输入或选择事件。
123
+
124
+ ```tsx
125
+ import { AutoComplete, Button } from '@apexhub/apex-ui-react'
126
+
127
+ import { useState } from 'react'
128
+
129
+ const options = [{ value: 'React' }, { value: 'Vue' }, { value: 'TypeScript' }]
130
+
131
+ export default function Demo() {
132
+ const [value, setValue] = useState('React')
133
+ const [selected, setSelected] = useState('尚未选择')
134
+ return (
135
+ <div>
136
+ <AutoComplete
137
+ aria-label="技术关键词"
138
+ options={options}
139
+ value={value}
140
+ onChange={setValue}
141
+ onSelect={setSelected}
142
+ allowClear
143
+ />
144
+ <p>
145
+ 当前文字:<output>{value || '空'}</output>;最近选择:{selected}
146
+ </p>
147
+ <Button onClick={() => setValue('自由输入的内容')}>设置自由文本</Button>
148
+ </div>
149
+ )
150
+ }
151
+ ```
152
+
153
+ ### 分组与自定义标签
154
+
155
+ `label` 用于展示,选择后填入 `value`。支持一层分组,禁用项不参与键盘选择。所有选项的 `value` 必须唯一且稳定,标签内请使用展示内容。
156
+
157
+ ```tsx
158
+ import { AutoComplete, type AutoCompleteOptionItem } from '@apexhub/apex-ui-react'
159
+
160
+ const options: AutoCompleteOptionItem[] = [
161
+ {
162
+ label: '常用邮箱域名',
163
+ options: [
164
+ {
165
+ value: '@example.com',
166
+ label: (
167
+ <span>
168
+ <strong>@example.com</strong> · 工作邮箱
169
+ </span>
170
+ ),
171
+ },
172
+ { value: '@mail.example.com', label: <span>@mail.example.com · 个人邮箱</span> },
173
+ ],
174
+ },
175
+ { label: '其他', options: [{ value: '@legacy.example.com', disabled: true }] },
176
+ ]
177
+
178
+ export default function Demo() {
179
+ return <AutoComplete aria-label="邮箱域名" options={options} placeholder="输入 @ 查找域名" />
180
+ }
181
+ ```
182
+
183
+ ### 自定义过滤、前后缀与浮层宽度
184
+
185
+ 按中文标签搜索时可以提供过滤函数。默认浮层跟随输入框宽度,也可指定宽度;可用空间不足时自动收窄。
186
+
187
+ ```tsx
188
+ import { AutoComplete } from '@apexhub/apex-ui-react'
189
+
190
+ const options = [
191
+ { value: 'Beijing', label: '北京 Beijing' },
192
+ { value: 'Hangzhou', label: '杭州 Hangzhou' },
193
+ ]
194
+
195
+ export default function Demo() {
196
+ return (
197
+ <AutoComplete
198
+ aria-label="中英文城市搜索"
199
+ options={options}
200
+ filterOption={(input, option) =>
201
+ String(option.label).toLowerCase().includes(input.toLowerCase())
202
+ }
203
+ prefix="城市"
204
+ suffix="↵"
205
+ popupMatchSelectWidth={280}
206
+ placeholder="试试输入 北京 或 bei"
207
+ />
208
+ )
209
+ }
210
+ ```
211
+
212
+ ### 远程搜索
213
+
214
+ 使用 搜索事件 发起查询,配合 `filterOption` 设为 `false` 显示服务端返回的候选。请求、防抖、错误提示和过期结果丢弃由使用方管理。示例使用模拟请求。
215
+
216
+ ```tsx
217
+ import { AutoComplete, type AutoCompleteOption } from '@apexhub/apex-ui-react'
218
+
219
+ import { useEffect, useState } from 'react'
220
+
221
+ function search(query: string): Promise<AutoCompleteOption[]> {
222
+ return new Promise((resolve) => {
223
+ setTimeout(
224
+ () =>
225
+ resolve(
226
+ ['React', 'Vue', 'TypeScript', 'JavaScript']
227
+ .filter((value) => value.toLowerCase().includes(query.toLowerCase()))
228
+ .map((value) => ({ value })),
229
+ ),
230
+ 350,
231
+ )
232
+ })
233
+ }
234
+
235
+ export default function Demo() {
236
+ const [query, setQuery] = useState('')
237
+ const [options, setOptions] = useState<AutoCompleteOption[]>([])
238
+ const [loading, setLoading] = useState(false)
239
+ const [error, setError] = useState('')
240
+
241
+ useEffect(() => {
242
+ let active = true
243
+ setOptions([])
244
+ setError('')
245
+ setLoading(Boolean(query))
246
+ if (!query) return
247
+ const timer = setTimeout(async () => {
248
+ try {
249
+ const result = await search(query)
250
+ if (active) setOptions(result)
251
+ } catch {
252
+ if (active) setError('搜索失败,请重新输入')
253
+ } finally {
254
+ if (active) setLoading(false)
255
+ }
256
+ }, 200)
257
+ return () => {
258
+ active = false
259
+ clearTimeout(timer)
260
+ }
261
+ }, [query])
262
+
263
+ return (
264
+ <div>
265
+ <AutoComplete
266
+ aria-label="远程技术搜索"
267
+ aria-describedby="auto-complete-remote-help"
268
+ options={options}
269
+ filterOption={false}
270
+ onSearch={setQuery}
271
+ status={loading ? 'loading' : error ? 'error' : undefined}
272
+ placeholder="输入 React、Vue 或 TypeScript"
273
+ allowClear
274
+ />
275
+ <p id="auto-complete-remote-help" role="status">
276
+ {loading
277
+ ? '搜索中…'
278
+ : error ||
279
+ (query && !options.length ? '暂无匹配建议,仍可保留输入文字' : '示例使用模拟请求')}
280
+ </p>
281
+ </div>
282
+ )
283
+ }
284
+ ```
285
+
286
+ ### 尺寸与状态
287
+
288
+ 尺寸、表面、加载和校验状态与 Input 一致。禁用或只读时不展开建议;只读内容仍可聚焦和复制。
289
+
290
+ ```tsx
291
+ import { AutoComplete } from '@apexhub/apex-ui-react'
292
+
293
+ const options = [{ value: 'React' }, { value: 'Vue' }]
294
+
295
+ export default function Demo() {
296
+ return (
297
+ <div>
298
+ <p>尺寸:small / medium / large</p>
299
+ <AutoComplete aria-label="小尺寸" size="small" options={options} placeholder="small" />
300
+ <AutoComplete aria-label="中尺寸" options={options} placeholder="medium" />
301
+ <AutoComplete aria-label="大尺寸" size="large" options={options} placeholder="large" />
302
+ <p>表面与状态</p>
303
+ <AutoComplete
304
+ aria-label="浮起表面"
305
+ variant="elevated"
306
+ options={options}
307
+ placeholder="elevated"
308
+ />
309
+ <AutoComplete
310
+ aria-label="错误状态"
311
+ status="error"
312
+ options={options}
313
+ placeholder="请补全内容"
314
+ />
315
+ <AutoComplete aria-label="加载状态" status="loading" defaultValue="搜索中" />
316
+ <AutoComplete aria-label="已完成" status="completed" defaultValue="React" options={options} />
317
+ <p>禁用与只读</p>
318
+ <AutoComplete aria-label="禁用" disabled defaultValue="React" options={options} />
319
+ <AutoComplete aria-label="只读" readOnly defaultValue="Vue" options={options} />
320
+ </div>
321
+ )
322
+ }
323
+ ```
324
+
325
+ ### 表单
326
+
327
+ 可直接放入 FormItem,自动绑定值、校验状态和标签。选择建议时 Enter 不会同时提交表单;没有激活候选时保留正常的 Enter 提交行为。
328
+
329
+ ```tsx
330
+ import { AutoComplete, Button, Form, FormItem, useForm } from '@apexhub/apex-ui-react'
331
+
332
+ import { useState } from 'react'
333
+
334
+ export default function Demo() {
335
+ const [form] = useForm<{ city: string }>()
336
+ const [result, setResult] = useState('')
337
+ return (
338
+ <Form form={form} name="auto-complete-demo" onFinish={(values) => setResult(values.city)}>
339
+ <FormItem name="city" label="城市" rules={[{ required: true, message: '请输入城市' }]}>
340
+ <AutoComplete
341
+ options={[{ value: '北京' }, { value: '杭州' }]}
342
+ placeholder="选择建议或自行输入"
343
+ allowClear
344
+ />
345
+ </FormItem>
346
+ <Button htmlType="submit">提交</Button>
347
+ <Button onClick={() => form.resetFields()}>重置</Button>
348
+ <p>
349
+ 已提交:<output>{result || '尚未提交'}</output>
350
+ </p>
351
+ </Form>
352
+ )
353
+ }
354
+ ```
355
+
356
+ ## DOM 结构
357
+
358
+ 源码声明的静态 `data-slot`:`auto-complete-option`、`auto-complete-option-label`、`auto-complete`、`auto-complete-popup`、`auto-complete-list`、`auto-complete-group`、`auto-complete-group-label`。具体节点随模式和状态出现,不表示固定嵌套顺序。
359
+
360
+ ## 行为要点
361
+
362
+ - 选择只填入 value,不强制要求自由输入的文字匹配候选。清除后值为 `''`,依次通知 change、search、clear 并恢复输入焦点。
363
+ - 中文组合输入期间更新 value,暂不 search 或选择;组合结束后只 search 一次。受控输入请在变更事件中更新 value。
364
+ - 空候选隐藏面板;仍处于展开意图时,远程结果返回可以显示。非受控面板被 Escape、Tab、失焦或选择关闭后,迟到结果不会重新打开。
365
+ - 上下键循环候选并跳过禁用项;Tab 不自动选择;左右键和 Home/End 保持文本编辑行为。
366
+ - value 未提供时使用非受控模式;撤去受控 value 时沿用最后一次受控文字。
367
+ - SSR 输出输入框,客户端挂载后再显示建议面板。浮层使用组件库统一挂载点。
368
+
369
+ ## 样式定制
370
+
371
+ 优先使用本组件公开的尺寸、类型和状态属性。换肤与变量覆盖方式见 [主题指南](../../llms-theme.txt)。
372
+
373
+ 需要定制具体样式时再读取 [Token 明细](./tokens.txt),其中包含用途、定义值及适用作用域。常规组件使用无需加载该文件。
@@ -0,0 +1,77 @@
1
+ # AutoComplete 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
+ | `--dropdown-fill-active` | `background-color` | `var(--apex-fill-neutral-quaternary)` | `.apex-dropdown.apex-default-dropdown` |
14
+ | `--dropdown-fill-container-default` | `background-color` | `var(--apex-fill-neutral-secondary)` | `.apex-dropdown.apex-default-dropdown` |
15
+ | `--dropdown-fill-default` | `background-color` | `var(--apex-fill-neutral-transparent)` | `.apex-dropdown.apex-default-dropdown` |
16
+ | `--dropdown-fill-disabled` | `background-color` | `var(--apex-fill-neutral-transparent)` | `.apex-dropdown.apex-default-dropdown` |
17
+ | `--dropdown-fill-hover` | `background-color` | `var(--apex-fill-neutral-tertiary)` | `.apex-dropdown.apex-default-dropdown` |
18
+ | `--dropdown-radius-container` | `border-radius` | `var(--apex-radius-8)` | `.apex-dropdown.apex-lg-dropdown` |
19
+ | `--dropdown-radius-container` | `border-radius` | `var(--apex-radius-8)` | `.apex-dropdown.apex-sm-dropdown` |
20
+ | `--dropdown-radius-item` | `border-radius` | `var(--apex-radius-8)` | `.apex-dropdown.apex-lg-dropdown` |
21
+ | `--dropdown-radius-item` | `border-radius` | `var(--apex-radius-8)` | `.apex-dropdown.apex-sm-dropdown` |
22
+ | `--dropdown-size-container-gap` | `gap` | `var(--apex-spacing-2)` | `.apex-dropdown.apex-lg-dropdown` |
23
+ | `--dropdown-size-container-gap` | `gap` | `var(--apex-spacing-2)` | `.apex-dropdown.apex-sm-dropdown` |
24
+ | `--dropdown-size-container-height-max` | `max-height` | `var(--apex-size-320)` | `.apex-dropdown.apex-lg-dropdown` |
25
+ | `--dropdown-size-container-height-max` | `max-height` | `var(--apex-size-320)` | `.apex-dropdown.apex-sm-dropdown` |
26
+ | `--dropdown-size-item-height-item` | `min-height` | `var(--apex-size-32)` | `.apex-dropdown.apex-lg-dropdown` |
27
+ | `--dropdown-size-item-height-item` | `min-height` | `var(--apex-size-24)` | `.apex-dropdown.apex-sm-dropdown` |
28
+ | `--dropdown-spacing-container-padding-x` | `padding` | `var(--apex-spacing-6)` | `.apex-dropdown.apex-lg-dropdown` |
29
+ | `--dropdown-spacing-container-padding-x` | `padding` | `var(--apex-spacing-6)` | `.apex-dropdown.apex-sm-dropdown` |
30
+ | `--dropdown-spacing-container-padding-y` | `padding` | `var(--apex-spacing-6)` | `.apex-dropdown.apex-lg-dropdown` |
31
+ | `--dropdown-spacing-container-padding-y` | `padding` | `var(--apex-spacing-6)` | `.apex-dropdown.apex-sm-dropdown` |
32
+ | `--dropdown-spacing-item-padding-x-item` | `padding-inline`、`padding-inline-start` | `var(--apex-spacing-12)` | `.apex-dropdown.apex-lg-dropdown` |
33
+ | `--dropdown-spacing-item-padding-x-item` | `padding-inline`、`padding-inline-start` | `var(--apex-spacing-12)` | `.apex-dropdown.apex-sm-dropdown` |
34
+ | `--dropdown-stroke` | `border` | `var(--apex-border-1)` | `.apex-dropdown.apex-lg-dropdown` |
35
+ | `--dropdown-stroke` | `border` | `var(--apex-border-1)` | `.apex-dropdown.apex-sm-dropdown` |
36
+ | `--dropdown-stroke-container-default` | `border` | `var(--apex-stroke-neutral-quinary)` | `.apex-dropdown.apex-default-dropdown` |
37
+ | `--dropdown-text-active` | `color` | `var(--apex-text-neutral-primary)` | `.apex-dropdown.apex-default-dropdown` |
38
+ | `--dropdown-text-default` | `color` | `var(--apex-text-neutral-primary)` | `.apex-dropdown.apex-default-dropdown` |
39
+ | `--dropdown-text-disabled` | `color` | `var(--apex-text-neutral-disabled)` | `.apex-dropdown.apex-default-dropdown` |
40
+ | `--dropdown-text-hover` | `color` | `var(--apex-text-neutral-primary)` | `.apex-dropdown.apex-default-dropdown` |
41
+ | `--dropdown-text-subtitle-default` | `color` | `var(--apex-text-neutral-alpha-primary)` | `.apex-dropdown.apex-default-dropdown` |
42
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-20)` | `.apex-font.apex-text-cn-body-font` |
43
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-18)` | `.apex-font.apex-text-cn-caption-font` |
44
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-36)` | `.apex-font.apex-text-cn-heading-1-font` |
45
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-28)` | `.apex-font.apex-text-cn-heading-2-font` |
46
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-24)` | `.apex-font.apex-text-cn-heading-3-font` |
47
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-24)` | `.apex-font.apex-text-cn-heading-4-font` |
48
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-20)` | `.apex-font.apex-text-en-body-font` |
49
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-18)` | `.apex-font.apex-text-en-caption-font` |
50
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-36)` | `.apex-font.apex-text-en-heading-1-font` |
51
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-28)` | `.apex-font.apex-text-en-heading-2-font` |
52
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-24)` | `.apex-font.apex-text-en-heading-3-font` |
53
+ | `--font-fontheight` | `line-height` | `var(--apex-fontheight-24)` | `.apex-font.apex-text-en-heading-4-font` |
54
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-14)` | `.apex-font.apex-text-cn-body-font` |
55
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-12)` | `.apex-font.apex-text-cn-caption-font` |
56
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-24)` | `.apex-font.apex-text-cn-heading-1-font` |
57
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-18)` | `.apex-font.apex-text-cn-heading-2-font` |
58
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-16)` | `.apex-font.apex-text-cn-heading-3-font` |
59
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-16)` | `.apex-font.apex-text-cn-heading-4-font` |
60
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-14)` | `.apex-font.apex-text-en-body-font` |
61
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-12)` | `.apex-font.apex-text-en-caption-font` |
62
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-24)` | `.apex-font.apex-text-en-heading-1-font` |
63
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-18)` | `.apex-font.apex-text-en-heading-2-font` |
64
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-16)` | `.apex-font.apex-text-en-heading-3-font` |
65
+ | `--font-fontsize` | `font-size` | `var(--apex-fontsize-16)` | `.apex-font.apex-text-en-heading-4-font` |
66
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-400)` | `.apex-font.apex-text-cn-body-font` |
67
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-400)` | `.apex-font.apex-text-cn-caption-font` |
68
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-600)` | `.apex-font.apex-text-cn-heading-1-font` |
69
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-600)` | `.apex-font.apex-text-cn-heading-2-font` |
70
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-600)` | `.apex-font.apex-text-cn-heading-3-font` |
71
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-400)` | `.apex-font.apex-text-cn-heading-4-font` |
72
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-400)` | `.apex-font.apex-text-en-body-font` |
73
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-400)` | `.apex-font.apex-text-en-caption-font` |
74
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-600)` | `.apex-font.apex-text-en-heading-1-font` |
75
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-600)` | `.apex-font.apex-text-en-heading-2-font` |
76
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-600)` | `.apex-font.apex-text-en-heading-3-font` |
77
+ | `--font-fontweight` | `font-weight` | `var(--apex-fontweight-400)` | `.apex-font.apex-text-en-heading-4-font` |
@@ -0,0 +1,199 @@
1
+ # Avatar
2
+
3
+ > Avatar:需要展示用户、团队或业务实体的缩略标识,且空间有限时。
4
+
5
+ 包:`@apexhub/apex-ui-react`;版本:`1.2.0`(当前源码快照,发布状态以安装包版本为准)。
6
+
7
+ 公开导出:`Avatar`、`AvatarGroup`。
8
+
9
+ 以下 API 属于 Apex UI;不要据 antd 的同名组件推断额外属性或默认值。默认值列的空缺表示未声明,不代表 `false`。
10
+
11
+ ## 快速开始
12
+
13
+ ```tsx
14
+ import { Avatar } from '@apexhub/apex-ui-react'
15
+
16
+ import '@apexhub/apex-ui-react/style.css'
17
+
18
+ export default () => (
19
+ <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
20
+ <Avatar>A</Avatar>
21
+ <Avatar>U</Avatar>
22
+ </div>
23
+ )
24
+ ```
25
+
26
+ ## 何时使用
27
+
28
+ - 需要展示用户、团队或业务实体的缩略标识,且空间有限时。
29
+ - 图片不可用时,可用字符或图标作为 fallback;图片加载失败会自动回退。
30
+ - 需要将多个头像堆叠展示,或限制可见数量并以 `+N` 表示溢出时,使用 `AvatarGroup`。
31
+
32
+ ## API
33
+
34
+ 仅使用类型定义支持的属性;原生属性、ref 目标和事件签名因组件而异。关联类型用于解释字段结构;只有「导出类型」中的名称可从包根导入。
35
+
36
+ ### Avatar
37
+
38
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
39
+ | --- | --- | --- | --- | --- |
40
+ | shape | 头像形状 | `"circle" \| "square"` | 否 | `'circle'` |
41
+ | size | 头像尺寸;支持枚举档位、像素数、响应式对象 | `AvatarSize` | 否 | `'medium'` |
42
+ | src | 图片类头像的资源地址 | `string` | 否 | — |
43
+ | alt | 图像无法显示时的替代文本(同时作为字符 fallback 的 `aria-label`) | `string` | 否 | — |
44
+ | children | 字符或图标头像内容;若存在 src 且图片加载失败时,作为 fallback 渲染 | `React.ReactNode` | 否 | — |
45
+ | gap | 字符类头像距离左右两侧边界(像素);用于自动缩放计算 | `number` | 否 | `4` |
46
+ | crossOrigin | CORS 属性设置(透传 `<img crossorigin>`) | `"" \| "anonymous" \| "use-credentials"` | 否 | — |
47
+ | onError | 图片加载失败的事件;返回 `false` 时关闭组件默认 fallback 行为 | `() => boolean` | 否 | — |
48
+ | clickable | 是否启用可点击交互态;为 `true` 时根节点带上 `role="button"`、`tabIndex=0`、<br>`cursor: pointer`,并消费 hover / click / focus-visible / disabled 状态色 token。<br>静态展示场景请保持 `false`(默认)以避免被错误地识别为按钮。 | `boolean` | 否 | `false` |
49
+ | disabled | 仅在 `clickable=true` 时生效;禁用后阻断 `onClick` 与键盘触发,并切换到 disabled 状态色。 | `boolean` | 否 | `false` |
50
+ | gray | 置灰展示。内部切换 `apex-inactive-avatar` token 作用域;<br>图片额外 grayscale。与 disabled(交互禁用)正交。 | `boolean` | 否 | `false` |
51
+ | ref | 根节点 ref(指向 `HTMLSpanElement`) | `React.Ref<HTMLSpanElement>` | 否 | — |
52
+ | onClick | 头像点击回调(配合 `clickable=true` 使用) | `React.MouseEventHandler<HTMLSpanElement>` | 否 | — |
53
+ | className | 根节点类名 | `string` | 否 | — |
54
+ | style | 根节点内联样式(禁止硬编码色值,优先 CSS Token) | `React.CSSProperties` | 否 | — |
55
+
56
+ ### AvatarSize
57
+
58
+ Avatar 尺寸
59
+
60
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
61
+ | --- | --- | --- | --- | --- |
62
+ | at | — | `(index: number) => string \| undefined` | 否 | — |
63
+ | xs | — | `number` | 否 | — |
64
+ | sm | — | `number` | 否 | — |
65
+ | md | — | `number` | 否 | — |
66
+ | lg | — | `number` | 否 | — |
67
+ | xl | — | `number` | 否 | — |
68
+ | xxl | — | `number` | 否 | — |
69
+
70
+ ### AvatarGroupProps
71
+
72
+ 继承:`React.HTMLAttributes<HTMLDivElement>`;本节列出新增或重声明字段。
73
+
74
+ AvatarGroup 组件 Props
75
+
76
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
77
+ | --- | --- | --- | --- | --- |
78
+ | max | 最多显示相关配置;`count` 触发 `+N` 溢出 Avatar | `{ count?: number style?: React.CSSProperties }` | 否 | — |
79
+ | size | 透传给所有子 Avatar;子 Avatar 自传 `size` 时不被覆盖 | `AvatarSize` | 否 | `'medium'` |
80
+ | shape | 透传给所有子 Avatar | `"circle" \| "square"` | 否 | `'circle'` |
81
+ | ref | 根节点 ref(指向 `HTMLDivElement`) | `React.Ref<HTMLDivElement>` | 否 | — |
82
+ | className | 根节点类名 | `string` | 否 | — |
83
+ | style | 根节点内联样式(禁止硬编码色值,优先 CSS Token) | `React.CSSProperties` | 否 | — |
84
+
85
+ ### 导出类型
86
+
87
+ 另可从 `@apexhub/apex-ui-react` 导入:`AvatarGroupProps`、`AvatarProps`(与上文子类型配合使用)。
88
+
89
+ ## 代码演示
90
+
91
+ ### 图片头像
92
+
93
+ 通过 `src` 加载图片;加载失败时回退到 子内容 或 `alt` 对应内容。
94
+
95
+ ```tsx
96
+ import { Avatar } from '@apexhub/apex-ui-react'
97
+
98
+ const src =
99
+ 'data:image/svg+xml;utf8,' +
100
+ encodeURIComponent(
101
+ '<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64"><rect width="64" height="64" fill="#7B61FF"/><text x="50%" y="50%" dominant-baseline="middle" fill="white" font-size="24" text-anchor="middle">UI</text></svg>',
102
+ )
103
+
104
+ export default () => <Avatar src={src} alt="用户头像" />
105
+ ```
106
+
107
+ ### 尺寸
108
+
109
+ 提供 `large`、`medium`(默认)、`small` 三档,也支持数字像素或响应式对象。
110
+
111
+ ```tsx
112
+ import { Avatar } from '@apexhub/apex-ui-react'
113
+
114
+ export default () => (
115
+ <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
116
+ <Avatar size="large">L</Avatar>
117
+ <Avatar size="medium">M</Avatar>
118
+ <Avatar size="small">S</Avatar>
119
+ </div>
120
+ )
121
+ ```
122
+
123
+ ### 形状
124
+
125
+ 通过 `shape` 切换圆形(默认)与方形。
126
+
127
+ ```tsx
128
+ import { Avatar } from '@apexhub/apex-ui-react'
129
+
130
+ export default () => (
131
+ <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
132
+ <Avatar shape="circle">圆</Avatar>
133
+ <Avatar shape="square">方</Avatar>
134
+ </div>
135
+ )
136
+ ```
137
+
138
+ ### 头像组
139
+
140
+ 用 `AvatarGroup` 堆叠多个头像;`max.count` 限制可见数量,超出部分以 `+N` 溢出头像展示。
141
+
142
+ ```tsx
143
+ import { Avatar, AvatarGroup } from '@apexhub/apex-ui-react'
144
+
145
+ export default () => (
146
+ <AvatarGroup max={{ count: 3 }}>
147
+ <Avatar>A</Avatar>
148
+ <Avatar>B</Avatar>
149
+ <Avatar>C</Avatar>
150
+ <Avatar>D</Avatar>
151
+ <Avatar>E</Avatar>
152
+ </AvatarGroup>
153
+ )
154
+ ```
155
+
156
+ ### 置灰展示
157
+
158
+ `gray` 用于离职、失效等场景的视觉降级;图片头像会额外应用灰度滤镜,与 `disabled`(交互禁用)正交。
159
+
160
+ ```tsx
161
+ import { Avatar } from '@apexhub/apex-ui-react'
162
+
163
+ const IMG_SRC = 'https://api.dicebear.com/7.x/avataaars/svg?seed=gray-demo'
164
+
165
+ export default () => (
166
+ <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
167
+ <Avatar>A</Avatar>
168
+ <Avatar gray>A</Avatar>
169
+ <Avatar src={IMG_SRC} alt="正常图片" />
170
+ <Avatar gray src={IMG_SRC} alt="置灰图片" />
171
+ </div>
172
+ )
173
+ ```
174
+
175
+ ## DOM 结构
176
+
177
+ 源码声明的静态 `data-slot`:`avatar`、`avatar-image`、`avatar-fallback`、`avatar-inner`、`avatar-group`。具体节点随模式和状态出现,不表示固定嵌套顺序。
178
+
179
+ ## 样式定制
180
+
181
+ 优先使用本组件公开的尺寸、类型和状态属性。换肤与变量覆盖方式见 [主题指南](../../llms-theme.txt)。
182
+
183
+ 需要定制具体样式时再读取 [Token 明细](./tokens.txt),其中包含用途、定义值及适用作用域。常规组件使用无需加载该文件。
184
+
185
+ ## FAQ
186
+
187
+ ### `AvatarGroup` 的 `+N` 能点击查看全部成员吗?
188
+
189
+ 当前版本仅展示数字溢出头像,不支持 Popover 展开完整列表;需自行在外层实现悬浮预览。
190
+
191
+
192
+ ### 为什么 `src` 只接受字符串?
193
+
194
+ 与底层图片组件一致;若需懒加载或自定义图片包装,请改用 `children` 自行渲染。
195
+
196
+
197
+ ### 头像默认可点击吗?
198
+
199
+ 否。`clickable` 默认为 `false`,避免列表中的展示头像被误识别为按钮;需要交互时再显式开启。