FormField 表单字段

为控件配上标签、说明与错误信息。

昵称必填

公开显示在个人页

<script setup lang="ts">
  import { ref } from 'vue'
  import { FormField, Input } from '@hina-ui/vue'

  const name = ref('')
</script>

<template>
  <FormField label="昵称" description="公开显示在个人页" required class="w-80">
    <Input v-model="name" placeholder="星见书音" />
  </FormField>
</template>

vue

用法

import { FormField } from '@hina-ui/vue'

表单字段把一个控件与它的标签、说明和错误信息组成一行。放在 Form 里时，通过 name 取得该字段的错误；单独使用时，通过 error 直接传入错误文字。库里的控件放进字段后会自动关联：标签指向控件，说明与错误信息通过 aria-describedby 关联到控件，出现错误时控件进入无效状态，字段的 disabled 也会传给控件。

昵称

<script setup lang="ts">
  import { ref } from 'vue'
  import { FormField, Input } from '@hina-ui/vue'

  const name = ref('')
</script>

<template>
  <FormField label="昵称" class="w-80">
    <Input v-model="name" />
  </FormField>
</template>

vue

示例

横向布局

orientation="horizontal" 将标签放在起始侧，控件放在末端侧。label-width 接受 CSS 长度或以像素为单位的数字，默认 10rem。通过 FormLayout 可为多个字段统一标签列宽。横向模式始终保持两列。

显示名称

显示在你的公开个人资料中。

<script setup lang="ts">
  import { ref } from 'vue'
  import { FormField, Input } from '@hina-ui/vue'
  const name = ref('Hina')
</script>
<template>
  <FormField
    label="显示名称"
    orientation="horizontal"
    label-width="8rem"
    description="显示在你的公开个人资料中。"
    class="w-full"
  >
    <Input v-model="name" />
  </FormField>
</template>

vue

说明位置

description-placement="label" 将说明放在标签下方，阅读顺序也位于控件之前。默认的 control 将说明放在控件下方。错误提示始终留在控件区域。两种位置都支持 description 插槽，并保持与控件的无障碍关联。

显示名称

显示在你的公开个人资料中。

邮箱地址

使用可以接收通知的邮箱地址。

请输入邮箱地址。

<script setup lang="ts">
  import { ref } from 'vue'
  import { FormField, Input, Stack } from '@hina-ui/vue'
  const name = ref('Hina')
  const email = ref('')
</script>
<template>
  <Stack class="w-full">
    <FormField
      label="显示名称"
      orientation="responsive"
      description-placement="label"
      description="显示在你的公开个人资料中。"
    >
      <Input v-model="name" />
    </FormField>
    <FormField
      label="邮箱地址"
      orientation="responsive"
      description-placement="control"
      description="使用可以接收通知的邮箱地址。"
      error="请输入邮箱地址。"
    >
      <Input v-model="email" type="email" />
    </FormField>
  </Stack>
</template>

vue

响应式布局

orientation="responsive" 在字段宽度小于 32rem 时纵向排列，达到 32rem 时切为两列。断点依据字段自身的可用宽度，多列表单也按每个字段的列宽判断。拖动示例容器调整宽度即可观察切换。

显示名称

拖动容器右下角调整宽度；字段宽度小于 32rem 时纵向排列。

<script setup lang="ts">
  import { ref } from 'vue'
  import { FormField, Input, Stack } from '@hina-ui/vue'
  const name = ref('Hina')
</script>
<template>
  <Stack class="w-full max-w-2xl resize-x overflow-auto p-2">
    <FormField
      label="显示名称"
      orientation="responsive"
      description="拖动容器右下角调整宽度；字段宽度小于 32rem 时纵向排列。"
    >
      <Input v-model="name" />
    </FormField>
  </Stack>
</template>

vue

说明文字

description 在控件下方显示一段说明，也可以用同名插槽放入更丰富的内容。

昵称

公开显示在个人页，可以随时修改

简介

不超过 80 个字，支持换行。

<script setup lang="ts">
  import { ref } from 'vue'
  import { FormField, Input, Stack, Textarea } from '@hina-ui/vue'

  const name = ref('')
  const bio = ref('')
</script>

<template>
  <Stack gap="md" align="stretch" class="w-80">
    <FormField label="昵称" description="公开显示在个人页，可以随时修改">
      <Input v-model="name" />
    </FormField>
    <FormField label="简介">
      <Textarea v-model="bio" />
      <template #description>不超过 80 个字，支持换行。</template>
    </FormField>
  </Stack>
</template>

vue

必填标记

required 在标签后显示必填标记，并给辅助技术提供对应的文字。标记只是提示，是否必填由校验规则决定。

邮箱必填

<script setup lang="ts">
  import { ref } from 'vue'
  import { FormField, Input } from '@hina-ui/vue'

  const email = ref('')
</script>

<template>
  <FormField label="邮箱" required class="w-80">
    <Input v-model="email" type="email" />
  </FormField>
</template>

vue

单独使用

不在表单里时，error 直接决定显示的错误文字，适合自行管理校验的场合。

显示错误

邮箱

邮箱格式不正确

<script setup lang="ts">
  import { ref } from 'vue'
  import { FormField, Input, Stack, Switch } from '@hina-ui/vue'

  const email = ref('shion@example')
  const failed = ref(true)
</script>

<template>
  <Stack gap="md" align="stretch" class="w-80">
    <Switch v-model="failed">显示错误</Switch>
    <FormField label="邮箱" :error="failed ? '邮箱格式不正确' : undefined">
      <Input v-model="email" type="email" />
    </FormField>
  </Stack>
</template>

vue

各类控件

单个控件通过标签的 for 关联；单选组、复选框组、滑块、评分与日期输入这类成组的控件则通过 aria-labelledby 关联到标签。

类型

游戏小说漫画

标签

游戏小说漫画

评分

音量

发售日期

年

月

日

<script setup lang="ts">
  import { ref } from 'vue'
  import {
    CheckboxGroup,
    DateField,
    FormField,
    RadioGroup,
    Rating,
    Slider,
    Stack,
  } from '@hina-ui/vue'

  const kinds = [
    { label: '游戏', value: 'game' },
    { label: '小说', value: 'novel' },
    { label: '漫画', value: 'manga' },
  ]
  const kind = ref<string | number | null>('game')
  const tags = ref<Array<string | number>>([])
  const score = ref(4)
  const volume = ref(30)
  const released = ref<string | null>(null)
</script>

<template>
  <Stack gap="md" align="stretch" class="w-80">
    <FormField label="类型">
      <RadioGroup v-model="kind" :options="kinds" orientation="horizontal" />
    </FormField>
    <FormField label="标签">
      <CheckboxGroup v-model="tags" :options="kinds" orientation="horizontal" />
    </FormField>
    <FormField label="评分">
      <Rating v-model="score" />
    </FormField>
    <FormField label="音量">
      <Slider v-model="volume" />
    </FormField>
    <FormField label="发售日期">
      <DateField v-model="released" />
    </FormField>
  </Stack>
</template>

vue

行为

一个字段只放一个控件；控件自带的 id 与 aria-describedby 优先于字段生成的值。
错误信息出现时把下方的内容推开，消失时收回，高度与间距连续变化。
字段失去焦点时通知所在的表单，供 blur 校验时机使用。

API

Props

属性	类型	默认值	说明
`name`	`string`	—	字段名，用于从表单取得错误
`label`	`string`	—	标签文字
`description`	`string`	—	说明文字
`error`	`string`	—	直接指定的错误文字
`required`	`boolean`	`false`	是否显示必填标记
`orientation`	`'vertical' \| 'horizontal' \| 'responsive'`	`'vertical'`	标签与控件的布局，继承 FormLayout 配置
`descriptionPlacement`	`'label' \| 'control'`	`'control'`	说明位于标签或控件下方，继承 FormLayout 配置
`labelWidth`	`string \| number`	`'10rem'`	标签列宽：CSS 长度或像素数，继承 FormLayout 配置
`disabled`	`boolean`	`false`	是否禁用控件
`class`	`string`	—	追加至根元素的类名

插槽

插槽	说明
default	控件
`label`	标签内容
`description`	说明内容