1. 动态表单到底是什么?为什么我们需要它?
大家好,我是老张,一个在移动端开发里摸爬滚打了十来年的老码农。今天咱们不聊那些虚头巴脑的概念,就聊聊在 UniApp 里做动态表单那些事儿。你可能已经用过 uni-forms 组件了,静态的表单,比如登录注册,填个姓名电话,那都是小菜一碟。但一遇到“动态表单”,很多新手朋友就开始头疼了。
什么是动态表单?简单说,就是表单的项不是写死在代码里的,而是可以根据用户的操作动态增加、减少,甚至改变类型的。举个最生活化的例子:你填一个报销单,餐费、交通费、住宿费,每一项都可以点个“+”号新增一行,也可以点“-”号删掉一行。再比如,做一个商品属性管理,不同类别的商品需要填写的参数完全不一样,这时候就需要一个能“变”的表单。
为什么静态表单搞不定呢?因为静态表单的字段数量、类型、校验规则在编译时就已经固定了。而动态表单的需求核心是运行时决定。用户点了“添加”,你才需要多渲染一个输入框,同时这个新输入框的数据要能正确收集,校验规则要能独立生效,删除时还得把对应的数据清理干净。这背后涉及到数据绑定、列表渲染、表单校验的联动,确实比静态表单复杂一个层级。
我在实际项目中踩过不少坑,比如数据绑定乱了套,新增的项校验不触发,或者删除中间项导致数据错位。所以,今天我就把自己趟出来的路,总结成一套小白也能懂、上手就能用的实战技巧和最佳实践,手把手带你搞定 UniApp 动态表单。
2. 核心基石:设计好你的数据模型
在动手写代码之前,咱们得先把“地基”打好。这个地基,就是你的数据模型。数据模型设计得好,后面的渲染、校验、提交都会顺风顺水;设计得不好,那就是给自己挖坑,代码会变得又臭又长。
2.1 为什么一定要用数组?
原始文章里提到了一点:“当某个字段为动态时,要用数组来存放多个值”。这句话是黄金法则,一定要刻在脑子里。很多新手会想,我用一个对象,里面动态添加属性行不行?比如 formData.item1, formData.item2。我告诉你,这条路走不通,或者说会走得非常痛苦。
为什么非得是数组?因为动态表单的本质是一个字段对应多个值,并且这多个值在结构上是完全平等的。数组天生就是为存储有序、同构的数据集合而生的。它和 v-for 指令是绝配,可以完美地实现列表渲染。你新增一项,就是往数组里 push 一个元素;删除一项,就是从数组里 splice 一个元素。视图会自动更新,管理起来逻辑清晰无比。
让我们看看一个反例和正例的对比:
// ❌ 反例:使用动态键名的对象(极其不推荐)
let formData = {
dynamicField: {}
};
// 当你新增一项时
formData.dynamicField[`item_${Date.now()}`] = { value: '' };
// 渲染和遍历变得复杂,校验更是噩梦,无法使用数组索引精准定位。
// ✅ 正例:使用数组(推荐)
let formData = {
domains: [] // 用于存储多个域名
};
// 新增一项
formData.domains.push({ id: Date.now(), value: '' });
// 删除第 index 项
formData.domains.splice(index, 1);
看到了吗?数组的方案简洁、可预测。原始文章的作者也提到了,他使用的是包含 id 及 value 的对象结构。这个 id 非常关键,它通常是创建时的时间戳或一个唯一标识。为什么需要 id?因为 v-for 渲染列表时,需要一个唯一的 :key 来帮助 Vue 高效地更新虚拟 DOM。如果你用数组的 index 当 key,在中间删除项时会导致渲染错乱和状态问题,这是一个常见的坑。用唯一的 id 作为 key 是最佳实践。
2.2 设计一个健壮的数据结构
基于上面的原则,我们可以设计一个更通用的动态表单数据模型。不仅仅是 id 和 value,根据业务需求,你还可以扩展。
// 初始化表单数据的函数
const resetForm = () => {
return {
// 静态字段
userName: '',
email: '',
// 动态字段 - 参与人列表
participants: [
{
id: Date.now(), // 唯一标识,用于 :key
value: '', // 输入值
// 你可以根据需要扩展其他属性
type: 'text', // 字段类型,未来可能支持切换
placeholder: '请输入参与人姓名',
rules: [{ required: true, errorMessage: '参与人不能为空' }] // 甚至可以每个项独享规则
}
],
// 动态字段 - 工作时间段列表
workTimeList: [
{
id: Date.now() + 1,
value: [], // 这里用数组,因为 uni-datetime-picker 的 range 类型返回数组
startPlaceholder: '开始时间',
endPlaceholder: '结束时间'
}
]
};
};
// 在 Vue3 的 setup 中使用
import { ref } from 'vue';
const formData = ref(resetForm());
这个结构清晰明了:静态字段单独存放,每个动态字段都是一个数组,数组里的每个元素都是一个描述该项所有信息的对象。这样,无论是渲染、校验还是提交数据,你都能清晰地定位到每一个表单项。
3. 视图层渲染:让 v-for 和 uni-forms-item 共舞
数据模型准备好后,下一步就是把它渲染到页面上。这里是动态表单的“面子工程”,也是最体现技巧的地方。
3.1 基础渲染与动态绑定
核心就是利用 v-for 指令遍历我们的动态数组,并为每一项生成一个 uni-forms-item。这里有几个关键点,直接对应原始文章里的代码,我来给你掰开揉碎了讲。
第一,v-model 的动态绑定。
你的输入组件(如 uni-easyinput, uni-datetime-picker)必须绑定到数组对应的具体元素上。
<view v-for="(item, index) in formData.participants" :key="item.id">
<uni-forms-item :label="index === 0 ? '参与人' : ''" :required="index === 0">
<uni-easyinput
v-model="formData.participants[index].value"
:placeholder="item.placeholder || '请输入内容'"
/>
</uni-forms-item>
</view>
注意 v-model="formData.participants[index].value",它精准地绑定了当前遍历项的数据。这样,任何一个输入框的变化,都会直接同步到 formData 中对应的位置。
第二,label 的智能显示。
通常只有第一项需要显示 label(如“参与人”),后面的项 label 区域留空即可,这样视觉上更紧凑。原始文章里用了 :label="index == 0 ? '参与人' : ''" 和 v-slot:label 的方式来实现。我更推荐一种简洁写法:
<uni-forms-item :label="index === 0 ? '参与人' : null">
将 label 设为 null 或 undefined,uni-forms-item 会自动不渲染 label 区域,比传入空字符串并配合插槽更简单。
3.2 动态 name 与表单校验的桥梁
这是动态表单校验的灵魂所在,也是新手最容易懵的地方。uni-forms 组件需要通过每个 uni-forms-item 的 name 属性来建立表单域与校验规则的关联。对于动态表单,这个 name 必须是动态的、能指向深层数据结构的。
原始文章给出了关键代码::name="['domains', index, 'value']"。
这是什么意思?这是一个“路径数组”。它告诉 uni-forms 组件:请去 formData 这个对象里,找到 domains 属性,它是一个数组,再找到这个数组的第 index 个元素,最后取这个元素下的 value 属性值来进行校验。
它完全等价于 formData.domains[index].value。使用数组路径的写法是 uni-forms 组件约定的,为了能动态解析。所以,你的代码必须这样写:
<view v-for="(item, index) in formData.participants" :key="item.id">
<uni-forms-item
:name="['participants', index, 'value']"
:label="index === 0 ? '参与人' : null"
:required="index === 0"
:rules="[{ required: true, errorMessage: '参与人不能为空' }]"
>
<uni-easyinput v-model="formData.participants[index].value" />
</uni-forms-item>
</view>
重要提示:v-model 绑定的路径和 :name 指定的校验路径,必须指向数据的同一个位置!否则会出现“输入了值但校验依然报错”的灵异事件。我早期就犯过这个错,调试了半天。
4. 实现动态增删:让表单“活”起来
光能渲染还不够,动态表单的核心交互就是“增删”。咱们来实现它。
4.1 新增表单项
新增项的本质,就是向对应的动态数组里 push 一个新的元素对象。这个新对象的结构必须和已有的项保持一致。
// 添加一个参与人项
const addParticipant = () => {
formData.value.participants.push({
id: Date.now(), // 生成新的唯一ID
value: '', // 初始值为空
placeholder: '请输入参与人姓名'
});
};
// 添加一个工作时间段
const addWorkTime = () => {
formData.value.workTimeList.push({
id: Date.now(),
value: [], // 时间范围选择器,初始为空数组
startPlaceholder: '开始时间',
endPlaceholder: '结束时间'
});
};
在模板中,给一个加号按钮绑定这个事件即可。记得像原始文章那样,只在第一项或某项旁边显示“添加”按钮,避免每项后面都出现加号的混乱UI。
4.2 删除表单项
删除项的核心是调用数组的 splice 方法。这里有个大坑:你不能直接根据 item.id 来删除,因为 splice 需要的是数组索引。我们需要在遍历时拿到 index。
// 删除指定索引的参与人项
const deleteParticipant = (index) => {
formData.value.participants.splice(index, 1);
};
在模板中,将删除按钮绑定到该方法,并传入当前项的 index。注意,通常第一项(索引0)不允许删除,因为至少要保留一项。原始文章里用了 v-if="index" 来控制删除按钮的显示,这个逻辑很实用。
<uni-icons
v-if="index > 0"
@click="deleteParticipant(index)"
type="minus"
color="#e43d33"
></uni-icons>
删除操作后的校验重置:这里有个进阶技巧。当你删除中间某一项后,数组的索引变了,但 uni-forms 内部可能还缓存着之前索引的校验状态。为了安全起见,在删除操作后,可以手动触发一次对应动态字段的校验清理或重新验证。可以使用 this.$refs.form.setValue 重新设置一下该数组的值,或者调用 this.$refs.form.validateField 重新校验整个数组字段。这是我踩过坑后总结的经验。
5. 复杂校验实战:超越必填项
动态表单的校验,绝不仅仅是“不能为空”。我遇到过很多复杂场景,比如“至少填写两项”、“时间范围不能重叠”、“动态项总和不能超过100”等等。这些都需要更精细的校验策略。
5.1 自定义校验规则函数
uni-forms 支持自定义校验函数,这给我们打开了无限可能。假设我们有一个动态添加的“技能标签”列表,要求至少填写2个,最多5个。
首先,定义表单数据:
formData: {
skills: [{ id: 1, value: '' }, { id: 2, value: '' }] // 初始两项
}
然后,我们可以定义一个针对整个 skills 数组的校验规则,这个规则不挂在单个 uni-forms-item 上,而是通过表单的 rules 属性或 validateFunction 来定义。
// 在表单组件上绑定自定义校验函数
<uni-forms ref="form" :model="formData" :rules="rules" :validate-trigger="bind">
// 在 rules 中定义(适用于对整个数组的校验)
const rules = {
skills: {
rules: [{
validateFunction: (rule, value, data, callback) => {
// value 就是 formData.skills 数组
const filledSkills = value.filter(item => item.value.trim() !== '');
if (filledSkills.length < 2) {
callback('至少需要填写两项技能');
} else if (filledSkills.length > 5) {
callback('最多只能填写五项技能');
} else {
callback(); // 校验通过
}
}
}]
}
}
5.2 动态项之间的关联校验
更复杂的场景是项与项之间的关联。比如多个“工作时间段”不能有时间重叠。这需要在所有项的值发生变化时进行全局校验。
我们可以在每个 uni-datetime-picker 的 @change 事件中,或者利用表单的 @validate 事件,触发一个全局检查函数。
// 检查工作时间段是否重叠的函数
const checkTimeOverlap = (timeList) => {
const ranges = timeList.map(item => item.value).filter(range => range && range.length === 2);
for (let i = 0; i < ranges.length; i++) {
for (let j = i + 1; j < ranges.length; j++) {
const [start1, end1] = ranges[i];
const [start2, end2] = ranges[j];
if (!(end1 <= start2 || end2 <= start1)) {
return `第${i+1}个和第${j+1}个时间段存在重叠`;
}
}
}
return null;
};
// 在提交表单时调用
const submitForm = async () => {
const overlapError = checkTimeOverlap(formData.value.workTimeList);
if (overlapError) {
uni.showToast({ title: overlapError, icon: 'none' });
return;
}
// 继续其他校验和提交...
};
这种业务逻辑强的校验,往往需要自己写逻辑,无法完全依赖表单组件的内置规则。把校验逻辑提取成纯函数,会让代码更清晰、可测试。
6. 性能优化与体验打磨
当动态表单项变得非常多(比如几十上百个)时,性能问题就会凸显。同时,用户体验的细节也决定了产品的专业度。
6.1 列表渲染优化
Vue 的 v-for 在列表变化时会尽可能高效地更新 DOM,但不当的使用仍会导致卡顿。
- 始终提供唯一的
:key:就像之前强调的,使用item.id而非index。这是最重要的优化项。 - 避免内联函数和方法:在
v-for循环内,避免使用内联的复杂表达式或频繁调用的方法。比如:rules="getRules(index)",如果getRules计算不复杂可以,如果复杂则建议预先计算好。 - 考虑虚拟滚动:如果列表项数量真的巨大(超过100),可以考虑使用
uni-list等支持虚拟滚动的组件来渲染表单项,但这会大幅增加复杂度,非必要不使用。大部分管理后台场景,分页是更合理的解决方案。
6.2 数据提交与重置的注意事项
提交数据:提交前,我们通常需要从 formData 中提取出后端需要的数据格式。动态数组部分,我们可能只需要提交 value 数组,而不需要 id 等前端管理用的字段。
const getSubmitData = () => {
const data = {
userName: formData.value.userName,
email: formData.value.email,
// 只提取 participants 里的 value 值,组成新数组
participants: formData.value.participants.map(item => item.value).filter(v => v.trim()),
// 对于时间范围,可能需要格式化
workTimeList: formData.value.workTimeList.map(item => ({
start: item.value[0] ? formatTime(item.value[0]) : null,
end: item.value[1] ? formatTime(item.value[1]) : null
}))
};
return data;
};
重置表单:重置动态表单不仅仅是清空输入框的值,更要将数组结构恢复到初始状态。直接调用我们一开始定义的 resetForm 函数是最稳妥的。
const handleReset = () => {
// 直接替换整个 formData 的 value
formData.value = resetForm();
// 如果需要同时清除 uni-forms 的校验状态
if (this.$refs.form) {
this.$refs.form.clearValidate();
}
};
切忌只做 formData.value.participants = [] 这样的操作,因为可能还有其他关联状态未重置。完整的重置函数能保证表单状态绝对干净。
6.3 用户体验细节
- 添加/删除的视觉反馈:添加或删除项时,可以添加简单的动画,例如 uni-app 自带的
uni.createAnimation实现淡入淡出或滑动效果,让操作更有响应感。 - 防止误删:删除按钮旁可以增加一个简单的确认提示,尤其是当项内已填写了重要内容时。
- 初始项的处理:像原始文章那样,动态列表至少保留一项,并且第一项往往是必填的,这个逻辑符合大多数用户预期。
- 键盘与滚动:在 H5 端,当动态添加项导致输入框被顶上去时,要留意键盘弹出是否会影响布局。在小程序端,则要注意
page的滚动区域是否正常。
7. 实战进阶:从后台配置动态表单
前面讲的都是前端预定义结构的动态表单。更高级的场景是,表单的结构完全由后端接口返回。比如一个通用的问卷调查系统,或者一个动态配置的活动报名页。这要求我们的前端代码具有更强的动态性。
7.1 接收并解析表单配置
假设后端返回的配置数据如下:
{
"formItems": [
{
"type": "text",
"label": "姓名",
"field": "name",
"required": true,
"defaultValue": ""
},
{
"type": "dynamic-list",
"label": "教育经历",
"field": "education",
"itemTemplate": {
"type": "text",
"placeholder": "学校名称"
},
"maxCount": 5,
"defaultValue": [""]
}
]
}
我们需要一个解析器,将这个配置转化为前端可以渲染和绑定的数据模型与组件。
// 解析配置,生成初始 formData 和组件渲染配置
const parseFormConfig = (config) => {
const formData = {};
const renderConfig = [];
config.formItems.forEach(item => {
if (item.type === 'dynamic-list') {
// 动态列表字段
formData[item.field] = item.defaultValue.map((val, idx) => ({
id: Date.now() + idx,
value: val,
config: item.itemTemplate // 保存子项配置,用于渲染
}));
renderConfig.push({ ...item, isDynamic: true });
} else {
// 静态字段
formData[item.field] = item.defaultValue;
renderConfig.push({ ...item, isDynamic: false });
}
});
return { formData, renderConfig };
};
7.2 动态渲染组件
有了 renderConfig,我们就可以在模板中动态决定渲染什么组件。
<uni-forms ref="form" :model="formData">
<template v-for="item in renderConfig" :key="item.field">
<!-- 静态字段 -->
<uni-forms-item v-if="!item.isDynamic" :label="item.label" :name="item.field" :rules="getRules(item)">
<component :is="getComponent(item.type)" v-model="formData[item.field]" :placeholder="item.placeholder" />
</uni-forms-item>
<!-- 动态字段 -->
<view v-else>
<view v-for="(subItem, subIndex) in formData[item.field]" :key="subItem.id">
<uni-forms-item :label="subIndex === 0 ? item.label : ''" :name="[item.field, subIndex, 'value']" :rules="getRules(item)">
<component
:is="getComponent(subItem.config.type)"
v-model="formData[item.field][subIndex].value"
:placeholder="subItem.config.placeholder"
/>
<!-- 动态增删按钮 -->
<uni-icons v-if="subIndex > 0" @click="removeDynamicItem(item.field, subIndex)" type="minus" />
</uni-forms-item>
</view>
<button v-if="formData[item.field].length < item.maxCount" @click="addDynamicItem(item.field, item.itemTemplate)">添加</button>
</view>
</template>
</uni-forms>
这里的 getComponent 函数是一个映射,将类型字符串(如 'text', 'number', 'date')映射到真正的 UniApp 组件(如 uni-easyinput, uni-number-box, uni-datetime-picker)。
const componentMap = {
'text': 'uni-easyinput',
'number': 'uni-number-box',
'date': 'uni-datetime-picker',
// ... 其他组件映射
};
const getComponent = (type) => {
return componentMap[type] || 'uni-easyinput';
};
7.3 处理动态校验规则
校验规则也可以从后端配置中读取,例如 required、pattern(正则)、range(范围)等。getRules 函数负责将配置项转化为 uni-forms 能识别的规则数组。
const getRules = (itemConfig) => {
const rules = [];
if (itemConfig.required) {
rules.push({ required: true, errorMessage: `${itemConfig.label}不能为空` });
}
if (itemConfig.pattern) {
rules.push({ pattern: new RegExp(itemConfig.pattern), errorMessage: itemConfig.patternMessage || '格式错误' });
}
// ... 其他规则转换
return rules;
};
通过这套机制,我们就实现了一个真正意义上的、由数据驱动的动态表单系统。前端代码变成了一个通用的渲染引擎,表单的具体表现完全由后端数据控制。这在搭建后台管理系统、问卷调查、CRM等需要高度灵活配置的场景下,威力巨大。当然,复杂度也更高,需要前后端有良好的协议约定和错误处理机制。
这套方案我曾在多个中后台项目中实践过,虽然初期搭建费点功夫,但后期面对频繁的表单需求变更时,优势就非常明显了,往往只需要后端改一下配置,前端无需发版。
447



被折叠的 条评论
为什么被折叠?



