表单

TuiForm 提供了数据收集、校验和提交的完整解决方案。 它底层集成了 async-validator 库，支持强大且灵活的异步验证规则。

基础用法

TuiForm 组件最核心的功能是管理数据模型 (model) 和验证规则 (rules)。 在 TuiFormItem 中通过 prop 属性绑定对应的数据字段，即可自动关联验证逻辑。

<script setup>
import { reactive, ref } from 'vue';

const formRef = ref(null);

const form = reactive({
  name: '',
  type: '',
  desc: ''
});

const rules = reactive({
  name: [
    { required: true, message: '请输入活动名称', trigger: 'blur' },
    { min: 3, max: 20, message: '长度在 3 到 20 个字符', trigger: 'blur' }
  ],
  type: [
    { required: true, message: '请选择活动类型', trigger: 'change' }
  ]
});

const onSubmit = async () => {
  try {
    const valid = await formRef.value.validate();
    if (valid) {
      console.log('提交成功:', form);
    }
  } catch (error) {
    console.log('验证失败:', error);
  }
};

const onReset = () => {
  formRef.value.resetFields();
};
</script>

<template>
  <TuiForm ref="formRef" :model="form" :rules="rules" labelWidth="120px">
    <TuiFormItem label="活动名称" prop="name">
      <TuiInput v-model="form.name" placeholder="请输入名称" />
    </TuiFormItem>
    
    <TuiFormItem label="活动类型" prop="type">
      <TuiSelect v-model="form.type" :options="[{label:'线上',value:'online'}]" />
    </TuiFormItem>
    
    <TuiFormItem label="备注" prop="desc">
      <TuiInput type="textarea" v-model="form.desc" />
    </TuiFormItem>

    <TuiFormItem>
      <TuiButton type="primary" @click="onSubmit">提交</TuiButton>
      <TuiButton @click="onReset">重置</TuiButton>
    </TuiFormItem>
  </TuiForm>
</template>

布局与对齐

标签对齐 (Label Position)

通过 labelPosition 属性可以控制标签的位置：

• right (默认): 右对齐。
• left: 左对齐。
• top: 顶部对齐（标签位于输入框上方）。

<TuiForm labelPosition="top" :model="form">...</TuiForm>

行内表单 (Inline)

设置 inline 为 true，表单项将水平排列。常用于顶部搜索栏。

<TuiForm inline :model="queryForm">
  <TuiFormItem label="用户名">
    <TuiInput v-model="queryForm.user" />
  </TuiFormItem>
  <TuiFormItem>
    <TuiButton type="primary">查询</TuiButton>
  </TuiFormItem>
</TuiForm>

栅格布局 (Grid Layout)

TuiForm 可以完美配合 TuiRow 和 TuiCol 实现复杂的行列布局。

<TuiForm :model="form">
  <TuiRow :gutter="20">
    <TuiCol :span="12">
      <TuiFormItem label="开始时间" prop="startTime">...</TuiFormItem>
    </TuiCol>
    <TuiCol :span="12">
      <TuiFormItem label="结束时间" prop="endTime">...</TuiFormItem>
    </TuiCol>
  </TuiRow>
</TuiForm>

全局控制

TuiForm 提供了一系列属性用于统一下发配置，减少重复代码：

• size: 统一控制内部支持 size 属性的组件尺寸 (large, default, small)。
• disabled: 全局禁用表单内的所有组件。
• labelWidth: 统一设置标签宽度。
• labelSuffix: 统一设置标签后缀（如 : 或 -）。
• asteriskPosition: 必填星号的位置 (left, right)。

表单项配置

除了继承 Form 的全局配置外，TuiFormItem 也支持单独配置：

• contentAlign: 控制内容区域的对齐方式 (left, center, right)。这在处理按钮组居右显示的场景非常有用。

<TuiFormItem contentAlign="right">
  <TuiButton type="primary" @click="submit">Submit</TuiButton>
  <TuiButton @click="cancel">Cancel</TuiButton>
</TuiFormItem>

API 参考

TuiForm Props

属性名	类型	默认值	说明
model	Object	{}	核心数据对象。表单数据源。
rules	Object	{}	验证规则对象。基于 async-validator。
inline	Boolean	false	是否为行内表单模式。
labelPosition	String	'right'	标签对齐方式。可选：left, right, top。
labelWidth	String/Number	150	标签宽度。
labelSuffix	String	':'	标签后缀字符。
labelHide	Boolean	false	是否隐藏所有标签。
asteriskHide	Boolean	false	是否隐藏必填星号。
asteriskPosition	String	'left'	星号位置。可选：left, right。
showMessage	Boolean	true	是否显示校验错误信息。
inlineMessage	Boolean	false	是否以行内形式显示校验信息。
size	String	'default'	全局尺寸。可选：large, default, small。
disabled	Boolean	false	全局禁用表单。
validateOnRuleChange	Boolean	true	是否在 rules 属性改变后立即触发一次验证。
scrollToError	Boolean	false	验证失败时是否滚动到第一个错误项。
scrollIntoViewOptions	Object/Boolean	true	滚动配置（同原生 scrollIntoView 参数）。

TuiForm Methods (Expose)

方法名	说明	参数
validate	对整个表单进行校验。返回 Promise。	(callback: Function)
validateField	校验部分字段。	`(props: String
resetFields	重置表单字段到初始值，并移除校验结果。	-
clearValidate	清除校验信息（不重置值）。	`(props: String
scrollToField	滚动到指定字段。	(prop: String)

TuiForm Emits

事件名	说明	回调参数
validate	任一表单项被校验后触发。	(prop: String, isValid: Boolean, message: String)

TuiFormItem Props

属性名	类型	默认值	说明
prop	String/Array	-	对应 model 的键名。用于验证和重置。
label	String	-	标签文本。
required	Boolean	false	是否必填（如不设置，则依据 rules 自动生成）。
error	String	-	手动设置表单域的错误信息。
validateStatus	String	-	手动设置校验状态。可选：error, validating, success。
for	String	-	指定原生 label 的 for 属性。
contentAlign	String	null	内容区对齐方式。可选：left, center, right。

TuiFormItem Methods (Expose)

方法名	说明
resetField	重置当前字段。
clearValidate	清除当前字段的校验信息。
validateMessage	当前的校验错误信息。
validateState	当前的校验状态。