diff --git a/packages/docs/icons/svgs/fill/pwd.svg b/packages/docs/icons/svgs/fill/pwd.svg new file mode 100644 index 0000000000000000000000000000000000000000..387f1a27609508906259639a62ad54319ad1f38a --- /dev/null +++ b/packages/docs/icons/svgs/fill/pwd.svg @@ -0,0 +1,5 @@ + + + \ No newline at end of file diff --git a/packages/opendesign/src/form/OForm.vue b/packages/opendesign/src/form/OForm.vue index 5c14e0e036d09998154abd692b9043ee27d27d14..df2d429c2516303089a131d2e051d38e2669d461 100644 --- a/packages/opendesign/src/form/OForm.vue +++ b/packages/opendesign/src/form/OForm.vue @@ -77,8 +77,11 @@ provide(formInjectKey, { }); defineExpose({ + /** expose: validate form */ validate: doValidate, + /** expose: reset form */ resetFields, + /** expose: clear validate state */ clearValidate, }); diff --git a/packages/opendesign/src/form/__docs__/__case__/FormCustom.vue b/packages/opendesign/src/form/__docs__/__case__/FormCustom.vue new file mode 100644 index 0000000000000000000000000000000000000000..3f95bed45855eb571869d7f47b99d218e2f35225 --- /dev/null +++ b/packages/opendesign/src/form/__docs__/__case__/FormCustom.vue @@ -0,0 +1,102 @@ + + + +### 插槽 + +- `label`: 自定义标签内容 +- `symbol`: 自定义必填符号 +- `message`: 自定义验证信息 +- `extra`: 自定义额外信息 + + + +### Slots + +- `label`: Customize the label content +- `symbol`: Customize the required symbol +- `message`: Customize the validation message +- `extra`: Customize the extra information + + + + + + diff --git a/packages/opendesign/src/form/__docs__/__case__/FormUsage.vue b/packages/opendesign/src/form/__docs__/__case__/FormUsage.vue new file mode 100644 index 0000000000000000000000000000000000000000..7fbed2dab2d36d213f4bf2c5faf3d1d204835391 --- /dev/null +++ b/packages/opendesign/src/form/__docs__/__case__/FormUsage.vue @@ -0,0 +1,111 @@ + + + +### 使用 + +目前`OForm` 支持的表单项有 `OInput`、`OInputNumber`、`OTextarea`、`OSelect`、`OCheckboxGroup`、`ORadioGroup`、`OUpload` + +`layout` + +- `h`: 水平布局(标签与控件在同一行) +- `v`: 垂直布局 +- `inline`: 行内布局 + +`labelAlign`: 标签与控件之前垂直对其方式 + +- `top`: 标签顶部对其 +- `center`: 标签居中对其 +- `bottom`: 标签底部对其 + +`labelJustify`: 标签水平对齐方式 + +- `left`: 标签左对齐 +- `center`: 标签居中对齐 +- `right`: 标签右对齐 + +`labelWidth`: 标签宽度 + +`labelAlign` `labelJustify` 和 `labelWidth` 可通过 `OForm` 统一设置,也可通过 `OFormItem` 单独设置。 + + + +### Usage + +Currently, the form items supported by `OForm` include `OInput`, `OInputNumber`, `OTextarea`, `OSelect`, `OCheckboxGroup`, `ORadioGroup`, and `OUpload`. + +`layout` + +- `h`: Horizontal layout (label and control on the same line) +- `v`: Vertical layout +- `inline`: Inline layout + +`labelAlign`: Vertical alignment between the label and the control + +- `top`: Label aligns to the top +- `center`: Label aligns to the center +- `bottom`: Label aligns to the bottom + +`labelJustify`: Horizontal alignment of the label + +- `left`: Label aligns to the left +- `center`: Label aligns to the center +- `right`: Label aligns to the right + +`labelWidth`: Label width + +`labelAlign`, `labelJustify`, and `labelWidth` can be uniformly set via `OForm` or individually set via `OFormItem`. + + diff --git a/packages/opendesign/src/form/__docs__/__case__/ValidateData.vue b/packages/opendesign/src/form/__docs__/__case__/ValidateData.vue new file mode 100644 index 0000000000000000000000000000000000000000..f1a079cd9a184acbfa95cd215aeabb1e11fc9b1e --- /dev/null +++ b/packages/opendesign/src/form/__docs__/__case__/ValidateData.vue @@ -0,0 +1,309 @@ + + + +### 表单校验 + +表单校验用于验证用户输入的数据是否符合要求。通过 OFormItem 组件的 rules 属性配置校验规则。 + +#### 使用方法 + +- 通过 `OFrom` 组件的 `model` 参数指定要校验的表单数据。 +- 通过 `OFromItem` 组件的 `field` 参数指定要校验的字段名,可以是带点的嵌套字段名(如:`a.b.c`),暂不支持数组索引。 +- 通过 `OFromItem` 组件的 `rules` 属性指定要校验的规则。 + +#### 校验规则类型 + +**必填校验 `RequiredRuleT`**:验证字段是否已经填写 + +> 注:当 `OFromItem` 组件的 `required` 属性为 true 时,`OFrom` 组件会自动添加必填校验规则。 + +```ts +type RequiredRuleT = { + required: boolean; + /** 错误提示 */ + message?: string; + /** 触发器:默认为 change 事件 */ + triggers?: TriggerT | TriggerT[]; +}; +type TriggerT = 'change' | 'input' | 'blur' | 'focus'; +``` + +**类型校验 `TypeRuleT`**:验证字段值是否为指定类型 + +```ts +type TypeRuleT = { + type: 'string' | 'number' | 'boolean' | 'array' | 'object'; + message?: string; + triggers?: TriggerT | TriggerT[]; +}; +``` + +**自定义校验 `ValidatorRuleT`**:通过函数进行复杂的自定义校验 + +```ts +type ValidatorRuleT = { + triggers?: TriggerT | TriggerT[]; + /** 自定义校验函数 */ + validator?: ValidatorT; +}; +type ValidatorT = (value: any) => ValidatorResultT | void; +/** 校验结果 */ +type ValidatorResultT = { + type: 'danger' | 'warning' | 'success'; + message?: string; +}; +``` + +**自定义校验返回结果** + +- danger: 校验失败,阻止表单提交,显示第一个错误提示 +- warning: 警告信息,显示所有的警告提示 +- success: 校验通过,不显示信息 +- 无返回值: 同 success + +当同一字段配置多个校验规则时: + +- danger 类型会阻断后续校验规则的执行 +- warning 和 success 类型不会阻断后续校验 +- 每次校验都会重置之前的校验结果 + 如果需要在多个事件中触发校验,请确保规则配置了所有相关触发事件 + + ```js + const badRules = [ + { triggers: 'change' }, + // ❌ 错误示例:第一个rule的change事件会重置第二个rule校验结果 + { triggers: 'input' }, + ]; + + const goodRules = [ + { triggers: 'change' }, + // ✅ 正确示例:确保所有相关事件都能触发校验 + { triggers: ['input', 'change'] }, + ]; + ``` + +#### 手动校验 + +可通过 `OForm` 组件实例的 `validate` 方法校验表单数据。注意: + +1. 若未传入 `trigger` 参数,则使用 `defaultTrigger` 属性定义的事件进行校验; +2. 若未定义 `defaultTrigger`,则使用 `change` 事件进行校验; +3. 若无 `change` 触发的校验规则,则使用 `rules` 中第一个校验规则的第一个触发事件进行校验。 + +#### 提交 + +当 `OForm` 子元素中具有 `type="submit"` 的 `