@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,341 @@
1
+ # Form
2
+
3
+ > Form:需要收集、校验并提交一组结构化字段数据时。
4
+
5
+ 包:`@apexhub/apex-ui-react`;版本:`1.2.2`(当前源码快照,发布状态以安装包版本为准)。
6
+
7
+ 公开导出:`Form`、`FormItem`、`useForm`。
8
+
9
+ 以下 API 属于 Apex UI;不要据 antd 的同名组件推断额外属性或默认值。默认值列的空缺表示未声明,不代表 `false`。
10
+
11
+ ## 快速开始
12
+
13
+ ```tsx
14
+ import { Button, Form, Input } from '@apexhub/apex-ui-react'
15
+
16
+ import '@apexhub/apex-ui-react/style.css'
17
+
18
+ export default () => (
19
+ <Form
20
+ labelCol={{ span: 3 }}
21
+ wrapperCol={{ span: 18 }}
22
+ style={{ maxWidth: 600 }}
23
+ onFinish={(values) => {
24
+ console.log('提交:', values)
25
+ }}
26
+ >
27
+ <Form.Item name="username" label="用户名" rules={[{ required: true, message: '请输入用户名' }]}>
28
+ <Input placeholder="用户名" />
29
+ </Form.Item>
30
+ <Form.Item
31
+ name="password"
32
+ label="密码"
33
+ rules={[{ required: true, min: 6, message: '至少 6 位' }]}
34
+ >
35
+ <Input type="password" placeholder="密码" />
36
+ </Form.Item>
37
+ <Form.Item>
38
+ <Button type="primary" htmlType="submit">
39
+ 登录
40
+ </Button>
41
+ </Form.Item>
42
+ </Form>
43
+ )
44
+ ```
45
+
46
+ ## 何时使用
47
+
48
+ - 需要收集、校验并提交一组结构化字段数据时。
49
+ - 需要标签布局、必填标记、字段联动或统一校验规则时。
50
+ - 单个输入控件且无跨字段校验时,可直接使用 Input 等原子组件,不必包一层 Form。
51
+
52
+ ## API
53
+
54
+ 仅使用类型定义支持的属性;原生属性、ref 目标和事件签名因组件而异。关联类型用于解释字段结构;只有「导出类型」中的名称可从包根导入。
55
+
56
+ ### Form
57
+
58
+ 泛型参数:`<Values extends Record<string, unknown> = Record<string, unknown>>`。
59
+
60
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
61
+ | --- | --- | --- | --- | --- |
62
+ | form | — | `FormInstance<Values>` | 否 | — |
63
+ | name | — | `string` | 否 | — |
64
+ | layout | — | `"horizontal" \| "vertical" \| "inline"` | 否 | — |
65
+ | labelCol | 标签列布局;`flex` 可设置固定宽度,且优先于 `span`。 | `FormColProps` | 否 | — |
66
+ | wrapperCol | 控件列布局;`flex: 'auto'` 可填充剩余空间,且优先于 `span`。 | `FormColProps` | 否 | — |
67
+ | labelAlign | — | `"left" \| "right"` | 否 | — |
68
+ | colon | — | `boolean` | 否 | — |
69
+ | disabled | — | `boolean` | 否 | — |
70
+ | initialValues | — | `Partial<Values>` | 否 | — |
71
+ | requiredMark | — | `boolean \| 'optional' \| ((labelNode: React.ReactNode, info: { required: boolean }) => React.ReactNode)` | 否 | — |
72
+ | requiredMarkPlacement | 必填星号相对 label 文字或 label 列的位置。<br>labelStart / labelEnd 仅在 horizontal 布局下启用悬挂对齐。 | `"afterLabel" \| "beforeLabel" \| "labelEnd" \| "labelStart"` | 否 | `'afterLabel'` |
73
+ | validateMessages | — | `Partial<ValidateMessages>` | 否 | — |
74
+ | validateTrigger | — | `string \| string[]` | 否 | — |
75
+ | onFinish | — | `(values: Values) => void` | 否 | — |
76
+ | onFinishFailed | — | `(info: { values: Values; errorFields: FieldError[]; outOfDate: boolean }) => void` | 否 | — |
77
+ | onValuesChange | — | `(changed: Partial<Values>, all: Values) => void` | 否 | — |
78
+ | reserveMessageSpace | 是否为 explain(错误/help)区预留一行高度,防止错误出现时布局跳动。<br>可在 Form.Item 上单独覆盖。 | `boolean` | 否 | `true` |
79
+ | ref | — | `React.Ref<HTMLFormElement>` | 否 | — |
80
+
81
+ ### RequiredMarkPlacement
82
+
83
+ ```typescript
84
+ type RequiredMarkPlacement = 'afterLabel' | 'beforeLabel' | 'labelEnd' | 'labelStart'
85
+ ```
86
+
87
+ ### FormColProps
88
+
89
+ Form 标签列/控件列布局;`flex` 与 `span` 同时存在时优先使用 `flex`。
90
+
91
+ ```typescript
92
+ type FormColProps = Pick<ColProps, 'span' | 'offset' | 'flex'>
93
+ ```
94
+
95
+ ### FormItemProps
96
+
97
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
98
+ | --- | --- | --- | --- | --- |
99
+ | name | — | `string` | 否 | — |
100
+ | label | — | `React.ReactNode` | 否 | — |
101
+ | required | — | `boolean` | 否 | — |
102
+ | rules | — | `Rule[]` | 否 | — |
103
+ | help | — | `React.ReactNode` | 否 | — |
104
+ | extra | — | `React.ReactNode` | 否 | — |
105
+ | validateStatus | — | `"success" \| "warning" \| "error" \| "validating"` | 否 | — |
106
+ | valuePropName | — | `string` | 否 | — |
107
+ | trigger | — | `string` | 否 | — |
108
+ | validateTrigger | — | `string \| string[]` | 否 | — |
109
+ | dependencies | — | `NamePath[]` | 否 | — |
110
+ | shouldUpdate | — | `boolean \| ((prev: Record<string, unknown>, cur: Record<string, unknown>) => boolean)` | 否 | — |
111
+ | getValueFromEvent | — | `(...args: unknown[]) => unknown` | 否 | — |
112
+ | getValueProps | — | `(value: unknown) => Record<string, unknown>` | 否 | — |
113
+ | labelCol | 覆盖 Form 的标签列布局;`flex` 优先于 `span`。 | `FormColProps` | 否 | — |
114
+ | wrapperCol | 覆盖 Form 的控件列布局;`flex` 优先于 `span`。 | `FormColProps` | 否 | — |
115
+ | labelAlign | — | `"left" \| "right"` | 否 | — |
116
+ | requiredMarkPlacement | 覆盖 Form 的必填星号位置。 | `"afterLabel" \| "beforeLabel" \| "labelEnd" \| "labelStart"` | 否 | — |
117
+ | colon | — | `boolean` | 否 | — |
118
+ | noStyle | — | `boolean` | 否 | — |
119
+ | htmlFor | — | `string` | 否 | — |
120
+ | initialValue | — | `unknown` | 否 | — |
121
+ | hidden | — | `boolean` | 否 | — |
122
+ | className | — | `string` | 否 | — |
123
+ | style | — | `React.CSSProperties` | 否 | — |
124
+ | children | — | `React.ReactElement \| ((form: FormInstance) => React.ReactNode)` | 否 | — |
125
+ | asyncDebounceMs | async 校验器的防抖延迟(毫秒)。默认 150ms,设为 0 禁用防抖。<br>用于消除 validateTrigger='onChange' 时每次按键触发 async validator 导致的 validating 闪烁。 | `number` | 否 | `150` |
126
+ | reserveMessageSpace | 是否为 explain(错误/help)区预留一行高度,防止错误出现时布局跳动。<br>未设置时继承 Form 的 reserveMessageSpace。 | `boolean` | 否 | — |
127
+
128
+ ### FormInstance
129
+
130
+ 泛型参数:`<Values extends Record<string, unknown> = Record<string, unknown>>`。
131
+
132
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
133
+ | --- | --- | --- | --- | --- |
134
+ | getFieldValue | — | `(name: NamePath) => unknown` | 是 | — |
135
+ | getFieldsValue | 传 nameList 时只返回这些字段,否则返回全部 | `(nameList?: NamePath[]) => Values` | 是 | — |
136
+ | setFieldValue | — | `(name: NamePath, value: unknown) => void` | 是 | — |
137
+ | setFieldsValue | — | `(values: Partial<Values>) => void` | 是 | — |
138
+ | setFields | 批量设置字段的值/错误/touched/validating(注入服务端错误用 errors) | `(fields: FieldData[]) => void` | 是 | — |
139
+ | resetFields | — | `(names?: NamePath[]) => void` | 是 | — |
140
+ | validateFields | — | `(names?: NamePath[]) => Promise<Values>` | 是 | — |
141
+ | submit | — | `() => void` | 是 | — |
142
+ | getFieldError | — | `(name: NamePath) => string[]` | 是 | — |
143
+ | getFieldsError | — | `() => FieldError[]` | 是 | — |
144
+ | isFieldTouched | — | `(name: NamePath) => boolean` | 是 | — |
145
+ | isFieldsTouched | 任一字段被触碰过返回 true;传 nameList 则只看这些字段 | `(nameList?: NamePath[]) => boolean` | 是 | — |
146
+ | scrollToField | 将指定字段滚动到可视区域 | `(name: NamePath, options?: ScrollOptions) => void` | 是 | — |
147
+ | scrollToFirstError | 滚动到第一个有错误的字段(如提交失败后定位) | `(options?: ScrollOptions) => void` | 是 | — |
148
+
149
+ ### ValidateMessages
150
+
151
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
152
+ | --- | --- | --- | --- | --- |
153
+ | default | — | `string` | 否 | — |
154
+ | required | — | `string` | 否 | — |
155
+ | whitespace | — | `string` | 否 | — |
156
+ | optional | — | `string` | 否 | — |
157
+ | pattern | — | `{ mismatch?: string }` | 否 | — |
158
+ | string | — | `{ len?: string; min?: string; max?: string }` | 否 | — |
159
+ | number | — | `{ len?: string; min?: string; max?: string }` | 否 | — |
160
+ | array | — | `{ len?: string; min?: string; max?: string }` | 否 | — |
161
+ | types | — | `{ email?: string url?: string number?: string string?: string boolean?: string array?: string }` | 否 | — |
162
+
163
+ ### FieldError
164
+
165
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
166
+ | --- | --- | --- | --- | --- |
167
+ | name | — | `NamePath` | 是 | — |
168
+ | errors | — | `string[]` | 是 | — |
169
+
170
+ ### Rule
171
+
172
+ ```typescript
173
+ type Rule = RuleObject | RuleRender
174
+ ```
175
+
176
+ ### ValidateStatus
177
+
178
+ ```typescript
179
+ type ValidateStatus = 'success' | 'warning' | 'error' | 'validating'
180
+ ```
181
+
182
+ ### NamePath
183
+
184
+ ```typescript
185
+ type NamePath = string
186
+ ```
187
+
188
+ ### FieldData
189
+
190
+ setFields 的单字段数据,常用于注入服务端校验错误
191
+
192
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
193
+ | --- | --- | --- | --- | --- |
194
+ | name | — | `NamePath` | 是 | — |
195
+ | value | — | `unknown` | 否 | — |
196
+ | errors | — | `string[]` | 否 | — |
197
+ | touched | — | `boolean` | 否 | — |
198
+ | validating | — | `boolean` | 否 | — |
199
+
200
+ ### ScrollOptions
201
+
202
+ scrollToField / scrollToFirstError 的滚动选项(透传给 scrollIntoView)
203
+
204
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
205
+ | --- | --- | --- | --- | --- |
206
+ | behavior | — | `"auto" \| "instant" \| "smooth"` | 否 | — |
207
+ | block | — | `"center" \| "end" \| "nearest" \| "start"` | 否 | — |
208
+ | inline | — | `"center" \| "end" \| "nearest" \| "start"` | 否 | — |
209
+
210
+ ### RuleObject
211
+
212
+ | 属性 | 说明 | 类型 | 必填 | 默认值 |
213
+ | --- | --- | --- | --- | --- |
214
+ | required | — | `boolean` | 否 | — |
215
+ | message | — | `string` | 否 | — |
216
+ | type | — | `"string" \| "number" \| "boolean" \| "array" \| "email" \| "url"` | 否 | — |
217
+ | pattern | — | `RegExp` | 否 | — |
218
+ | min | — | `number` | 否 | — |
219
+ | max | — | `number` | 否 | — |
220
+ | len | — | `number` | 否 | — |
221
+ | whitespace | — | `boolean` | 否 | — |
222
+ | validator | — | `(rule: RuleObject, value: unknown) => Promise<void> \| void` | 否 | — |
223
+ | validateTrigger | — | `string \| string[]` | 否 | — |
224
+
225
+ ### RuleRender
226
+
227
+ ```typescript
228
+ type RuleRender = (api: { getFieldValue: (name: NamePath) => unknown }) => RuleObject
229
+ ```
230
+
231
+ 其他组件的类型不在此展开:`ColProps` 见 `../grid/llm.txt`。
232
+
233
+ ### 导出类型
234
+
235
+ 另可从 `@apexhub/apex-ui-react` 导入:`FieldError`、`FormColProps`、`FormInstance`、`FormItemProps`、`FormProps`、`NamePath`、`RequiredMarkPlacement`、`Rule`、`ValidateMessages`、`ValidateStatus`(与上文子类型配合使用)。
236
+
237
+ ## 代码演示
238
+
239
+ ### 布局
240
+
241
+ 通过 `layout` 切换水平、垂直与行内排布;可用 `labelCol` / `wrapperCol` 控制标签与控件栅格,也可通过 `flex` 设置固定宽度或自适应布局。
242
+
243
+ ```tsx
244
+ import { Form, Input } from '@apexhub/apex-ui-react'
245
+
246
+ export default () => (
247
+ <Form layout="vertical" style={{ maxWidth: 400 }}>
248
+ <Form.Item name="title" label="标题">
249
+ <Input placeholder="垂直布局" />
250
+ </Form.Item>
251
+ <Form.Item name="desc" label="描述">
252
+ <Input placeholder="标签在上、控件在下" />
253
+ </Form.Item>
254
+ </Form>
255
+ )
256
+ ```
257
+
258
+ ### 布局 (fixed-label-width)
259
+
260
+ 固定标签宽度时,将 `labelCol` 设为 `{ flex: '140px' }`,并让 `wrapperCol` 自动填充剩余空间。
261
+
262
+ ```tsx
263
+ import { Form, Input } from '@apexhub/apex-ui-react'
264
+
265
+ export default () => (
266
+ <Form labelAlign="left" labelCol={{ flex: '140px' }} wrapperCol={{ flex: 'auto' }}>
267
+ <Form.Item name="name" label="名称">
268
+ <Input placeholder="标签固定为 140px" />
269
+ </Form.Item>
270
+ <Form.Item name="description" label="较长的标签">
271
+ <Input placeholder="控件列自动填充" />
272
+ </Form.Item>
273
+ </Form>
274
+ )
275
+ ```
276
+
277
+ ### 校验规则
278
+
279
+ 在 `Form.Item` 的 `rules` 中声明同步或异步校验;失败时触发提交失败事件。
280
+
281
+ ```tsx
282
+ import { Button, Form, Input } from '@apexhub/apex-ui-react'
283
+
284
+ export default () => (
285
+ <Form style={{ maxWidth: 400 }}>
286
+ <Form.Item
287
+ name="email"
288
+ label="邮箱"
289
+ rules={[{ required: true }, { type: 'email', message: '邮箱格式不正确' }]}
290
+ >
291
+ <Input placeholder="name@example.com" />
292
+ </Form.Item>
293
+ <Form.Item>
294
+ <Button type="primary" htmlType="submit">
295
+ 校验
296
+ </Button>
297
+ </Form.Item>
298
+ </Form>
299
+ )
300
+ ```
301
+
302
+ ### 必填标记
303
+
304
+ `requiredMark` 控制必填星号展示;`requiredMarkPlacement` 可让星号紧跟文字,或贴齐横向 label 列的首尾边缘。
305
+
306
+ ```tsx
307
+ import { Form, Input } from '@apexhub/apex-ui-react'
308
+
309
+ export default () => (
310
+ <Form
311
+ labelCol={{ span: 5 }}
312
+ wrapperCol={{ span: 18 }}
313
+ labelAlign="left"
314
+ requiredMarkPlacement="labelEnd"
315
+ style={{ maxWidth: 600 }}
316
+ >
317
+ <Form.Item name="required" label="必填项" required>
318
+ <Input />
319
+ </Form.Item>
320
+ <Form.Item name="optional" label="选填项">
321
+ <Input />
322
+ </Form.Item>
323
+ </Form>
324
+ )
325
+ ```
326
+
327
+ ## DOM 结构
328
+
329
+ 源码声明的静态 `data-slot`:`form`、`form-item`、`form-item-label`、`form-item-control`、`form-item-field`、`form-item-caption`、`form-item-extra`。具体节点随模式和状态出现,不表示固定嵌套顺序。
330
+
331
+ ## 样式定制
332
+
333
+ 优先使用本组件公开的尺寸、类型和状态属性。换肤与变量覆盖方式见 [主题指南](../../llms-theme.txt)。
334
+
335
+ 需要定制具体样式时再读取 [Token 明细](./tokens.txt),其中包含用途、定义值及适用作用域。常规组件使用无需加载该文件。
336
+
337
+ ## FAQ
338
+
339
+ ### `Form.Item` 的 `name` 支持 `user.name` 这种路径吗?
340
+
341
+ v1 不支持点号或方括号嵌套路径,`name` 须为单层字符串字段名。
@@ -0,0 +1,28 @@
1
+ # Form 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
+ | `--form-spacing-gap` | `margin-top` | `var(--apex-spacing-4)` | `.apex-form.apex-vertical-form` |
14
+ | `--form-spacing-gap-caption` | `gap` | `var(--apex-spacing-0)` | `.apex-form.apex-horizontal-form` |
15
+ | `--form-spacing-gap-caption` | `gap` | `var(--apex-spacing-0)` | `.apex-form.apex-vertical-form` |
16
+ | `--form-spacing-gap-title` | `column-gap`、`gap` | `var(--apex-spacing-8)` | `.apex-form.apex-horizontal-form` |
17
+ | `--form-spacing-gap-title` | `column-gap`、`gap` | `var(--apex-spacing-4)` | `.apex-form.apex-vertical-form` |
18
+ | `--form-spacing-gap-y` | `margin-top` | `var(--apex-spacing-4)` | `.apex-form.apex-horizontal-form` |
19
+ | `--form-text-caption-default` | `color` | `var(--apex-text-neutral-secondary)` | `.apex-form.apex-default-form` |
20
+ | `--form-text-caption-disabled` | `color` | `var(--apex-text-neutral-disabled)` | `.apex-form.apex-default-form` |
21
+ | `--form-text-caption-error` | `color` | `var(--apex-text-error-primary)` | `.apex-form.apex-default-form` |
22
+ | `--form-text-caption-success` | `color` | `var(--apex-text-success-primary)` | `.apex-form.apex-default-form` |
23
+ | `--form-text-caption-warning` | `color` | `var(--apex-text-warning-primary)` | `.apex-form.apex-default-form` |
24
+ | `--form-text-title-default` | `color` | `var(--apex-text-neutral-alpha-primary)` | `.apex-form.apex-default-form` |
25
+ | `--formgroup-spacing-gap-horizontal` | `gap` | `var(--apex-spacing-16)` | `.apex-formgroup.apex-horizontal-formgroup` |
26
+ | `--formgroup-spacing-gap-horizontal` | `gap` | `var(--apex-spacing-16)` | `.apex-formgroup.apex-vertical-formgroup` |
27
+ | `--formgroup-spacing-gap-vertical` | `gap` | `var(--apex-spacing-12)` | `.apex-formgroup.apex-horizontal-formgroup` |
28
+ | `--formgroup-spacing-gap-vertical` | `gap` | `var(--apex-spacing-12)` | `.apex-formgroup.apex-vertical-formgroup` |