xtf-form-item

组件说明

xtf-form-item 是表单项组件，必须配合 xtf-form 使用。用于包裹表单控件，提供标签、校验、错误提示和联动控制，适用于表单字段布局和校验展示等场景。

---

基础用法

1. 基础用法

通过 label 设置标签，通过 prop 绑定校验字段：

<template>
  <xtf-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="phone">
      <xtf-input v-model="formData.phone" type="number" placeholder="请输入手机号" />
    </xtf-form-item>
  </xtf-form>
</template>

<script>
export default {
  data() {
    return {
      formData: { username: '', phone: '' },
      rules: {
        username: [{ required: true, message: '请输入用户名' }],
        phone: [{ required: true, message: '请输入手机号' }]
      }
    }
  }
}
</script>

2. 帮助文字与额外信息

通过 help 设置帮助文字，通过 extra 设置额外信息：

<template>
  <xtf-form :model="formData" label-width="160">
    <xtf-form-item label="验证码" prop="code" help="请查看手机短信获取验证码">
      <xtf-input v-model="formData.code" placeholder="请输入验证码" />
    </xtf-form-item>
    <xtf-form-item label="金额" prop="amount" extra="单位：元">
      <xtf-input v-model="formData.amount" type="digit" placeholder="请输入金额" />
    </xtf-form-item>
  </xtf-form>
</template>

<script>
export default {
  data() {
    return {
      formData: { code: '', amount: '' }
    }
  }
}
</script>

3. 自定义标签与校验状态

默认插槽可接收校验状态和手动触发函数，命名插槽可替换标签、额外信息与帮助文本：

<template>
  <xtf-form :model="model" :rules="rules">
    <xtf-form-item prop="email" feedback @validate-status-change="onStatus">
      <template #label><xtf-text text="邮箱" bold /></template>
      <template #extra><xtf-text text="必填" color="danger" /></template>
      <template #default="{ status, triggerValidate }">
        <xtf-input
          v-model="model.email"
          placeholder="name@example.com"
          @blur="triggerValidate('blur')"
        />
      </template>
      <template #help><xtf-text text="请输入常用邮箱" color="secondary" /></template>
    </xtf-form-item>
  </xtf-form>
</template>

<script>
export default {
  data() {
    return {
      model: { email: '' },
      rules: { email: [{ required: true, message: '请输入邮箱', trigger: 'blur' }] }
    }
  },
  methods: {
    onStatus(payload) {
      console.log(payload)
    }
  }
}
</script>

---

全部属性

属性	类型	默认值	作用描述	适用范围
label	String	''	标签文字	标签
prop	String	''	字段名	数据绑定
required	Boolean	false	是否必填	必填
help	String	''	帮助文字	帮助
extra	String	''	额外信息	额外
error	String	''	手动错误信息	错误
rules	Array	[]	校验规则	校验
layout	String	''	布局方式	布局
labelWidth	String | Number	''	标签宽度	标签
size	String	''	尺寸	尺寸
requiredMark	String	''	必填标记位置	必填标记
feedback	Boolean	false	是否显示校验反馈图标	反馈
validateTrigger	String | Array	''	校验触发时机	触发时机
linkage	String	''	联动规则名	联动
dependencies	String | Array	''	依赖字段	依赖
visibleWhen / disabledWhen	Function | Object | Array | String | Number | Boolean	undefined	联动显示/禁用条件；函数签名 (value, model, dependencies) => Boolean	联动控制
customClass	String	''	自定义类名	样式覆盖
customStyle	String | Object	''	自定义样式	动态样式覆盖

---

事件

事件名称	触发时机	回调参数	参数说明
validate-status-change	校验状态变化时触发	({ prop, status, message })	字段路径、状态和校验提示

---

插槽

插槽名称	说明
default	表单控件
label	自定义标签
extra	自定义额外信息
help	自定义帮助文字

默认插槽参数为 { status, message, linkageState, disabled, triggerValidate, clearValidate }，第三个示例展示了真实用法。

---

主题说明

• 必填标记使用 danger 主题色
• 错误信息使用 danger 主题色
• 校验反馈图标使用 xtf-icon 组件
• 通过 inject 获取 xtf-form 的配置

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