FormField

一个用于表单元素的包装器，提供验证和错误处理。

用法

使用 FormField 包装任何表单组件。在 Form 中使用时，它提供验证和错误处理。

描述

使用 description prop 在标签下方提供额外信息。

description

We'll never share your email with anyone else.

<template>
  <UFormField label="Email" description="We'll never share your email with anyone else.">
    <UInput placeholder="Enter your email" class="w-full" />
  </UFormField>
</template>

提示 (Hint)

使用 hint prop 在标签旁边显示提示消息。

hint

EmailOptional

<template>
  <UFormField label="Email" hint="Optional">
    <UInput placeholder="Enter your email" />
  </UFormField>
</template>

帮助 (Help)

使用 help prop 在表单控件下方显示帮助消息。

help

Please enter a valid email address.

<template>
  <UFormField label="Email" help="Please enter a valid email address.">
    <UInput placeholder="Enter your email" class="w-full" />
  </UFormField>
</template>

错误 (Error)

使用 error prop 在表单控件下方显示错误消息。当与 help prop 一起使用时，error prop 具有优先权。

在 Form 内部使用时，当发生验证错误时，此属性会自动设置。

error

Please enter a valid email address.

<template>
  <UFormField label="Email" error="Please enter a valid email address.">
    <UInput placeholder="Enter your email" class="w-full" />
  </UFormField>
</template>

这会将表单控件的 color 设置为 error。你可以在 app.config.ts 中全局更改它。

尺寸 (Size)

使用 size prop 更改 FormField 的尺寸，size 会代理到表单控件。

size

EmailOptional

We'll never share your email with anyone else.

Please enter a valid email address.

<template>
  <UFormField
    label="Email"
    description="We'll never share your email with anyone else."
    hint="Optional"
    help="Please enter a valid email address."
    size="xl"
  >
    <UInput placeholder="Enter your email" class="w-full" />
  </UFormField>
</template>

API

Props

Prop	Default	Type
`as`	`'div'`	`any` The element or component this component should render as.
`name`		`string` The name of the FormField. Also used to match form errors.
`errorPattern`		`RegExp` A regular expression to match form error names.
`label`		`string`
`description`		`string`
`help`		`string`
`error`		`string \| false \| true`
`hint`		`string`
`size`	`'md'`	`"md" \| "xs" \| "sm" \| "lg" \| "xl"`
`required`		`boolean`
`eagerValidation`		`boolean` If true, validation on input will be active immediately instead of waiting for a blur event.
`validateOnInputDelay`	`300`	`number` Delay in milliseconds before validating the form on input events.
`ui`		`{ root?: ClassNameValue; wrapper?: ClassNameValue; labelWrapper?: ClassNameValue; label?: ClassNameValue; container?: ClassNameValue; description?: ClassNameValue; error?: ClassNameValue; hint?: ClassNameValue; help?: ClassNameValue; }`

Slots

Slot	Type
`label`	`{ label?: string \| undefined; }`
`hint`	`{ hint?: string \| undefined; }`
`description`	`{ description?: string \| undefined; }`
`help`	`{ help?: string \| undefined; }`
`error`	`{ error?: string \| boolean \| undefined; }`
`default`	`{ error?: string \| boolean \| undefined; }`

Theme

app.config.ts

export default defineAppConfig({
  ui: {
    formField: {
      slots: {
        root: '',
        wrapper: '',
        labelWrapper: 'flex content-center items-center justify-between',
        label: 'block font-medium text-default',
        container: 'mt-1 relative',
        description: 'text-muted',
        error: 'mt-2 text-error',
        hint: 'text-muted',
        help: 'mt-2 text-muted'
      },
      variants: {
        size: {
          xs: {
            root: 'text-xs'
          },
          sm: {
            root: 'text-xs'
          },
          md: {
            root: 'text-sm'
          },
          lg: {
            root: 'text-sm'
          },
          xl: {
            root: 'text-base'
          }
        },
        required: {
          true: {
            label: "after:content-['*'] after:ms-0.5 after:text-error"
          }
        }
      },
      defaultVariants: {
        size: 'md'
      }
    }
  }
})

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        formField: {
          slots: {
            root: '',
            wrapper: '',
            labelWrapper: 'flex content-center items-center justify-between',
            label: 'block font-medium text-default',
            container: 'mt-1 relative',
            description: 'text-muted',
            error: 'mt-2 text-error',
            hint: 'text-muted',
            help: 'mt-2 text-muted'
          },
          variants: {
            size: {
              xs: {
                root: 'text-xs'
              },
              sm: {
                root: 'text-xs'
              },
              md: {
                root: 'text-sm'
              },
              lg: {
                root: 'text-sm'
              },
              xl: {
                root: 'text-base'
              }
            },
            required: {
              true: {
                label: "after:content-['*'] after:ms-0.5 after:text-error"
              }
            }
          },
          defaultVariants: {
            size: 'md'
          }
        }
      }
    })
  ]
})

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import uiPro from '@nuxt/ui-pro/vite'

export default defineConfig({
  plugins: [
    vue(),
    uiPro({
      ui: {
        formField: {
          slots: {
            root: '',
            wrapper: '',
            labelWrapper: 'flex content-center items-center justify-between',
            label: 'block font-medium text-default',
            container: 'mt-1 relative',
            description: 'text-muted',
            error: 'mt-2 text-error',
            hint: 'text-muted',
            help: 'mt-2 text-muted'
          },
          variants: {
            size: {
              xs: {
                root: 'text-xs'
              },
              sm: {
                root: 'text-xs'
              },
              md: {
                root: 'text-sm'
              },
              lg: {
                root: 'text-sm'
              },
              xl: {
                root: 'text-base'
              }
            },
            required: {
              true: {
                label: "after:content-['*'] after:ms-0.5 after:text-error"
              }
            }
          },
          defaultVariants: {
            size: 'md'
          }
        }
      }
    })
  ]
})

Form

一个内置验证和提交处理的表单组件。

Icon

一个显示 Iconify 中任何图标的组件。