Form 表单

何时使用

收集、校验并提交一组表单数据时使用。支持嵌套字段路径，如 user.email。

基础校验

姓名

邮箱

<script setup lang="ts">
import { reactive, ref } from 'vue'
import {
  DanButton,
  DanForm,
  DanFormItem,
  DanInput,
  type DanFormInstance,
} from '@dandan-ui/ui'

const formRef = ref<DanFormInstance>()
const model = reactive({
  name: '',
  profile: { email: '' },
})
const rules = {
  name: [{ required: true, message: '请输入姓名', trigger: 'blur' }],
  'profile.email': [{ required: true, message: '请输入邮箱', trigger: 'blur' }],
}

async function onSubmit() {
  const ok = await formRef.value?.validate()
  window.alert(ok ? '校验通过' : '校验失败')
}
</script>

<template>
  <DanForm ref="formRef" :model="model" :rules="rules" label-width="72px">
    <DanFormItem label="姓名" prop="name">
      <DanInput v-model="model.name" placeholder="请输入姓名" clearable />
    </DanFormItem>
    <DanFormItem label="邮箱" prop="profile.email">
      <DanInput v-model="model.profile.email" placeholder="name@example.com" />
    </DanFormItem>
    <DanFormItem>
      <DanButton type="primary" @click="onSubmit">提交</DanButton>
    </DanFormItem>
  </DanForm>
</template>

综合表单

组合输入框、单选、多选、选择器、开关等控件。

姓名

角色

开发设计产品

技能

VueTypeScriptCSS

城市

×

简介

0 / 80

订阅

<script setup lang="ts">
import { reactive, ref } from 'vue'
import {
  DanButton,
  DanCheckbox,
  DanCheckboxGroup,
  DanForm,
  DanFormItem,
  DanInput,
  DanRadio,
  DanRadioGroup,
  DanSelect,
  DanSwitch,
  DanTextarea,
  type DanFormInstance,
} from '@dandan-ui/ui'

const formRef = ref<DanFormInstance>()
const model = reactive({
  name: '',
  role: 'dev',
  skills: ['vue'],
  city: 'shanghai',
  bio: '',
  newsletter: true,
})

const rules = {
  name: [{ required: true, message: '请输入姓名', trigger: 'blur' }],
  city: [{ required: true, message: '请选择城市', trigger: 'change' }],
}

const cityOptions = [
  { label: '上海', value: 'shanghai' },
  { label: '北京', value: 'beijing' },
  { label: '深圳', value: 'shenzhen' },
]

async function onSubmit() {
  const ok = await formRef.value?.validate()
  window.alert(ok ? '校验通过' : '校验失败')
}

function onReset() {
  formRef.value?.resetFields()
}
</script>

<template>
  <DanForm
    ref="formRef"
    :model="model"
    :rules="rules"
    label-width="88px"
    style="max-width: 560px"
  >
    <DanFormItem label="姓名" prop="name">
      <DanInput v-model="model.name" clearable placeholder="请输入姓名" />
    </DanFormItem>
    <DanFormItem label="角色">
      <DanRadioGroup v-model="model.role">
        <DanRadio label="dev">开发</DanRadio>
        <DanRadio label="design">设计</DanRadio>
        <DanRadio label="pm">产品</DanRadio>
      </DanRadioGroup>
    </DanFormItem>
    <DanFormItem label="技能">
      <DanCheckboxGroup v-model="model.skills">
        <DanCheckbox label="vue">Vue</DanCheckbox>
        <DanCheckbox label="ts">TypeScript</DanCheckbox>
        <DanCheckbox label="css">CSS</DanCheckbox>
      </DanCheckboxGroup>
    </DanFormItem>
    <DanFormItem label="城市" prop="city">
      <DanSelect v-model="model.city" :options="cityOptions" clearable />
    </DanFormItem>
    <DanFormItem label="简介">
      <DanTextarea
        v-model="model.bio"
        :rows="3"
        maxlength="80"
        show-word-limit
      />
    </DanFormItem>
    <DanFormItem label="订阅">
      <DanSwitch v-model="model.newsletter" />
    </DanFormItem>
    <DanFormItem>
      <div style="display: flex; gap: 8px">
        <DanButton type="primary" @click="onSubmit">提交</DanButton>
        <DanButton @click="onReset">重置</DanButton>
      </div>
    </DanFormItem>
  </DanForm>
</template>

顶部标签

标题

描述

<script setup lang="ts">
import { reactive } from 'vue'
import { DanForm, DanFormItem, DanInput } from '@dandan-ui/ui'

const model = reactive({
  title: '',
  desc: '',
})
</script>

<template>
  <DanForm :model="model" label-position="top" style="max-width: 420px">
    <DanFormItem label="标题" prop="title" required>
      <DanInput v-model="model.title" placeholder="请输入标题" />
    </DanFormItem>
    <DanFormItem label="描述" prop="desc">
      <DanInput v-model="model.desc" placeholder="请输入描述" />
    </DanFormItem>
  </DanForm>
</template>

API

Form Props

属性	说明	类型	默认值	必填
model	表单数据对象，字段需可响应式	Record<string, unknown>	—	是
rules	校验规则表，key 支持嵌套路径如 user.email	FormRules	{}	否
disabled	禁用整表内可继承的控件	boolean	false	否
size	向下提供的默认尺寸	'small' | 'default' | 'large'	—	否
labelWidth	统一标签宽度，如 '88px'	string	—	否
labelPosition	标签布局	'left' | 'right' | 'top'	'right'	否

FormRules / FormRule

字段	说明	类型
required	是否必填	boolean
message	错误文案	string
trigger	触发时机，如 'blur' / 'change'	string | string[]
min / max	字符串长度或数组长度限制	number
pattern	正则校验	RegExp
type	期望类型	'string' | 'number' | 'boolean' | 'array'
validator	自定义异步/同步校验	(rule, value, callback) => void

Form Expose

通过 ref 调用：

方法	说明	签名
validate	校验全部已注册字段	() => Promise<boolean>
validateField	校验单个字段	(prop: string) => Promise<boolean>
resetFields	恢复各字段初始值并清空校验	() => void
clearValidate	清空校验态；可传字段名或字段名数组	(props?: string | string[]) => void

Form Slots

插槽名	说明
default	放置若干 DanFormItem

FormItem Props

属性	说明	类型	默认值	必填
label	标签文本	string	—	否
prop	对应 model 的字段路径，支持 a.b.c	string	—	校验时必填
required	强制显示必填星号；不传则根据 rules 推断	boolean	—	否
labelWidth	覆盖 Form 的标签宽度	string	—	否

FormItem Slots

插槽名	说明
default	表单控件（Input / Select 等）
label	自定义标签内容

FormItem 行为

• 挂载时记录初始值，供 resetFields 使用。
• 子控件触发 change / blur 时按 rule.trigger 过滤后校验。
• 校验失败时在控件下方显示首条错误信息。

注意事项

• model 请使用 reactive / ref 对象，确保双向绑定生效。
• 嵌套路径如 profile.email 要求 model.profile 事先存在。