ant-design-vue/components/form/index.en-US.md

198 lines
12 KiB
Markdown
Raw Normal View History

2018-05-05 17:00:51 +08:00
## API
### Form
| Property | Description | Type | Default Value |
| -------- | ----------- | ---- | ------------- |
| form | Decorated by `Form.create()` will be automatically set `this.form` property, so just pass to form. If you use the template syntax, you can use `this.$form.createForm(this, options)` | object | n/a |
2018-05-05 17:00:51 +08:00
| hideRequiredMark | Hide required mark of all form items | Boolean | false |
2018-12-08 19:24:30 +08:00
| layout | Define form layout | 'horizontal'\|'vertical'\|'inline' | 'horizontal' |
| autoFormCreate(deprecated) | Automate Form.create, Recommended for use under the `template` component, and cannot be used with `Form.create()`. You should use `$form.createForm` to instead it after 1.1.9. |Function(form)| |
| options(deprecated) | The `options` corresponding to `Form.create(options)`. You should use `$form.createForm` to instead it after 1.1.9. | Object | {} |
2018-05-08 11:20:07 +08:00
### Events
| Events Name | Description | Arguments |
| --- | --- | --- |
| submit | Defines a function will be called if form data validation is successful. | Function(e:Event) |
2018-05-05 17:00:51 +08:00
### Form.create(options) \| this.$form.createForm(this, options)
2018-05-05 17:00:51 +08:00
How to use
#### Used in jsx, the usage is consistent with the React version of antd
2018-05-05 17:00:51 +08:00
```jsx
2018-05-08 11:20:07 +08:00
const CustomizedForm = {}
2018-05-05 17:00:51 +08:00
CustomizedForm = Form.create({})(CustomizedForm);
```
Maintain an ref for wrapped component instance, use `wrappedComponentRef`.
#### Single file template usage
````html
<template>
<a-form :form="form" />
</template>
<script>
export default {
beforeCreate () {
this.form = this.$form.createForm(this, options)
},
}
</script>
````
2018-05-05 17:00:51 +08:00
The following `options` are available:
| Property | Description | Type |
| -------- | ----------- | ---- |
| props | Only supports the use of Form.create({})(CustomizedForm). declare props on form(和[like vue props]( https://vuejs.org/v2/api/#props)) | {} |
| mapPropsToFields | Convert props to field value(e.g. reading the values from Redux store). And you must mark returned fields with [`Form.createFormField`](#Form.createFormField). If you use `$form.createForm` to create a collector, you can map any data to the Field without being bound by the parent component. | (props) => Object{ fieldName: FormField { value } } |
2018-05-05 17:00:51 +08:00
| validateMessages | Default validate message. And its format is similar with [newMessages](https://github.com/yiminghe/async-validator/blob/master/src/messages.js)'s returned value | Object { [nested.path]&#x3A; String } |
| onFieldsChange | Specify a function that will be called when the value a `Form.Item` gets changed. Usage example: saving the field's value to Redux store. | Function(props, fields) |
| onValuesChange | A handler while value of any field is changed | (props, values) => void |
2018-05-08 11:20:07 +08:00
If the form has been decorated by `Form.create` then it has `this.form` property. `this.form` provides some APIs as follows:
2018-05-05 17:00:51 +08:00
> Note: Before using `getFieldsValue` `getFieldValue` `setFieldsValue` and so on, please make sure that corresponding field had been registered with `getFieldDecorator`.
| Method | Description | Type |
| ------ | ----------- | ---- |
| getFieldDecorator | Two-way binding for form, single file template can be bound using the directive `v-decorator`. please read below for details. | |
2018-05-05 17:00:51 +08:00
| getFieldError | Get the error of a field. | Function(name) |
| getFieldsError | Get the specified fields' error. If you don't specify a parameter, you will get all fields' error. | Function(\[names: string\[]]) |
| getFieldsValue | Get the specified fields' values. If you don't specify a parameter, you will get all fields' values. | Function(\[fieldNames: string\[]]) |
| getFieldValue | Get the value of a field. | Function(fieldName: string) |
| isFieldsTouched | Check whether any of fields is touched by `getFieldDecorator`'s `options.trigger` event | (names?: string\[]) => boolean |
| isFieldTouched | Check whether a field is touched by `getFieldDecorator`'s `options.trigger` event | (name: string) => boolean |
| isFieldValidating | Check if the specified field is being validated. | Function(name) |
| resetFields | Reset the specified fields' value(to `initialValue`) and status. If you don't specify a parameter, all the fields will be reset. | Function(\[names: string\[]]) |
2019-01-03 20:48:09 +08:00
| setFields | Set value and error state of fields. | ({<br />&nbsp;&nbsp;\[fieldName\]: {value: any, errors: \[Error\] }<br />}) => void |
2018-05-08 11:20:07 +08:00
| setFieldsValue | Set the value of a field. | Function({ [fieldName]&#x3A; value } |
2018-12-13 21:26:21 +08:00
| validateFields | Validate the specified fields and get theirs values and errors. If you don't specify the parameter of fieldNames, you will validate all fields. | (<br />&nbsp;&nbsp;\[fieldNames: string\[]],<br />&nbsp;&nbsp;\[options: object\],<br />&nbsp;&nbsp;callback(errors, values)<br />) => void |
2018-05-05 17:00:51 +08:00
| validateFieldsAndScroll | This function is similar to `validateFields`, but after validation, if the target field is not in visible area of form, form will be automatically scrolled to the target field area. | same as `validateFields` |
2018-12-08 19:24:30 +08:00
### validateFields/validateFieldsAndScroll
```jsx
const { form: { validateFields } } = this;
validateFields((errors, values) => {
// ...
});
validateFields(['field1', 'field2'], (errors, values) => {
// ...
});
validateFields(['field1', 'field2'], options, (errors, values) => {
// ...
});
```
2018-05-05 17:00:51 +08:00
| Method | Description | Type | Default |
| ------ | ----------- | ---- | ------- |
| options.first | If `true`, every field will stop validation at first failed rule | boolean | false |
| options.firstFields | Those fields will stop validation at first failed rule | String\[] | \[] |
| options.force | Should validate validated field again when `validateTrigger` is been triggered again | boolean | false |
| options.scroll | Config scroll behavior of `validateFieldsAndScroll`, more: [dom-scroll-into-view's config](https://github.com/yiminghe/dom-scroll-into-view#function-parameter) | Object | {} |
update to antd3.8.3 (#159) * refactor: align * feat: update align to 2.4.3 * feat: update trigger 2.5.4 * feat: update tooltip 3.7.2 * fix: align * feat: update vc-calendar to 9.6.2 * feat: update vc-checkbox to 2.1.5 * feat: update vc-dialog to 7.1.8 * feat: update vc-from to 2.2.1 * feat: update vc-notification to 3.1.1 * test: update snapshots * feat: update vc-tree to 1.12.6 * feat: update vc-table to 6.2.8 * feat: update vc-upload to 2.5.1 * feat: update vc-input-number to 4.0.12 * feat: update vc-tabs to 9.2.6 * refactor: vc-menu * refactor: update vc-menu to 7.0.5 * style: remove unused * feat: update pagination to 1.16.5 * feat: add vc-progress 2.2.5 tag * feat: add vc-rate 2.4.0 tag * feat: update vc-slider to 8.6.1 * fix: tooltip error * style: delete conosle * feat: update vc-steps to 3.1.1 * add vc-switch tag 1.6.0 * feat: update upload to 2.5.1 * fix: update vc-menu * fix: update store * fix: add ref dir * fix: trigger mock shouldComponentUpdate * fix: update vc-select * revert: trigger lazyrenderbox * fix: update vc-select * fix: update vc-select * fix: update vc-select * fix: update vc-menu * fix: update vc-slick ref * update style to 3.8.2 * test: update snapshots * update vc-select * update util & affix * feat: add drawer * fix: support title add slot mode * test: update affix test * update alert * update anchor * update snapshots * fix: doc and vc-drawer * update select & auto-complete * update back-top & grid * feractor: avatar * test: add drawer test * update badge * update button * update card * update divider * feat: update vc-tabs to 9.3.6 and tabs * add afterEnter callback * update form * fix: update drawer * test: update snapshots * update modal & notification * test: update snapshots * update message * update locale-provider * update dropdown * update layout popconfirm popover * update time-picker * update menu * update date-picker * docs: update input docs * update input * update snapshots * update table * update test snapshots * feat: update progress * update checkbox * feat: update spin * update radio * docs: slider steps timeline * update list * update transfer * update collapse * update cascader * update upload
2018-09-05 21:28:54 +08:00
#### Callback arguments example of validateFields
- `errors`:
```js
{
"userName": {
"errors": [
{
"message": "Please input your username!",
"field": "userName"
}
]
},
"password": {
"errors": [
{
"message": "Please input your Password!",
"field": "password"
}
]
}
}
```
- `values`:
```js
{
"userName": "username",
"password": "password",
}
```
2018-05-05 17:00:51 +08:00
### Form.createFormField
To mark the returned fields data in `mapPropsToFields`, [demo](#components-form-demo-global-state).
### this.form.getFieldDecorator(id, options) and v-decorator="[id, options]"
2018-05-05 17:00:51 +08:00
After wrapped by `getFieldDecorator` or `v-decorator`, `value`(or other property defined by `valuePropName`) `onChange`(or other property defined by `trigger`) props will be added to form controlsthe flow of form data will be handled by Form which will cause:
2018-05-05 17:00:51 +08:00
1. You shouldn't use `onChange` to collect data, but you still can listen to `onChange`(and so on) events.
2018-12-08 19:24:30 +08:00
2. You cannot set value of form control via `value` `defaultValue` prop, and you should set default value with `initialValue` in `getFieldDecorator` instead.
2018-05-08 11:20:07 +08:00
3. You shouldn't call `v-model` manually, please use `this.form.setFieldsValue` to change value programmatically.
2018-05-05 17:00:51 +08:00
#### Special attention
1. `getFieldDecorator` and `v-decorator` can not be used to decorate stateless component.
2. you can't use `getFieldDecorator` and `v-decorator` in stateless component: <https://vuejs.org/v2/api/#functional>
2018-05-05 17:00:51 +08:00
#### getFieldDecorator(id, options) and v-decorator="[id, options]" parameters
2018-05-05 17:00:51 +08:00
| Property | Description | Type | Default Value |
| -------- | ----------- | ---- | ------------- |
| id | The unique identifier is required. support [nested fields format](https://github.com/react-component/form/pull/48). | string | |
| options.getValueFromEvent | Specify how to get value from event or other onChange arguments | function(..args) | [reference](https://github.com/react-component/form#option-object) |
2018-12-08 19:24:30 +08:00
| options.getValueProps | Get the component props according to field value. | function(value): any | [reference](https://github.com/react-component/form#option-object)
2018-12-13 21:26:21 +08:00
| options.initialValue | You can specify initial value, type, optional value of children node. (Note: Because `Form` will test equality with `===` internally, we recommend to use variable as `initialValue`, instead of literal) | | n/a |
2018-06-26 09:14:43 +08:00
| options.normalize | Normalize value to form component, [a select-all example](https://codesandbox.io/s/kw4l2vqqmv) | function(value, prevValue, allValues): any | - |
2019-01-19 17:53:55 +08:00
| options.preserve | Keep the field even if field removed | boolean | false |
2018-05-05 17:00:51 +08:00
| options.rules | Includes validation rules. Please refer to "Validation Rules" part for details. | object\[] | n/a |
2018-07-21 14:09:22 +08:00
| options.trigger | When to collect the value of children node | string | 'change' |
2018-05-05 17:00:51 +08:00
| options.validateFirst | Whether stop validate on first rule of error for this field. | boolean | false |
2018-07-21 14:09:22 +08:00
| options.validateTrigger | When to validate the value of children node. | string\|string\[] | 'change' |
2018-05-05 17:00:51 +08:00
| options.valuePropName | Props of children node, for example, the prop of Switch is 'checked'. | string | 'value' |
### Form.Item
2018-12-08 19:24:30 +08:00
Note: If Form.Item has multiple children that had been decorated by `getFieldDecorator` or `v-decorator`, `help` and `required` and `validateStatus` can't be generated automatically.
2018-05-05 17:00:51 +08:00
| Property | Description | Type | Default Value |
| -------- | ----------- | ---- | ------------- |
| colon | Used with `label`, whether to display `:` after label text. | boolean | true |
| extra | The extra prompt message. It is similar to help. Usage example: to display error message and prompt message at the same time. | string\|slot | |
2018-05-05 17:00:51 +08:00
| hasFeedback | Used with `validateStatus`, this option specifies the validation status icon. Recommended to be used only with `Input`. | boolean | false |
| help | The prompt message. If not provided, the prompt message will be generated by the validation rule. | string\|slot | |
| label | Label text | string\|slot | |
2019-02-16 16:51:21 +08:00
| labelCol | The layout of label. You can set `span` `offset` to something like `{span: 3, offset: 12}` or `sm: {span: 3, offset: 12}` same as with `<Col>` | [object](/components/grid/#Col) | |
2018-05-05 17:00:51 +08:00
| required | Whether provided or not, it will be generated by the validation rule. | boolean | false |
| validateStatus | The validation status. If not provided, it will be generated by validation rule. options: 'success' 'warning' 'error' 'validating' | string | |
2019-02-16 16:51:21 +08:00
| wrapperCol | The layout for input controls, same as `labelCol` | [object](/components/grid/#Col) | |
2018-05-05 17:00:51 +08:00
### Validation Rules
| Property | Description | Type | Default Value |
| -------- | ----------- | ---- | ------------- |
| enum | validate a value from a list of possible values | string | - |
| len | validate an exact length of a field | number | - |
| max | validate a max length of a field | number | - |
| message | validation error message | string | - |
| min | validate a min length of a field | number | - |
| pattern | validate from a regular expression | RegExp | - |
| required | indicates whether field is required | boolean | `false` |
| transform | transform a value before validation | function(value) => transformedValue:any | - |
| type | built-in validation type, [available options](https://github.com/yiminghe/async-validator#type) | string | 'string' |
| validator | custom validate function (Note: [callback must be called](https://github.com/ant-design/ant-design/issues/5155)) | function(rule, value, callback) | - |
| whitespace | treat required fields that only contain whitespace as errors | boolean | `false` |
See more advanced usage at [async-validator](https://github.com/yiminghe/async-validator).