# form (w-form)

- **Import**: `WForm` from `win-design-next`
- **Tag**: `<w-form>`
- **说明**: Form 表单
- **分类**: data-entry
- **Skill 版本**: V1.1.0
- **适配组件库**: win-design-next 1.2.2
- **API 来源**: `docs/zh-CN/component/form.md`

## API

## Form API

### Attributes

| 属性名                    | 说明                                                                                                                                                 | 类型                                           | 默认值 |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ------ |
| model                     | 表单数据对象                                                                                                                                         | ^[object]`Record`                              | —      |
| rules                     | 表单验证规则                                                                                                                                         | ^[object]`FormRules`                           | —      |
| inline                    | 行内表单模式                                                                                                                                         | ^[boolean]                                     | false  |
| label-position            | 表单域标签的位置， 当设置为 `left` 或 `right` 时，则也需要设置 `label-width` 属性                                                                    | ^[enum]`'left' \| 'right' \| 'top'`            | right  |
| label-width               | 标签的长度，例如 `'50px'`。 作为 Form 直接子元素的 form-item 会继承该值。 可以使用 `auto`。                                                          | ^[string] / ^[number]                          | ''     |
| label-suffix              | 表单域标签的后缀                                                                                                                                     | ^[string]                                      | ''     |
| hide-required-asterisk    | 是否隐藏必填字段标签旁边的红色星号。                                                                                                                 | ^[boolean]                                     | false  |
| require-asterisk-position | 星号的位置。                                                                                                                                         | ^[enum]`'left' \| 'right'`                     | left   |
| show-message              | 是否显示校验错误信息                                                                                                                                 | ^[boolean]                                     | true   |
| inline-message            | 是否以行内形式展示校验信息                                                                                                                           | ^[boolean]                                     | false  |
| status-icon               | 是否在输入框中显示校验结果反馈图标                                                                                                                   | ^[boolean]                                     | false  |
| validate-on-rule-change   | 是否在 `rules` 属性改变后立即触发一次验证                                                                                                            | ^[boolean]                                     | true   |
| size                      | 用于控制该表单内组件的尺寸                                                                                                                           | ^[enum]`'' \| 'large' \| 'default' \| 'small'` | —      |
| disabled                  | 是否禁用该表单内的所有组件。 如果设置为 `true`, 它将覆盖内部组件的 `disabled` 属性                                                                   | ^[boolean]                                     | false  |
| scroll-to-error           | 当校验失败时，滚动到第一个错误表单项                                                                                                                 | ^[boolean]                                     | false  |
| scroll-into-view-options  | 当校验有失败结果时，滚动到第一个失败的表单项目 可通过 [scrollIntoView](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView) 配置 | ^[object]`Record` / ^[boolean]                 | —      |
| prevent-submit ^(1.1.14)  | 是否阻止表单提交                                                                                                                                     | ^[boolean]                                     | false  |

### Events

| 名称     | 说明                   | 类型                                                                         |
| -------- | ---------------------- | ---------------------------------------------------------------------------- |
| validate | 任一表单项被校验后触发 | ^[Function]`(prop: FormItemProp, isValid: boolean, message: string) => void` |

### Slots

| 事件名  | 说明           | 子标签   |
| ------- | -------------- | -------- |
| default | 自定义默认内容 | FormItem |

### Exposes

| 名称          | 说明                                                            | 类型                                                                                                                |
| ------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| validate      | 对整个表单的内容进行验证。 接收一个回调函数，或返回 `Promise`。 | ^[Function]`(callback?: FormValidateCallback) => Promise`                                                           |
| validateField | 验证具体的某个字段。                                            | ^[Function]`(props?: Arrayable \| undefined, callback?: FormValidateCallback \| undefined) => FormValidationResult` |
| resetFields   | 重置该表单项，将其值重置为初始值，并移除校验结果                | ^[Function]`(props?: Arrayable \| undefined) => void`                                                               |
| scrollToField | 滚动到指定的字段                                                | ^[Function]`(prop: FormItemProp) => void`                                                                           |
| clearValidate | 清理某个字段的表单验证信息。                                    | ^[Function]`(props?: Arrayable \| undefined) => void`                                                               |
| fields        | 获取所有字段的 context                                          | ^[array]`FormItemContext[]`                                                                                         |
