chenzy-design

如何引入

import { Form, Form.Field, Form.List, Form.Input, Form.Select, Form.Checkbox, Form.Radio, Form.Switch, Form.Slider, Form.Rating, Form.DatePicker, Form.TagInput, Form.TreeSelect, Form.Cascader, Form.Upload, Form.Section, Form.Slot, Form.Label, Form.ErrorMessage } from '@chenzy-design/svelte';

基础校验

Form.Input 通过 rules 声明校验规则，onSubmit 返回 { valid, values }。

标签位置

支持 left / top / inset 三种标签位置，inset 在聚焦时上浮。

left（默认）

top

inset

表单控件

Form.Input / Select / DatePicker / Switch / Checkbox 等控件接管数据流，无须手动 value/onChange。

校验规则

required、内置 type、长度 min、自定义 validator（含异步）多种校验规则。

字段联动

dependencies 声明依赖字段，被依赖字段变化时自动重校验（如确认密码）。

动态字段

Form.List 动态增删行，每行子字段名由 name(item, sub) 拼接。

外部操作

getFormApi 拿到内部句柄，在表单外部命令式 setFieldsValue / validate / resetFields。

分组

Form.Section 把字段按语义分区，带分区标题。

API 参考

Form

Props

属性	说明	类型	默认值
`value`	受控整表单值；变更经 onChange 上报	`Record<string, unknown>`	undefined
`initValues`	非受控初始值	`Record<string, unknown>`	{}
`layout`	—	`'vertical'\|'horizontal'`	vertical
`labelPosition`	—	`'top'\|'left'\|'inset'`	top
`labelWidth`	—	`number \| string`	undefined
`labelAlign`	Label 文本对齐（spec §4）	`'left'\|'right'`	left
`size`	—	`'small'\|'default'\|'large'`	default
`disabled`	—	`boolean`	false
`requiredMark`	—	`boolean`	true
`colon`	—	`boolean`	false
`scrollToError`	提交校验失败时滚动并聚焦首个错误字段	`boolean`	false
`validateTrigger`	全局默认校验时机，字段可经 trigger 覆盖（spec §4）	`'change'\|'blur'\|'submit'\|'mount'\|string[]`	['blur','change']
`showValidateIcon`	错误/警告文案是否带状态图标（spec §4）	`boolean`	true
`stopValidateWithError`	字段命中首条错误即停止该字段后续 rule（spec §4）	`boolean`	false
`preventDefault`	是否拦截原生 submit 默认行为（spec §4）	`boolean`	true
`stopPropagation`	提交时是否阻止 submit 事件冒泡	`boolean`	false
`allowEmpty`	收集值时是否保留空值字段键（spec §4）	`boolean`	false
`getFormApi`	Form 挂载后一次性回传内部 FormApi 句柄，供父级外部命令式 setFieldsValue/validate/resetFields（Semi getFormApi）	`(formApi: FormApi) => void`	undefined
`onSubmit`	—	`(r: { valid; values; errors }) => void`	undefined
`onChange`	—	`(values: Record<string, unknown>) => void`	undefined
`onReset`	表单重置时回调（原生 reset 或 formApi.resetFields()）（Semi onReset）	`() => void`	undefined
`onErrorChange`	任意字段错误集合变化时回调，入参为最新 errors（Semi onErrorChange）	`(errors: FieldErrors) => void`	undefined
`children`	—	`Snippet`	undefined
`footer`	—	`Snippet<[{ submitting: boolean }]>`	undefined
`Field.field`	字段名（必填）	`string`	—
`Field.label`	—	`string`	undefined
`Field.rules`	—	`Rule[]`	[]
`Field.initValue`	字段级初始值，覆盖容器 initValues（spec §4.2）	`unknown`	undefined
`Field.required`	—	`boolean`	false
`Field.validateStatus`	外部强制校验态（受控展示，不经内部校验、不回写）（spec §4.2）	`'default'\|'warning'\|'error'`	undefined
`Field.extraText`	—	`string`	undefined
`Field.noStyle`	仅注册收集、不渲染布局 DOM（纯收集）（spec §4.2 §190）	`boolean`	false
`Field.span`	Form.Section 栅格内占列（grid-column: span N）（spec §4.2）	`number`	undefined
`Field.transform`	提交前值转换（纯函数，不回写 state）（spec §4.2）	`(v, values) => unknown`	undefined
`Field.dependencies`	依赖字段名；其值变化时本字段自动重校验	`string[]`	undefined
`Field.trigger`	字段级校验时机覆盖（spec §4）	`'change'\|'blur'\|'submit'\|'mount'\|string[]`	继承容器
`Field.valuePropName`	控件值属性名；如 Checkbox/Switch 用 'checked'，snippet 参数即多出同名别名映射字段值	`string`	'value'
`Field.children`	snippet 参数含通用 value 及按 valuePropName 命名的别名（默认 value）；id 用于 label for/id 关联，describedBy 用于控件 aria-describedby	`Snippet<[{ value; [valuePropName]; onChange; onBlur; status; id; describedBy; disabled }]>`	undefined
`Input.field`	字段名（必填）	`string`	—
`Input.label`	—	`string`	undefined
`Input.rules`	—	`Rule[]`	[]
`Input.initValue`	字段级初始值，覆盖容器 initValues（spec §4.2）	`unknown`	undefined
`Input.required`	—	`boolean`	false
`Input.validateStatus`	外部强制校验态（受控展示）（spec §4.2）	`'default'\|'warning'\|'error'`	undefined
`Input.extraText`	—	`string`	undefined
`Input.span`	Form.Section 栅格内占列（spec §4.2）	`number`	undefined
`Input.transform`	提交前值转换（纯函数）（spec §4.2）	`(v, values) => unknown`	undefined
`Input.placeholder`	—	`string`	undefined
`Input.type`	—	`'text'\|'password'`	text
`Input.clearable`	—	`boolean`	false
`Input.maxLength`	—	`number`	undefined
`Input.dependencies`	依赖字段名；其值变化时本字段自动重校验	`string[]`	undefined
`Input.trigger`	字段级校验时机覆盖（spec §4）	`'change'\|'blur'\|'submit'\|'mount'\|string[]`	继承容器

Form.Field

通用字段包裹器：注册字段、渲染 Label / 必填星标 / 错误提示，snippet 暴露 value/onChange/status/id 等，用于包装任意控件。

Form.List

动态字段数组：children snippet 暴露 items / add / remove / move / name(item, sub)，用于可增删的重复字段组。

Form.Input

绑定字段的单行输入框（Field + Input）。

Form.Select

绑定字段的下拉选择（Field + Select）。

Form.Checkbox

绑定字段的复选框（Field + Checkbox，valuePropName=checked）。

Form.Radio

绑定字段的单选框（Field + Radio）。

Form.Switch

绑定字段的开关（Field + Switch，valuePropName=checked）。

Form.Slider

绑定字段的滑块（Field + Slider）。

Form.Rating

绑定字段的评分（Field + Rating）。

Form.DatePicker

绑定字段的日期选择（Field + DatePicker）。

Form.TagInput

绑定字段的标签输入（Field + TagInput）。

Form.TreeSelect

绑定字段的树选择（Field + TreeSelect）。

Form.Cascader

绑定字段的级联选择（Field + Cascader）。

Form.Upload

绑定字段的上传（Field + Upload）。

Form.Section

字段分组容器，带分区标题（text）。

Form.Slot

在表单布局内自由插入非字段内容（保持栅格/间距一致）。

Form.Label

可独立组合的字段标签原子。

Form.ErrorMessage

可独立组合的字段错误信息原子。

Accessibility

设计变量

变量	默认值	用法
`--cd-color-form-alerticon-icon-default`	`var(--cd-color-warning)`	警告图标颜色
`--cd-color-form-label-disabled-text-default`	`var(--cd-color-disabled-text)`	禁用表单项标签文字颜色
`--cd-color-form-label-extra-text-default`	`var(--cd-color-tertiary)`	表单项标签图标颜色
`--cd-color-form-label-optional-text-default`	`var(--cd-color-tertiary)`	表单项标签可选标记颜色
`--cd-color-form-label-text-default`	`var(--cd-color-text-0)`	表单项标签文字颜色
`--cd-color-form-message-error-text-default`	`var(--cd-color-danger)`	错误提示颜色
`--cd-color-form-requiredmark-disabled-text-default`	`var(--cd-color-danger)`	禁用表单项必填标记颜色
`--cd-color-form-requiredmark-text-default`	`var(--cd-color-danger)`	必填标记颜色
`--cd-color-form-section-border-default`	`var(--cd-color-border)`	表单分组标题底部描边颜色
`--cd-color-form-section-text-default`	`var(--cd-color-text-0)`	表单分组标题文字颜色