antd-mini
Version:
antd-mini 是支付宝小程序 UI 组件库，遵循 Ant Design 规范。
437 lines (315 loc) • 16.5 kB
Markdown
---
nav:
path: /components
group:
title: 数据录入
order: 12
toc: 'content'
---
Form 表单包含数据录入、校验以及相应的样式。Form 组件需要 [component2](https://opendocs.alipay.com/mini/framework/custom-component-overview) 支持。
- 用于创建实体或收集信息。
- 需要对输入的数据类型进行校验时。
> 以输入框为例
在 `index.json` 中引入组件
```json
"usingComponents": {
"form-input": "antd-mini/es/Form/FormInput/index"
"form-input": "antd-mini/Form/FormInput/index"
}
```
逻辑层将输入框组件 ref 注册到 Form 中
```xml
<form-input
label="用户名"
name="account"
placeholder="请输入用户名"
tooltip="用户名说明"
allowClear
ref="handleRef"
/>
```
```js
import { Form } from 'antd-mini/es/Form/form';
import { Form } from 'antd-mini/Form/form';
Page({
handleRef(ref) {
this.form.addItem(ref);
if (!this.formRefList) {
this.formRefList = [];
}
this.formRefList.push(ref.detail);
},
});
```
<code src='../../demo/pages/Form/FormBasic/index'></code>
<code src='../../demo/pages/Form/FormLayout/index'></code>
<code src='../../demo/pages/Form/FormInitialValues/index'></code>
<code src='../../demo/pages/Form/FormInitialValuesAsync/index'></code>
<code src='../../demo/pages/Form/FormWatch/index'></code>
<code src='../../demo/pages/Form/FormRules/index'></code>
<code src='../../demo/pages/Form/FormDynamic/index'></code>
<code src='../../demo/pages/Form/FormDependency/index'></code>
<code src='../../demo/pages/Form/FormValidate/index'></code>
<code src='../../demo/pages/Form/FormValidateMessages/index'></code>
<code src='../../demo/pages/Form/FormMultiple/index'></code>
<code src='../../demo/pages/Form/FormReadonly/index'></code>
<code src='../../demo/pages/Form/FormImageUploadRules/index'></code>
<code src='../../demo/pages/Form/FormJSON/index'></code>
使用 `validateStatus: success` 及 `footer slot` 来自定义错误样式。
<code src='../../demo/pages/Form/FormCustomError/index'></code>
通过使用 [FormItem](
<code src='../../demo/pages/Form/FormCustom/index'></code>
<code src='../../demo/pages/Form/index'></code>
所有 Form 组件都包括的属性
| 属性 | 说明 | 类型 | 默认值 |
| -----|-----|-----|-----|
| dependencies | 设置依赖字段，查看[详细说明](
| footer | 底部 slot，接收 errors、status | slot | - |
| name | 名称 | string | - |
| label | 文本 | string | - |
| labelWidth | 文本宽度 | string | - |
| position | 布局，可选 `horizontal` `vertical` | string | horizontal |
| validateStatus | 校验状态，如不设置，则会根据校验规则自动生成，可选 `default` `success` `error` `validating` | string | - |
| help | 提示信息，如不设置，则会根据校验规则自动生成 | string | - |
| header | 顶部 slot，接收 errors、status | slot | - |
| tooltip | 表单项提示信息 | string\|slot | - |
| required | 必填样式设置。如不设置，则会根据校验规则自动生成 | boolean | false |
| message | 校验错误信息。如不设置，则会根据校验规则自动生成 | string | false |
| requiredMark | 必填选填的标记样式，可选 `asterisk` `text-required` `text-optional` | string | asterisk |
| 属性 | 说明 | 类型 |
| ---------------- | -------------- | ----------------------------------------- |
| rules | 可选，校验规则 | 查看[rules](
| initialValues | 可选，初始值 | Record<string, any> |
| validateMessages | 可选，校验消息 | 查看[validateMessages](
| 属性 | 说明 | 类型 |
| ------------------------ | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| addItem | 添加表单项 | (formItem: Ref) => void |
| updateRules | 更新 form 的校验规则，每次都需要传入全量的 rules | (rules: Rules) => void, Rules 的类型可以查看[rules](
| getFieldValue | 得到表单项的值 | (name: string) => any |
| getFieldsValue | 获取一组字段名对应的值。不传 nameList 则返回全部 fields 对 | (nameList?: string[]) => Record<string, any> |
| getFieldValidatorStatus | 得到表单校验状态 | (name: string) => [ValidatorStatus](
| getFieldsValidatorStatus | 得到一组表单校验状态。不传 nameList 则返回全部 fields 对 | (nameList?: string[]) => Record<string, [ValidatorStatus](
| reset | 重置表单为初始值 | () => void |
| isFieldTouched | 判断表单项是否被修改过 | () => boolean |
| onValueChange | 侦听指定表单项的值修改，查看[详细说明](
| onValuesChange | 侦听表单项的值修改，查看[详细说明](
| setFieldValue | 设置表单项的值 | (name: string, value: any) => void; |
| setFieldsValue | 设置表单项的值 | (values: Record<string, any>) => void; |
| setFieldValidatorStatus | 设置表单校验状态 | (name: string, validatorStatus: [ValidatorStatus](
| setFieldsValidatorStatus | 设置一组表单校验状态 | (fieldsValidatorStatus: Record<string, [ValidatorStatus](
| setInitialValues | 设置表单初始值 | (initialValues: Record<string, any>) => void |
| submit | 提交表单，返回 promise 表单值，校验错误会抛出 | () => Promise<Record<string, any>> |
当字段间存在依赖关系时使用。例如注册用户表单的“密码”与“确认密码”字段，其中“确认密码”校验依赖于“密码”字段。设置 `dependencies` 后，“密码”字段更新将自动触发“确认密码”的校验。
示例：
```javascript
{
account: [
{
required: true,
message: '需要输入用户名'
},
],
password: [
{
required: true,
},
],
confirm: [
{
required: true,
message: '需要输入确认密码'
},
(form) => ({
async validator(_, value) {
if (!value || form.getFieldValue('password') === value) {
return;
}
throw new Error('两次密码需一致');
},
}),
]
}
```
`rules` 可以在 `new Form` 中设置，也可以在 `FormItem` 通过 `required` 或 `message` 属性设置。
```html
<form-input
label="用户名"
name="account"
required
message="请输入用户名"
ref="handleRef"
></form-input>
```
可以参考 [Asynchronous validator](https://github.com/yiminghe/async-validator/blob/master/src/messages.ts#L4-L55) 的 message，antd-mini 在此基础上加了 `${label}`,`${len}`,`${min}`,`${max}`,`${pattern}`。
示例：
```javascript
{
required: '需要输入${label}',
string: {
min: '${label}最少${min}个字符',
},
pattern: {
mismatch: '${label}需要满足${pattern}模式',
},
}
```
`setFieldValue` 和 `setFieldsValue` 不会触发 `onValueChange` 和 `onValuesChange`。`onValueChange` 和 `onValuesChange` 只有在用户操作时才会被触发。如果在 `setFieldValue` 或 `setFieldsValue` 之后想要触发 `onValueChange` 或 `onValuesChange`，你需要手动调用这些方法。
**示例**：
```js
const onValuesChangeCallback = (changedValues) => {
console.log(changedValues);
};
this.form.onValuesChange(onValuesChangeCallback);
this.form.setFieldValue(name, value);
onValuesChangeCallback({
[]: value,
});
```
```js
type ValidatorStatus = {
status: 'default' | 'success' | 'error' | 'validating',
errors: string[],
};
```
```js
{
values: Record<string, any>,
errorFields: {
name: string;
errors: string[];
}[]
}
```
与 `Input` 相同。
与 `Textarea` 相同。
与 `Switch` 相同。
与 `Stepper` 相同，但添加了如下属性：
| 属性 | 说明 | 类型 | 默认值 |
| ---------------- | --------------------------------- | ------ | ------ |
| stepperClassName | 对应 `Stepper` 组件的 `className` | string | - |
| stepperStyle | 对应 `Stepper` 组件的 `style` | string | - |
与 `CheckGroup` 相同，但添加了如下属性：
| 属性 | 说明 | 类型 | 默认值 |
| ---------------- | ----------------------------------- | ------ | ------ |
| checkboxLabel | 对应 `CheckGroup` 组件的 `label` | slot | - |
| checkboxPosition | 对应 `CheckGroup` 组件的 `position` | string | - |
与 `RadioGroup` 相同，但添加了如下属性：
| 属性 | 说明 | 类型 | 默认值 |
| ------------- | ----------------------------------- | ------ | ------ |
| radioLabel | 对应 `RadioGroup` 组件的 `label` | slot | - |
| radioPosition | 对应 `RadioGroup` 组件的 `position` | string | - |
与 `Picker` 相同，但添加了如下属性：
| 属性 | 说明 | 类型 | 默认值 |
| ----- | -------------------------------------------------------- | ----------------- | ------ |
| arrow | 右侧箭头，可选 `right`、`up`、`down`，传 true 为 `right` | string \| boolean | - |
与 `DatePicker` 相同，但添加了如下属性：
| 属性 | 说明 | 类型 | 默认值 |
| ----- | -------------------------------------------------------- | ----------------- | ------ |
| arrow | 右侧箭头，可选 `right`、`up`、`down`，传 true 为 `right` | string \| boolean | - |
与 `RangePicker` 相同，但添加了如下属性：
| 属性 | 说明 | 类型 | 默认值 |
| ----- | -------------------------------------------------------- | ----------------- | ------ |
| arrow | 右侧箭头，可选 `right`、`up`、`down`，传 true 为 `right` | string \| boolean | - |
与 `CascaderPicker` 相同，但添加了如下属性：
| 属性 | 说明 | 类型 | 默认值 |
| ----- | -------------------------------------------------------- | ----------------- | ------ |
| arrow | 右侧箭头，可选 `right`、`up`、`down`，传 true 为 `right` | string \| boolean | - |
与 `Slider` 相同。
与 `Selector` 相同。
与 `ImageUpload` 相同。
`createForm` 是一个 `mixin`，用于自定义表单项。
```js
import { createForm } from 'antd-mini/es/Form/form';
Component({
mixins: [createForm()],
methods: {
onChange(value) {
this.emit('onChange', value);
},
},
});
```
`createForm` 会为组件增加以下内容：
- `data`
```js
{
formData: {
value: undefined, // 表单项的值
status: 'default', // 表单项的校验状态，包括 `default`、`success`、`error`、`validating`
errors: [], // 错误信息
},
}
```
- `methods`
```js
// 修改表单项时，需调用 `emit` 方法。自定义表单项组件在值改变时，应该调用此方法。
function emit(trigger: 'onChange' | 'onBlur' | 'onFocus', value: any): void;
```
想要了解更多方法，请参考 `createForm` 方法相关文档。使用 `formData` 和 `emit` 即可完成自定义表单项的实现。
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 变量名 | 默认值 | 深色模式默认值 | 备注 |
| --------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------- |
| --form-text-color | <div style="width: 150px; height: 30px; background-color: #cccccc; color: #333333;">
| --form-item-color | <div style="width: 150px; height: 30px; background-color: #666666; color: #ffffff;">
| --form-item-bg | <div style="width: 150px; height: 30px; background-color: #ffffff; color: #333333;">
| --form-error-color | <div style="width: 150px; height: 30px; background-color: #ff3141; color: #ffffff;">
| --form-extra-color | <div style="width: 150px; height: 30px; background-color: #999999; color: #ffffff;">
| --form-asterisk-color | <div style="width: 150px; height: 30px; background-color: #ff3b30; color: #ffffff;">