N-UI

Appearance

Form 表单 ​

由输入框、选择器、单选框、多选框等控件组成，用以收集、校验、提交数据。

基础用法 ​

最基础的表单包括各种输入表单项，比如 input、select、radio、checkbox 等。

vue
<template>
  <NForm :model="form">
    <NFormItem label="姓名" prop="name">
      <NInput v-model="form.name" placeholder="请输入姓名" />
    </NFormItem>
    <NFormItem label="邮箱" prop="email">
      <NInput v-model="form.email" placeholder="请输入邮箱" />
    </NFormItem>
  </NForm>
</template>

<script setup>
import { ref } from 'vue'
const form = ref({
  name: '',
  email: '',
})
</script>

表单校验 ​

通过 rules 属性传入校验规则，对表单进行校验。

vue
<template>
  <NForm :model="form" :rules="rules" ref="formRef">
    <NFormItem label="姓名" prop="name">
      <NInput v-model="form.name" placeholder="请输入姓名" />
    </NFormItem>
    <NFormItem label="邮箱" prop="email">
      <NInput v-model="form.email" placeholder="请输入邮箱" />
    </NFormItem>
    <NFormItem>
      <NButton type="primary" @click="handleSubmit">提交</NButton>
      <NButton @click="handleReset">重置</NButton>
    </NFormItem>
  </NForm>
</template>

<script setup>
import { ref } from 'vue'
const formRef = ref(null)
const form = ref({
  name: '',
  email: '',
})
const rules = {
  name: [
    { required: true, message: '请输入姓名', trigger: 'blur' },
    { min: 2, max: 10, message: '长度在 2 到 10 个字符', trigger: 'blur' },
  ],
  email: [
    { required: true, message: '请输入邮箱', trigger: 'blur' },
    { type: 'email', message: '请输入正确的邮箱地址', trigger: 'blur' },
  ],
}

const handleSubmit = async () => {
  const valid = await formRef.value?.validate()
  if (valid) {
    console.log('提交成功')
  }
}

const handleReset = () => {
  formRef.value?.resetFields()
}
</script>

行内表单 ​

设置 inline 属性可以使表单域在一行内显示。

vue
<template>
  <NForm :model="form" inline>
    <NFormItem label="姓名" prop="name">
      <NInput v-model="form.name" placeholder="请输入姓名" />
    </NFormItem>
    <NFormItem label="邮箱" prop="email">
      <NInput v-model="form.email" placeholder="请输入邮箱" />
    </NFormItem>
    <NFormItem>
      <NButton type="primary">查询</NButton>
    </NFormItem>
  </NForm>
</template>

<script setup>
import { ref } from 'vue'
const form = ref({
  name: '',
  email: '',
})
</script>

对齐方式 ​

使用 label-position 属性来设置标签的位置。

vue
<template>
  <div style="margin-bottom: 20px;">
    <NRadioGroup v-model="labelPosition">
      <NRadio value="left">左对齐</NRadio>
      <NRadio value="right">右对齐</NRadio>
      <NRadio value="top">顶部对齐</NRadio>
    </NRadioGroup>
  </div>
  <NForm :model="form" :labelPosition="labelPosition">
    <NFormItem label="姓名" prop="name">
      <NInput v-model="form.name" placeholder="请输入姓名" />
    </NFormItem>
    <NFormItem label="邮箱" prop="email">
      <NInput v-model="form.email" placeholder="请输入邮箱" />
    </NFormItem>
  </NForm>
</template>

<script setup>
import { ref } from 'vue'
const labelPosition = ref('right')
const form = ref({
  name: '',
  email: '',
})
</script>

标签宽度 ​

使用 label-width 属性来设置标签的宽度。

vue
<template>
  <NForm :model="form" labelWidth="120px">
    <NFormItem label="姓名" prop="name">
      <NInput v-model="form.name" placeholder="请输入姓名" />
    </NFormItem>
    <NFormItem label="邮箱地址" prop="email">
      <NInput v-model="form.email" placeholder="请输入邮箱" />
    </NFormItem>
  </NForm>
</template>

<script setup>
import { ref } from 'vue'
const form = ref({
  name: '',
  email: '',
})
</script>

表单项尺寸 ​

使用 size 属性来设置表单项的大小。

vue
<template>
  <div style="margin-bottom: 20px;">
    <NRadioGroup v-model="size">
      <NRadio value="large">大型</NRadio>
      <NRadio value="default">默认</NRadio>
      <NRadio value="small">小型</NRadio>
    </NRadioGroup>
  </div>
  <NForm :model="form" :size="size">
    <NFormItem label="姓名" prop="name">
      <NInput v-model="form.name" placeholder="请输入姓名" />
    </NFormItem>
    <NFormItem label="邮箱" prop="email">
      <NInput v-model="form.email" placeholder="请输入邮箱" />
    </NFormItem>
  </NForm>
</template>

<script setup>
import { ref } from 'vue'
const size = ref('default')
const form = ref({
  name: '',
  email: '',
})
</script>

禁用表单 ​

设置 disabled 属性来禁用整个表单。

vue
<template>
  <NForm :model="form" disabled>
    <NFormItem label="姓名" prop="name">
      <NInput v-model="form.name" placeholder="请输入姓名" />
    </NFormItem>
    <NFormItem label="邮箱" prop="email">
      <NInput v-model="form.email" placeholder="请输入邮箱" />
    </NFormItem>
  </NForm>
</template>

<script setup>
import { ref } from 'vue'
const form = ref({
  name: '张三',
  email: 'zhangsan@example.com',
})
</script>

必填字段 ​

设置 required 属性来标记必填字段。

vue
<template>
  <NForm :model="form">
    <NFormItem label="姓名" prop="name" required>
      <NInput v-model="form.name" placeholder="请输入姓名" />
    </NFormItem>
    <NFormItem label="邮箱" prop="email" required>
      <NInput v-model="form.email" placeholder="请输入邮箱" />
    </NFormItem>
  </NForm>
</template>

<script setup>
import { ref } from 'vue'
const form = ref({
  name: '',
  email: '',
})
</script>

自定义校验信息 ​

使用 error 属性来显示自定义校验信息。

vue
<template>
  <NForm :model="form">
    <NFormItem label="姓名" prop="name" :error="nameError">
      <NInput v-model="form.name" placeholder="请输入姓名" @blur="validateName" />
    </NFormItem>
  </NForm>
</template>

<script setup>
import { ref } from 'vue'
const form = ref({
  name: '',
})
const nameError = ref('')

const validateName = () => {
  if (!form.value.name) {
    nameError.value = '请输入姓名'
  } else if (form.value.name.length < 2) {
    nameError.value = '姓名长度不能小于2'
  } else {
    nameError.value = ''
  }
}
</script>

Form API ​

Props ​

属性说明类型默认值
model表单数据对象Record<string, any>—
rules表单验证规则Record<string, any>—
labelPosition表单域标签的位置'left' | 'right' | 'top''right'
labelWidth表单域标签的宽度string | number—
inline行内表单模式booleanfalse
disabled是否禁用该表单内的所有组件booleanfalse
size用于控制该表单内组件的尺寸'large' | 'default' | 'small''default'

Methods ​

方法名说明类型
validate对整个表单进行校验(callback?: (valid: boolean) => void) => Promise<boolean>
resetFields重置该表单项，将其值重置为初始值，并移除校验结果(props?: string[]) => void
clearValidate移除表单项的校验结果(props?: string[]) => void

Events ​

事件名说明类型
validate任一表单项被校验后触发(prop: string, valid: boolean) => void

FormItem API ​

Props ​

属性说明类型默认值
label标签文本string—
labelWidth表单域标签的宽度string | number—
prop表单域 model 字段string—
required是否必填booleanfalse
rules表单验证规则any—
error表单域验证错误信息string—
showMessage是否显示校验错误信息booleantrue
size用于控制该表单域下组件的尺寸'large' | 'default' | 'small'—

Slots ​

插槽名说明
default表单域内容
label标签内容
error自定义错误信息