xtf-form

组件说明

xtf-form 是表单组件，用于管理表单数据、校验规则和提交逻辑。配合 xtf-form-item 使用，支持字段校验、错误汇总、联动控制、标签布局和滚动定位，适用于注册表单、信息编辑和设置页面等场景。

基础用法

1. 基础表单

通过 model 绑定表单数据，通过 rules 设置校验规则：

vue

<template>
  <xtf-form ref="form" :model="formData" :rules="rules" label-width="160">
    <xtf-form-item label="用户名" prop="username">
      <xtf-input v-model="formData.username" placeholder="请输入用户名" />
    </xtf-form-item>
    <xtf-form-item label="密码" prop="password">
      <xtf-input v-model="formData.password" type="password" placeholder="请输入密码" />
    </xtf-form-item>
    <xtf-form-item>
      <xtf-button label="提交" block @click="handleSubmit" />
    </xtf-form-item>
  </xtf-form>
</template>

<script>
export default {
  data() {
    return {
      formData: {
        username: '',
        password: ''
      },
      rules: {
        username: [{ required: true, message: '请输入用户名' }],
        password: [
          { required: true, message: '请输入密码' },
          { min: 6, message: '密码至少6位' }
        ]
      }
    }
  },
  methods: {
    handleSubmit() {
      this.$refs.form.validate((valid) => {
        if (valid) {
          console.log('提交成功', this.formData)
        }
      })
    }
  }
}
</script>

2. 错误汇总

通过 showErrorSummary 在表单顶部显示错误汇总：

vue

<template>
  <xtf-form ref="form" :model="formData" :rules="rules" show-error-summary label-width="160">
    <xtf-form-item label="姓名" prop="name">
      <xtf-input v-model="formData.name" placeholder="请输入姓名" />
    </xtf-form-item>
    <xtf-form-item label="手机号" prop="phone">
      <xtf-input v-model="formData.phone" type="number" placeholder="请输入手机号" />
    </xtf-form-item>
  </xtf-form>
</template>

3. 表单重置

通过 reset 方法重置表单：

vue

<template>
  <view>
    <xtf-form ref="form" :model="formData" :rules="rules" label-width="160">
      <xtf-form-item label="邮箱" prop="email">
        <xtf-input v-model="formData.email" placeholder="请输入邮箱" />
      </xtf-form-item>
    </xtf-form>
    <xtf-button-group :gap="12" style="margin-top: 16rpx">
      <xtf-button label="提交" @click="handleSubmit" />
      <xtf-button label="重置" type="light" @click="handleReset" />
    </xtf-button-group>
  </view>
</template>

<script>
export default {
  data() {
    return {
      formData: { email: '' },
      rules: { email: [{ required: true, message: '请输入邮箱' }] }
    }
  },
  methods: {
    handleSubmit() {
      this.$refs.form.validate((valid) => {
        if (valid) console.log('提交')
      })
    },
    handleReset() {
      this.$refs.form.reset()
    }
  }
}
</script>

全部属性

属性	类型	默认值	作用描述	适用范围
`model`	`Object`	`{}`	表单数据对象	数据绑定
`rules`	`Object`	`{}`	校验规则	校验
`labelWidth`	`String \| Number`	`168`	标签宽度（rpx）	标签
`labelPosition`	`String`	`'vertical'`	标签位置：`'vertical'` / `'horizontal'`	标签布局
`size`	`String`	`''`	统一尺寸	尺寸
`disabled`	`Boolean`	`false`	是否全局禁用	禁用
`readonly`	`Boolean`	`false`	是否全局只读	只读
`loading`	`Boolean`	`false`	是否加载中	加载
`validateTrigger`	`String \| Array`	`'change'`	校验触发时机	触发时机
`requiredMark`	`String`	`'start'`	必填标记位置	必填标记
`feedback`	`Boolean`	`false`	是否显示校验反馈图标	反馈
`scrollToError`	`Boolean \| Object`	`true`	是否滚动到错误项	滚动定位
`linkage`	`Array`	`[]`	联动规则	联动
`showErrorSummary`	`Boolean`	`false`	是否显示错误汇总	错误汇总
`errorSummaryTitle`	`String`	`''`	错误汇总标题	错误汇总
`customClass`	`String`	`''`	自定义类名	样式覆盖
`customStyle`	`String \| Object`	`''`	自定义样式	动态样式覆盖

事件

事件名称	触发时机	回调参数	参数说明
`validate`	执行字段校验后触发	`({ valid, errors })`	是否通过与 `{ prop, message, field }` 错误数组
`reset`	调用 `reset` 后触发	`(props: String[])`	被重置的字段路径
`submit`	调用 `submit` 后触发	`({ valid, model, errors? })`	提交结果、模型和失败时的错误数组
`validate-status-change`	子项校验状态变化时触发	`({ prop, status, message })`	字段路径、`success`/`error` 状态和提示

事件使用示例

vue

<template>
  <xtf-form
    ref="form"
    :model="model"
    :rules="rules"
    @validate="onValidate"
    @reset="onReset"
    @submit="onSubmit"
    @validate-status-change="onStatus"
  >
    <xtf-form-item label="名称" prop="name"><xtf-input v-model="model.name" /></xtf-form-item>
    <xtf-button label="提交" @click="$refs.form.submit()" />
  </xtf-form>
</template>

<script>
export default {
  data() {
    return { model: { name: '' }, rules: { name: [{ required: true, message: '请输入名称' }] } }
  },
  methods: {
    onValidate(payload) {
      console.log('validate', payload)
    },
    onReset(props) {
      console.log('reset', props)
    },
    onSubmit(payload) {
      console.log('submit', payload)
    },
    onStatus(payload) {
      console.log('status', payload)
    }
  }
}
</script>

方法

方法名	参数	返回值	说明
`validate`	`(callback?)`	`Promise`	校验整个表单
`validateField`	`(fields?, trigger?)`	`Promise<Boolean>`	校验指定字段；失败时 reject 错误数组
`reset`	`(fields?)`	-	重置字段初始值
`clearValidate`	`(props?)`	-	清除校验结果
`getErrors`	-	`Array`	获取最近一次校验错误
`addField` / `removeField`	`(path, value?, index?)` / `(path, index)`	`Array` / `Any`	增删模型中的数组字段

主题说明

错误汇总使用卡片样式
错误项使用主题色 danger 标记
表单项使用 xtf-form-item 组件
通过 provide/inject 向子组件注入表单配置

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

xtf-form ​

组件说明 ​

基础用法 ​

1. 基础表单 ​

2. 错误汇总 ​

3. 表单重置 ​

全部属性 ​

事件 ​

事件使用示例 ​

方法 ​

主题说明 ​