Nuxt UI v3-alpha 已发布！

试用
组件

FormGroup

GitHub
显示表单元素的标签和附加信息。

用法

在 输入框、文本域、选择器 或 选择菜单 组件周围使用 FormGroup 组件，并提供一个 label 属性。该 <label> 将自动与表单元素相关联，以便在单击时获得焦点。

<template>
  <UFormGroup label="Email">
    <UInput placeholder="[email protected]" icon="i-heroicons-envelope" />
  </UFormGroup>
</template>

必填项

使用 required 属性指示表单元素为必填项。

<template>
  <UFormGroup label="Email" required>
    <UInput placeholder="[email protected]" icon="i-heroicons-envelope" />
  </UFormGroup>
</template>

描述

使用 description 属性在标签下方显示描述。

我们只会将它用于垃圾邮件。

<template>
  <UFormGroup label="Email" description="We'll only use this for spam.">
    <UInput placeholder="[email protected]" icon="i-heroicons-envelope" />
  </UFormGroup>
</template>

提示

使用 hint 属性在表单元素上方显示提示。

可选
<template>
  <UFormGroup label="Email" hint="Optional">
    <UInput placeholder="[email protected]" icon="i-heroicons-envelope" />
  </UFormGroup>
</template>

帮助

使用 help 属性在表单元素下方显示帮助信息。

我们绝不会与任何人分享您的电子邮件。

<template>
  <UFormGroup
    label="Email"
    help="We will never share your email with anyone else."
  >
    <UInput placeholder="[email protected]" icon="i-heroicons-envelope" />
  </UFormGroup>
</template>

错误

使用 error 属性在表单元素下方显示错误信息。

当与 help 属性一起使用时，error 属性将优先显示。

您必须输入电子邮件

<template>
  <UFormGroup v-slot="{ error }" label="Email" :error="!email && 'You must enter an email'" help="This is a nice email!">
    <UInput v-model="email" type="email" placeholder="Enter email" :trailing-icon="error ? 'i-heroicons-exclamation-triangle-20-solid' : undefined" />
  </UFormGroup>
</template>

<script setup lang="ts">
const email = ref('')
</script>
error 属性会自动将表单元素的 color 属性设置为 red。

您也可以使用 error 属性作为布尔值来标记表单元素为无效。

<template>
  <UFormGroup label="Email" error>
    <UInput placeholder="[email protected]" />
  </UFormGroup>
</template>
了解有关 Form 组件中表单验证的更多信息。

尺寸

使用 size 属性更改标签和表单元素的尺寸。

可选

我们只会将它用于垃圾邮件。

我们绝不会与任何人分享您的电子邮件。

<template>
  <UFormGroup
    size="xl"
    label="Email"
    hint="Optional"
    description="We'll only use this for spam."
    help="We will never share your email with anyone else."
  >
    <UInput placeholder="[email protected]" icon="i-heroicons-envelope" />
  </UFormGroup>
</template>
这将仅适用于支持 size 属性的表单元素。

提前验证

默认情况下，验证仅在初始 blur 事件后触发。这是为了防止在用户键入时验证表单。您可以通过将 eager-validation 属性设置为 true 来覆盖此行为。

<template>
  <UForm :schema="schema" :state="state" class="space-y-4">
    <UFormGroup label="Username" name="username" eager-validation>
      <UInput v-model="state.username" placeholder="Choose Username" />
    </UFormGroup>
  </UForm>
</template>

<script setup lang="ts">
import { z } from 'zod'

const schema = z.object({
  username: z.string().min(10, 'Must be at least 10 characters')
})

const state = reactive({
  username: undefined
})
</script>

插槽

label

使用 #label 插槽设置标签的自定义内容。

<template>
  <UFormGroup>
    <template #label>
      <UAvatar
        src="https://avatars.githubusercontent.com/u/739984?v=4"
        size="3xs"
      />
    </template>
    <template #default>
      <UInput model-value="benjamincanac" placeholder="[email protected]" />
    </template>
  </UFormGroup>
</template>

description

使用 #description 插槽设置描述的自定义内容。

仅写入有效的电子邮件地址 

<template>
  <UFormGroup label="Email">
    <template #description>
      Write only valid email address
      <UIcon name="i-heroicons-information-circle" />
    </template>
    <template #default>
      <UInput model-value="benjamincanac" placeholder="[email protected]" />
    </template>
  </UFormGroup>
</template>

hint

使用 #hint 插槽设置提示的自定义内容。

<template>
  <UFormGroup label="Step 1">
    <template #hint>
      <UIcon name="i-heroicons-arrow-right-20-solid" />
    </template>
    <template #default>
      <UInput model-value="benjamincanac" placeholder="[email protected]" />
    </template>
  </UFormGroup>
</template>

help

使用 #help 插槽设置帮助的自定义内容。

以下是一些示例 

<template>
  <UFormGroup label="Email">
    <template #help>
      Here are some examples <UIcon name="i-heroicons-information-circle" />
    </template>
    <template #default>
      <UInput model-value="benjamincanac" placeholder="[email protected]" />
    </template>
  </UFormGroup>
</template>

error

使用 #error 插槽设置错误的自定义内容。

您必须输入电子邮件

<template>
  <UFormGroup label="Email" :error="!email && 'You must enter an email'" help="This is a nice email!">
    <template #default="{ error }">
      <UInput v-model="email" type="email" placeholder="Enter email" :trailing-icon="error ? 'i-heroicons-exclamation-triangle-20-solid' : undefined" />
    </template>

    <template #error="{ error }">
      <span :class="[error ? 'text-red-500 dark:text-red-400' : 'text-primary-500 dark:text-primary-400']">
        {{ error ? error : 'Your email is valid' }}
      </span>
    </template>
  </UFormGroup>
</template>

<script setup lang="ts">
const email = ref('')
</script>

属性

name
string
null
size
FormGroupSize
null
"md""2xs""xs""sm""lg""xl"
label
string
null
ui
{ wrapper?: string; inner?: string; label?: DeepPartial<{ wrapper: string; base: string; required: string; }, any>; size?: DeepPartial<{ '2xs': string; xs: string; sm: string; md: string; lg: string; xl: string; }, any>; ... 5 more ...; default?: DeepPartial<...>; } & { ...; } & { ...; }
{}
error
string | boolean
null
help
string
null
description
string
null
hint
string
null
required
boolean
false
eagerValidation
boolean
false

配置

{
  wrapper: '',
  inner: '',
  label: {
    wrapper: 'flex content-center items-center justify-between',
    base: 'block font-medium text-gray-700 dark:text-gray-200',
    required: "after:content-['*'] after:ms-0.5 after:text-red-500 dark:after:text-red-400"
  },
  size: {
    '2xs': 'text-xs',
    xs: 'text-xs',
    sm: 'text-sm',
    md: 'text-sm',
    lg: 'text-sm',
    xl: 'text-base'
  },
  container: 'mt-1 relative',
  description: 'text-gray-500 dark:text-gray-400',
  hint: 'text-gray-500 dark:text-gray-400',
  help: 'mt-2 text-gray-500 dark:text-gray-400',
  error: 'mt-2 text-red-500 dark:text-red-400',
  default: {
    size: 'sm'
  }
}

表单

收集和验证表单数据。

水平导航

显示水平链接列表。