xtf-form-array

组件说明

xtf-form-array 是表单数组组件，用于管理动态增减的表单字段组。配合 xtf-form 使用，支持添加/删除/复制项、最大/最小数量限制和行级错误收集，适用于多地址录入、多联系人和动态表单项等场景。

---

基础用法

1. 动态表单组

通过 v-model 绑定数组数据，通过 template 设置新增项模板：

<template>
  <xtf-form :model="formData" label-width="160">
    <xtf-form-array
      v-model="formData.contacts"
      title="联系人"
      :template="itemTemplate"
      :max-items="5"
    >
      <template #default="{ item, index }">
        <xtf-form-item :label="'姓名' + (index + 1)">
          <xtf-input v-model="item.name" placeholder="请输入姓名" />
        </xtf-form-item>
        <xtf-form-item :label="'电话' + (index + 1)">
          <xtf-input v-model="item.phone" type="number" placeholder="请输入电话" />
        </xtf-form-item>
      </template>
    </xtf-form-array>
  </xtf-form>
</template>

<script>
export default {
  data() {
    return {
      formData: { contacts: [{ name: '', phone: '' }] },
      itemTemplate: { name: '', phone: '' }
    }
  }
}
</script>

2. 可复制项

通过 copyable 启用复制功能：

<template>
  <xtf-form :model="formData" label-width="160">
    <xtf-form-array v-model="formData.addresses" title="地址" copyable :template="addrTemplate">
      <template #default="{ item, index }">
        <xtf-form-item :label="'地址' + (index + 1)">
          <xtf-input v-model="item.address" placeholder="请输入地址" />
        </xtf-form-item>
      </template>
    </xtf-form-array>
  </xtf-form>
</template>

<script>
export default {
  data() {
    return {
      formData: { addresses: [{ address: '' }] },
      addrTemplate: { address: '' }
    }
  }
}
</script>

3. 自定义行操作与事件

插槽可调用组件提供的增删函数，并监听所有数组变化事件：

<template>
  <xtf-form-array
    v-model="items"
    title="收货人"
    :template="template"
    copyable
    show-indexes
    @input="onInput"
    @change="onChange"
    @add="onAdd"
    @remove="onRemove"
  >
    <template #default="{ item, index, moveUp, moveDown }">
      <xtf-input v-model="item.name" :placeholder="'收货人' + (index + 1)" />
      <xtf-button label="上移" size="xs" @click="moveUp" />
      <xtf-button label="下移" size="xs" @click="moveDown" />
    </template>
  </xtf-form-array>
</template>

<script>
export default {
  data() {
    return { items: [{ name: '张三' }], template: { name: '' } }
  },
  methods: {
    onInput(value) {
      console.log('input', value)
    },
    onChange(value) {
      console.log('change', value)
    },
    onAdd(payload) {
      console.log('add', payload)
    },
    onRemove(payload) {
      console.log('remove', payload)
    }
  }
}
</script>

---

全部属性

属性	类型	默认值	作用描述	适用范围
value	Array	[]	数组数据	双向绑定
name	String	''	字段名	数据绑定
title	String	''	标题	标题
minItems	String | Number	0	最小项数	数量限制
maxItems	String | Number	0	最大项数。内部限制逻辑将 0 解析为不限；但模板仅在值不是数值时显示添加按钮，因此数值 0（如 :max-items="0"）会隐藏添加按钮，省略该属性或传字符串 '0' 可显示不限添加按钮	数量限制
removable	Boolean	true	是否可删除	删除
addable	Boolean	true	是否可添加	添加
copyable	Boolean	false	是否可复制	复制
addButtonText	String	''	添加按钮文字	按钮
template	Object	{}	新增项模板	模板
showIndexes	Boolean	false	是否显示索引指示器	索引
itemKey	String	'_faKey'	每项的内部稳定键字段名	自定义数据键
disabled	Boolean	false	是否禁用	禁用
customClass	String	''	自定义类名	样式覆盖
customStyle	String | Object	''	自定义样式	动态样式覆盖

---

事件

事件名称	触发时机	回调参数	参数说明
input	数据变化时触发	(items: Array)	用于 Vue 2 v-model 的当前数组
change	数据变化时触发	(items: Array)	当前数组
add	添加项时触发	({ item, index, items })	新增项信息
remove	删除项时触发	({ item, index, items })	删除项信息

---

插槽

插槽名称	说明
default	每一项内容
title	自定义标题
add-btn	自定义添加按钮
actions	自定义行操作按钮

---

主题说明

• 添加按钮使用 xtf-button 组件
• 复制/删除按钮使用 xtf-button 组件
• 标题使用 xtf-text 组件
• 通过 inject 获取 xtf-form 的配置

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖相关 CSS 变量。