表单

表单组件。

重要提示

DANGER

表单组件验证使用的是 async-validator 库，使用前需先安装 async validator。

npm install async-validator

基础使用

在表单中使用 <pure-form-item> 组件定义表单项，具体使用方式见下方示例。

<template>
	<!--
	* 通过 `model` 属性绑定表单数据
	* 通过 `rules` 属性绑定表单校验规则
	-->
	<pure-form :model="form" :rules="rules">
		<!--
		* 一个表单字段
		* 通过 `prop` 设置表单字段的属性名，用于和绑定的表单数据进行关联
		-->
		<pure-form-item prop="name">
			<!-- 通过默认插槽设置字段内容 -->
			<pure-input v-model="form.name" placeholder="请输入用户名" :maxlength="10"></pure-input>
		</pure-form-item>

		<!--
		* 一个表单字段
		* 通过 `prop` 设置表单字段的属性名，用于和绑定的表单数据进行关联
		* 通过 `rules` 单独给该字段设置校验规则，优先级高于 <pure-form> 上设置的规则。
		-->
		<pure-form-item prop="age" :rules="rules.age">
			<!-- 通过默认插槽设置字段内容 -->
			<pure-input v-model="form.age" placeholder="请输入年龄" type="number"></pure-input>
		</pure-form-item>
	</pure-form>
</template>

<script setup lang="ts">
import { ref } from 'vue';

// 表单数据
const form = ref({
	name: '',
	age: 18,
});

// 表单校验规则
const rules = ref({
	username: [
		{ required: true, message: '请输入用户名', trigger: 'blur' },
	],
	age: [
		{ required: true, message: '请输入年龄', trigger: 'blur' },
	],
});

必填符号

以下几种情况会显示必填符号：

• <pure-form-item> 组件的 required 属性设置为 true。
• 验证规则中有 required: true 规则。

<template>
	<pure-form :model="form" :rules="rules">
		<!--
		* 通过 `required` 属性提示该字段必填
		* 重要提示：通过此种方式只是在样式上添加了必填符号，实际进行表单校验时，最终还是校验的配置规则中有没有设置必填。
		-->
		<pure-form-item label="用户名" prop="name" required>
			<pure-input v-model="form.name" placeholder="请输入用户名"></pure-input>
		</pure-form-item>

		<!--
		* 虽然没有在 <pure-form-item> 组件中设置 required 属性
		* 但是校验规则中有设置 required: true 规则
		* 所以最终还是会在样式上提示必填符号
		-->
		<pure-form-item label="年龄" prop="age">
			<pure-input v-model="form.age" placeholder="请输入年龄"></pure-input>
		</pure-form-item>
	</pure-form>
</template>

<script setup lang="ts">
import { ref } from "vue";

// 表单数据
const form = ref({
	name: "",
	age: 18,
});

// 表单校验规则
const rules = ref({
	// 虽然在 <pure-form-item> 组件中设置了 required 属性
	// 但是校验规则中并没有设置 required: true 规则
	// 所以最终校验时并不会校验该字段是否必填
	name: [{ message: "请输入用户名", trigger: "blur" }],

	// 年龄字段的校验规则中设置了 required: true 规则
	// 所以最终还是会在样式上提示必填符号
	age: [{ required: true, message: "请输入年龄", trigger: "blur" }],
});
</script>

可以通过以下几种方式隐藏必填符号：

• 通过 requiredSymbol 属性设置必填符号，默认值为 *。
• 如果字段是必填项，但是又不想显示必填符号：
  • 可以通过将 <pure-form> 的 requiredSymbol 属性设置为空字符串 '' 用来隐藏表单内的所有必填符号。
  • 可以通过将 <pure-form> 的 hideRequiredSymbol 属性设置为 true 用来隐藏表单内的所有必填符号。
  • 可以通过将 <pure-form-item> 的 requiredSymbol 属性设置为空字符串 '' 用来隐藏单个字段的必填符号。

<template>
	<!-- 方式一 -->
	<!-- 通过设置 requiredSymbol 为空字符串 '' 来隐藏所有必填符号 -->
	<pure-form :model="form" :rules="rules" requiredSymbol=""></pure-form>

	<!-- 方式二 -->
	<!-- 通过设置 hideRequiredSymbol 属性来隐藏所有必填符号 -->
	<pure-form :model="form" :rules="rules" hideRequiredSymbol></pure-form>

	<!-- 方式三 -->
	<pure-form :model="form" :rules="rules">
		<!-- 通过设置 requiredSymbol 为空字符串 '' 来隐藏单个字段的必填符号 -->
		<pure-form-item label="用户名" prop="name" requiredSymbol="">
			<pure-input v-model="form.name" placeholder="请输入用户名"></pure-input>
		</pure-form-item>
	</pure-form>
</template>

<script setup lang="ts">
import { ref } from "vue";

// 表单数据
const form = ref({
	name: "",
});

// 表单校验规则
const rules = ref({
	name: [{ required: true, message: "请输入用户名", trigger: "blur" }],
});
</script>

字段图标

可以在 <pure-form> 或 <pure-form-item> 组件上设置以下几种属性来配置字段图标，设置在 <pure-form> 组件上的属性会影响表单内的所有字段，设置在 pure-form-item 组件上的属性只会影响当前字段，pure-form-item 上的属性优先级高于 <pure-form> 组件上设置的值。

• iconName：图标名称。
• iconOpts：图标配置 参考。

<template>
	<pure-form :model="form" :rules="rules">
		<pure-form-item iconName="__user" prop="name">
			<pure-input v-model="form.name" placeholder="请输入用户名"></pure-input>
		</pure-form-item>
	</pure-form>
</template>

字段标签

• 通过 label 属性设置标签文本。
• 通过 sublabel 属性设置副标签文本。

<template>
	<pure-form :model="form" :rules="rules">
		<pure-form-item label="用户名" sublabel="(副标签)" prop="name">
			<pure-input v-model="form.name" placeholder="请输入用户名"></pure-input>
		</pure-form-item>
	</pure-form>
</template>

标签位置

更具体的来说应该是左侧内容（必填符号 + 图标 + 标签 + 副标签）的显示位置。

通过 labelPosition 属性设置标签位置，可选值为：

• left：左侧。
• top：上方。

可以设置在 <pure-form> 或 <pure-form-item> 组件上，设置在 <pure-form> 组件上的属性会影响表单内的所有字段，设置在 pure-form-item 组件上的属性只会影响当前字段，pure-form-item 上的属性优先级高于 <pure-form> 组件上设置的值。

<template>
	<!-- 全局设置 -->
	<pure-form :model="form" :rules="rules" labelPosition="top"> </pure-form>

	<pure-form :model="form" :rules="rules">
		<!-- 单字段设置 -->
		<pure-form-item iconName="__user" prop="name" labelPosition="top">
			<pure-input v-model="form.name" placeholder="请输入用户名"></pure-input>
		</pure-form-item>
	</pure-form>
</template>

禁用表单

通过给 <pure-form> 组件设置 disabled 属性即可禁用整个表单。
表单禁用状态时，所有字段都将被禁用，不会触发任何事件，一般在展示表单数据，不希望用户编辑的时候使用。

<template>
	<pure-form :model="form" :rules="rules" disabled> </pure-form>
</template>

禁用字段

给 <pure-form-item> 设置 disabled 属性即可禁用该字段。

• 不可编辑
• 不触发事件
• 有禁用样式

<template>
	<pure-form :model="form" :rules="rules">
		<pure-form-item disabled prop="name">
			<pure-input v-model="form.name" placeholder="请输入用户名"></pure-input>
		</pure-form-item>
	</pure-form>
</template>

只读字段

给 <pure-form-item> 设置 readonly 属性即可将该字段设置为只读。

• 不可编辑
• 会触发点击事件
• 无特殊样式

一般用于点击弹窗选择时使用。

<template>
	<pure-form :model="form" :rules="rules">
		<pure-form-item readonly prop="like" @onClick="handleShowPopup">
			<pure-input v-model="form.like" placeholder="请选择喜欢的颜色"></pure-input>
		</pure-form-item>
	</pure-form>

	<!-- 弹窗选择器 -->
	<pure-picker :show="popupVisible"></pure-picker>
</template>

<script setup lang="ts">
import { ref } from 'vue'

// 表单数据
const form = ref({
	like: ''
});

// 弹窗显示状态
const popupVisible = ref(false);

// 显示弹窗
function handleShowPopup () {
	// 切换弹窗显示状态
	popupVisible.value = !popupVisible.value;
}

内容对齐方式

通过 content-align 属性可以设置字段内容（默认插槽、错误提示）的对齐方式，可选值有 left、right。
可以设置在 <pure-form> 组件上，也可以设置在 <pure-form-item> 组件上，设置在 <pure-form> 组件上的属性会影响表单内的所有字段，设置在 <pure-form-item> 组件上的属性只会影响当前字段，<pure-form-item> 上的属性优先级高于 <pure-form> 组件上设置的值。

<template>
	<!-- 整个表单内容右对齐 -->
	<pure-form :model="form" :rules="rules" content-align="right"></pure-form>

	<pure-form :model="form" :rules="rules">
		<!-- 只读字段内容右对齐 -->
		<pure-form-item readonly prop="like" content-align="right">
			<pure-input v-model="form.like" placeholder="请输入喜欢的颜色"></pure-input>
		</pure-form-item>
	</pure-form>
</template>

表单验证

表单验证组件使用的是 async-validator 库，你可以在 async-validator 库的文档中查看所有可用的验证规则。

重要提示

支付宝小程序需启用 component2 ，否则使用无法获取表单组件的 ref 实例，继而无法使用组件对外暴漏的属性和方法。

设置验证规则

可以在 <pure-form> 组件上设置表单验证规则，也可以在 <pure-form-item> 组件上设置单字段验证规则。 设置在 <pure-form-item> 上的验证规则会覆盖 <pure-form> 组件上的验证规则。

• <pure-form> 组件上使用 rules 属性设置表单验证规则。
• <pure-form-item> 组件上使用 rule 属性设置单字段验证规则。

<template>
	<pure-form :model="form" :rules="rules" ref="formRef">
		<!-- 姓名 -->
		<pure-form-item prop="name" label="姓名">
			<pure-input v-model="form.name" placeholder="请填写您的姓名"></pure-input>
		</pure-form-item>

		<!-- 手机号 -->
		<pure-form-item prop="phone" label="手机号">
			<pure-input v-model="form.phone" placeholder="请填写您的手机号"></pure-input>
		</pure-form-item>

		<!-- 提交按钮 -->
		<pure-form-item>
			<pure-button type="primary" @onClick="handleSubmit">提交</pure-button>
		</pure-form-item>
	</pure-form>
</template>

<script setup lang="ts">
import { ref } from 'vue';

// 定义表单 Ref
const formRef = ref(null);

// 表单数据
const form = ref({
	name: '',
	phone: '',
});

// 表单校验规则
const rules = ref({
	name: [
		{ required: true, message: '请填写您的姓名', trigger: 'blur' },
	],
	phone: [
		{ required: true, message: '请填写您的手机号', trigger: 'blur' },
	],
});

// 提交表单
function handleSubmit() {
	// 验证整个表单
	formRef.value
		.validate()
		.then(() => {
			// 验证通过，执行提交操作
			console.log('表单验证通过');
		})
		.catch(() => {
			// 验证失败，处理错误信息
			console.log('表单验证失败');
		});

	// 验证单个字段
	formRef.value
		.validateField('name')
		.then(() => {
			// 验证通过，执行提交操作
			console.log('姓名验证通过');
		})
		.catch(() => {
			// 验证失败，处理错误信息
			console.log('姓名验证失败');
		});

	// 验证多个字段
	formRef.value
		.validateFields(['name', 'phone'])
		.then(() => {
			// 验证通过，执行提交操作
			console.log('姓名和手机号验证通过');
		})
		.catch(() => {
			// 验证失败，处理错误信息
			console.log('姓名和手机号验证失败');
		});
}

提示方式

通过 errorMode 属性设置表单验证错误提示方式。

• message：在下方显示错误提示消息。
• none：不提示。
• border：显示 4 个边框用于提示。
• border-bottom：显示底部边框用于提示。
• toast：弹出消息提示。

属性

<pure-form>

名称	类型	默认值	说明
model	Object	{}	表单模型
rules	Object	{}	校验规则
disabled	Boolean	false	是否禁用整个表单
requiredSymbol	String	*	必填符号
labelPosition	String	left	标签位置，可选值为 left、top
hideRequiredSymbol	Boolean	false	是否隐藏整个表单的必填符号
iconOpts	Object	{}	整个表单的图标配置选项 参考
showArrow	Boolean	false	是否显示右侧箭头，影响整个表单
arrowIconName	String	arrow-right	右侧箭头图标名称，影响整个表单
arrowIconOpts	Object	{}	右侧箭头图标配置选项，影响整个表单 参考
contentAlign	String	left	内容对齐方式，影响整个表单，可选值为 left、right
errorMode	String	left	错误提示模式，可选值为 message、none、border、 border-bottom 和 toast
alwaysTips	Boolean	false	提示是否一直存在，这样显示提示时表单高度不会因为提示而改变

<pure-form-item>

名称	类型	默认值	说明
prop	String	''	字段名
rule	[Object, Array]	{}	校验规则
required	Boolean	false	是否必填，只展示必填符号，不参与校验
requiredSymbol	String	*	必填符号
iconName	String	''	图标名称
iconOpts	Object	{}	整个表单的图标配置选项 参考
label	String	''	标签文本
sublabel	String	''	副标签文本
labelPosition	String	left	标签位置，可选值为 left、top
showArrow	Boolean	false	是否显示右侧箭头
arrowIconName	String	arrow-right	右侧箭头图标名称
arrowIconOpts	Object	{}	右侧箭头图标配置选项 参考
arrowRotate	Boolean	false	是否旋转右侧箭头
disabled	Boolean	false	是否禁用
readonly	Boolean	false	是否只读
contentAlign	String	left	内容对齐方式，影响整个表单，可选值为 left、right
hideRequiredSymbol	Boolean	false	是否隐藏必填符号
alwaysTips	Boolean	false	提示是否一直存在，这样显示提示时表单高度不会因为提示而改变

事件

<pure-form-item>

名称	参数	说明
onClick		点击事件

方法

<pure-form-item>

名称	参数	返回值	说明
validate		Promise- then 表示校验通过; catch 表示校验未通过	校验表单
validateField	fieldName: string	Promise- then 表示校验通过; catch 表示校验未通过	校验单个字段
validateFields	fieldNames: string[]	Promise- then 表示校验通过; catch 表示校验未通过	校验多个字段

插槽

<pure-form>

名称	参数	说明
#default		默认，徽标内容

<pure-form-item>

名称	参数	说明
#left		左侧内容（图标 + 标签 + 必填符号）
#icon		图标
#label		标签
#required		必填符号
#default		默认，表单项内容
#right		右侧内容（包含箭头）
#arrow		右侧箭头

样式变量

<pure-form>

名称	说明
--pure-form-display	显示方式

<pure-form>

名称	说明
--pure-form-item-padding	内边距
--pure-form-item-align-items	对齐方式
--pure-form-item-gap	内容块之间的间距
--pure-form-item-left-flex-direction	左侧内容布局方向
--pure-form-item-left-align-items	左侧内容对齐方式
--pure-form-item-left-justify-content	左侧内容对齐方式
--pure-form-item-left-gap	左侧内容之间的间距
--pure-form-item-left-width	左侧内容宽度
--pure-form-item-left-max-width	左侧内容最大宽度
--pure-form-item-required-display	必填符号显示方式
--pure-form-item-required-flex-direction	必填符号布局方向
--pure-form-item-required-align-items	必填符号对齐方式
--pure-form-item-required-justify-content	必填符号对齐方式
--pure-form-item-required-font-size	必填符号字体大小
--pure-form-item-required-font-weight	必填符号字体粗细
--pure-form-item-required-color	必填符号字体颜色
--pure-form-item-required-position	必填符号定位方式
--pure-form-item-required-left	必填符号定位位置
--pure-form-item-required-top	必填符号定位位置
--pure-form-item-required-right	必填符号定位位置
--pure-form-item-required-bottom	必填符号定位位置
--pure-form-item-required-z-index	必填符号层级
--pure-form-item-required-margin	必填符号外边距
--pure-form-item-required-padding	必填符号内边距
--pure-form-item-required-order	必填符号排序
--pure-form-item-required-transform	必填符号变换
--pure-form-item-icon-font-size	图标字体大小
--pure-form-item-icon-font-weight	图标字体粗细
--pure-form-item-icon-color	图标字体颜色
--pure-form-item-icon-margin	图标外边距
--pure-form-item-icon-padding	图标内边距
--pure-form-item-icon-width	图标宽度
--pure-form-item-icon-height	图标高度
--pure-form-item-icon-order	图标排序
--pure-form-item-label-font-size	标签字体大小
--pure-form-item-label-font-weight	标签字体粗细
--pure-form-item-label-color	标签字体颜色
--pure-form-item-label-margin	标签外边距
--pure-form-item-label-padding	标签内边距
--pure-form-item-label-width	标签宽度
--pure-form-item-label-height	标签高度
--pure-form-item-label-order	标签排序
--pure-form-item-sublabel-font-size	子标签字体大小
--pure-form-item-sublabel-font-weight	子标签字体粗细
--pure-form-item-sublabel-color	子标签字体颜色
--pure-form-item-sublabel-margin	子标签外边距
--pure-form-item-sublabel-padding	子标签内边距
--pure-form-item-sublabel-width	子标签宽度
--pure-form-item-sublabel-height	子标签高度
--pure-form-item-sublabel-order	子标签排序
--pure-form-item-main-text-align	主内容文本对齐方式
--pure-form-item-content-margin	主内容外边距
--pure-form-item-content-padding	主内容内边距
--pure-form-item-content-align-items	主内容垂直对齐方式
--pure-form-item-content-min-height	主内容最小高度
--pure-form-item-right-gap	右侧内容之间的间距
--pure-form-item-arrow-font-size	箭头字体大小
--pure-form-item-arrow-font-weight	箭头字体粗细
--pure-form-item-arrow-color	箭头字体颜色
--pure-form-item-arrow-margin	箭头外边距
--pure-form-item-arrow-padding	箭头内边距
--pure-form-item-arrow-width	箭头宽度
--pure-form-item-arrow-height	箭头高度
--pure-form-item-arrow-rotate	箭头旋转角度
--pure-form-item-arrow-transition	箭头过渡效果
--pure-form-item-tips-font-size	提示字体大小
--pure-form-item-tips-font-weight	提示字体粗细
--pure-form-item-tips-color	提示字体颜色
--pure-form-item-tips-margin	提示外边距
--pure-form-item-tips-padding	提示内边距
--pure-form-item-tips-width	提示宽度
--pure-form-item-tips-height	提示高度
--pure-form-item-left-padding-left	左侧内容内边距
--pure-form-item-tips-text-align	提示文本对齐方式
--pure-form-item-error-border-color	提示框颜色
--pure-form-item-error-border-width	提示框边框宽度
--pure-form-item-disabled-opacity	禁用状态透明度