CheckboxGroup

CheckboxGroupGitHub
一组复选按钮，用于从列表中选择多个选项。

用法

使用 v-model 指令控制 CheckboxGroup 的值，或者在你不需要控制其状态时，使用 default-value 属性设置其初始值。

<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
const value = ref(['System'])
</script>

<template>
  <UCheckboxGroup v-model="value" :items="items" />
</template>

项

使用 items 属性作为字符串或数字数组

<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
const value = ref(['System'])
</script>

<template>
  <UCheckboxGroup v-model="value" :items="items" />
</template>

您还可以传入一个包含以下属性的对象数组

  • label?: string
  • description?: string
  • value?: string
  • disabled?: boolean
  • class?: any
  • ui?: { item?: ClassNameValue, container?: ClassNameValue, base?: ClassNameValue, 'indicator'?: ClassNameValue, icon?: ClassNameValue wrapper?: ClassNameValue, label?: ClassNameValue, description?: ClassNameValue }

这是第一个选项。

这是第二个选项。

这是第三个选项。

<script setup lang="ts">
import type { CheckboxGroupItem } from '@nuxt/ui'

const items = ref<CheckboxGroupItem[]>([
  {
    label: 'System',
    description: 'This is the first option.',
    value: 'system'
  },
  {
    label: 'Light',
    description: 'This is the second option.',
    value: 'light'
  },
  {
    label: 'Dark',
    description: 'This is the third option.',
    value: 'dark'
  }
])
const value = ref([
  'system'
])
</script>

<template>
  <UCheckboxGroup v-model="value" :items="items" />
</template>
使用对象时，你需要在 v-model 指令或 default-value 属性中引用对象的 value 属性。

值键

你可以通过使用 value-key 属性来更改用于设置值的属性。默认为 value。

这是第一个选项。

这是第二个选项。

这是第三个选项。

<script setup lang="ts">
import type { CheckboxGroupItem } from '@nuxt/ui'

const items = ref<CheckboxGroupItem[]>([
  {
    label: 'System',
    description: 'This is the first option.',
    id: 'system'
  },
  {
    label: 'Light',
    description: 'This is the second option.',
    id: 'light'
  },
  {
    label: 'Dark',
    description: 'This is the third option.',
    id: 'dark'
  }
])
const value = ref([
  'light'
])
</script>

<template>
  <UCheckboxGroup v-model="value" value-key="id" :items="items" />
</template>

图例

使用 legend 属性设置 CheckboxGroup 的图例。

主题
<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <UCheckboxGroup legend="Theme" :default-value="['System']" :items="items" />
</template>

颜色

使用 color 属性更改 CheckboxGroup 的颜色。

<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <UCheckboxGroup color="neutral" :default-value="['System']" :items="items" />
</template>

变体

使用 variant 属性更改 CheckboxGroup 的变体。

<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <UCheckboxGroup color="primary" variant="card" :default-value="['System']" :items="items" />
</template>

尺寸

使用 size 属性更改 CheckboxGroup 的大小。

<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <UCheckboxGroup size="xl" variant="list" :default-value="['System']" :items="items" />
</template>

Orientation

使用 orientation 属性更改 CheckboxGroup 的方向。默认为 vertical。

<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <UCheckboxGroup
    orientation="horizontal"
    variant="list"
    :default-value="['System']"
    :items="items"
  />
</template>

指示器

使用 indicator 属性来改变或隐藏指示器的位置。默认为 start。

<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <UCheckboxGroup indicator="end" variant="card" :default-value="['System']" :items="items" />
</template>

禁用

使用 disabled 属性禁用 CheckboxGroup。

<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <UCheckboxGroup disabled :default-value="['System']" :items="items" />
</template>

API

属性

属性默认值类型
as

'div'

any

此组件应渲染为的元素或组件。

图例

string

valueKey

'value'

string | number

当 items 是对象数组时，选择用作值的字段。

labelKey

'label'

string | number

当 items 是对象数组时，选择用作标签的字段。

descriptionKey

'description'

string | number

当 items 是一个对象数组时，选择要用作描述的字段。

items

CheckboxGroupItem[]

modelValue

any[]

CheckboxGroup 的受控值。可以绑定为 v-model。

defaultValue

any[]

CheckboxGroup 初次渲染时的值。当你不需要控制 CheckboxGroup 的状态时使用。

尺寸

'md'

"xs" | "sm" | "md" | "lg" | "xl"

variant

'list'

"table" | "list" | "card"

orientation

'vertical'

"horizontal" | "vertical"

复选框按钮的布局方向。

disabled

boolean

当为 true 时，阻止用户与复选框交互

循环

false

boolean

键盘导航是否应该循环

name

string

字段的名称。作为名称/值对的一部分随其所属表单提交。

required

boolean

当为 true 时，表示用户必须在提交所属表单之前设置值。

color

'主要'

"primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral"

indicator

'start'

"start" | "end" | "hidden"

指示器的位置。

图标

appConfig.ui.icons.check

字符串 | 对象

选中时显示的图标。

ui

{ root?: ClassNameValue; fieldset?: ClassNameValue; legend?: ClassNameValue; item?: ClassNameValue; } & { root?: ClassNameValue; container?: ClassNameValue; base?: ClassNameValue; indicator?: ClassNameValue; icon?: ClassNameValue; wrapper?: ClassNameValue; label?: ClassNameValue; description?: ClassNameValue; }

插槽

插槽类型
图例

{}

label

{ item: CheckboxGroupItem & { id: string; }; }

description

{ item: CheckboxGroupItem & { id: string; }; }

事件

事件类型
update:modelValue

[value: CheckboxGroupItem[]]

change

[event: Event]

主题

app.config.ts
export default defineAppConfig({
  ui: {
    checkboxGroup: {
      slots: {
        root: 'relative',
        fieldset: 'flex gap-x-2',
        legend: 'mb-1 block font-medium text-default',
        item: ''
      },
      variants: {
        orientation: {
          horizontal: {
            fieldset: 'flex-row'
          },
          vertical: {
            fieldset: 'flex-col'
          }
        },
        color: {
          primary: {},
          secondary: {},
          success: {},
          info: {},
          warning: {},
          error: {},
          neutral: {}
        },
        variant: {
          list: {},
          card: {},
          table: {
            item: 'border border-muted'
          }
        },
        size: {
          xs: {
            fieldset: 'gap-y-0.5',
            legend: 'text-xs'
          },
          sm: {
            fieldset: 'gap-y-0.5',
            legend: 'text-xs'
          },
          md: {
            fieldset: 'gap-y-1',
            legend: 'text-sm'
          },
          lg: {
            fieldset: 'gap-y-1',
            legend: 'text-sm'
          },
          xl: {
            fieldset: 'gap-y-1.5',
            legend: 'text-base'
          }
        },
        required: {
          true: {
            legend: "after:content-['*'] after:ms-0.5 after:text-error"
          }
        }
      },
      compoundVariants: [
        {
          size: 'xs',
          variant: 'table',
          class: {
            item: 'p-2.5'
          }
        },
        {
          size: 'sm',
          variant: 'table',
          class: {
            item: 'p-3'
          }
        },
        {
          size: 'md',
          variant: 'table',
          class: {
            item: 'p-3.5'
          }
        },
        {
          size: 'lg',
          variant: 'table',
          class: {
            item: 'p-4'
          }
        },
        {
          size: 'xl',
          variant: 'table',
          class: {
            item: 'p-4.5'
          }
        },
        {
          orientation: 'horizontal',
          variant: 'table',
          class: {
            item: 'first-of-type:rounded-s-lg last-of-type:rounded-e-lg',
            fieldset: 'gap-0 -space-x-px'
          }
        },
        {
          orientation: 'vertical',
          variant: 'table',
          class: {
            item: 'first-of-type:rounded-t-lg last-of-type:rounded-b-lg',
            fieldset: 'gap-0 -space-y-px'
          }
        },
        {
          color: 'primary',
          variant: 'table',
          class: {
            item: 'has-data-[state=checked]:bg-primary/10 has-data-[state=checked]:border-primary/50 has-data-[state=checked]:z-[1]'
          }
        },
        {
          color: 'neutral',
          variant: 'table',
          class: {
            item: 'has-data-[state=checked]:bg-elevated has-data-[state=checked]:border-inverted/50 has-data-[state=checked]:z-[1]'
          }
        },
        {
          variant: 'table',
          disabled: true,
          class: {
            item: 'cursor-not-allowed opacity-75'
          }
        }
      ],
      defaultVariants: {
        size: 'md',
        variant: 'list',
        color: 'primary'
      }
    }
  }
})
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: {
        checkboxGroup: {
          slots: {
            root: 'relative',
            fieldset: 'flex gap-x-2',
            legend: 'mb-1 block font-medium text-default',
            item: ''
          },
          variants: {
            orientation: {
              horizontal: {
                fieldset: 'flex-row'
              },
              vertical: {
                fieldset: 'flex-col'
              }
            },
            color: {
              primary: {},
              secondary: {},
              success: {},
              info: {},
              warning: {},
              error: {},
              neutral: {}
            },
            variant: {
              list: {},
              card: {},
              table: {
                item: 'border border-muted'
              }
            },
            size: {
              xs: {
                fieldset: 'gap-y-0.5',
                legend: 'text-xs'
              },
              sm: {
                fieldset: 'gap-y-0.5',
                legend: 'text-xs'
              },
              md: {
                fieldset: 'gap-y-1',
                legend: 'text-sm'
              },
              lg: {
                fieldset: 'gap-y-1',
                legend: 'text-sm'
              },
              xl: {
                fieldset: 'gap-y-1.5',
                legend: 'text-base'
              }
            },
            required: {
              true: {
                legend: "after:content-['*'] after:ms-0.5 after:text-error"
              }
            }
          },
          compoundVariants: [
            {
              size: 'xs',
              variant: 'table',
              class: {
                item: 'p-2.5'
              }
            },
            {
              size: 'sm',
              variant: 'table',
              class: {
                item: 'p-3'
              }
            },
            {
              size: 'md',
              variant: 'table',
              class: {
                item: 'p-3.5'
              }
            },
            {
              size: 'lg',
              variant: 'table',
              class: {
                item: 'p-4'
              }
            },
            {
              size: 'xl',
              variant: 'table',
              class: {
                item: 'p-4.5'
              }
            },
            {
              orientation: 'horizontal',
              variant: 'table',
              class: {
                item: 'first-of-type:rounded-s-lg last-of-type:rounded-e-lg',
                fieldset: 'gap-0 -space-x-px'
              }
            },
            {
              orientation: 'vertical',
              variant: 'table',
              class: {
                item: 'first-of-type:rounded-t-lg last-of-type:rounded-b-lg',
                fieldset: 'gap-0 -space-y-px'
              }
            },
            {
              color: 'primary',
              variant: 'table',
              class: {
                item: 'has-data-[state=checked]:bg-primary/10 has-data-[state=checked]:border-primary/50 has-data-[state=checked]:z-[1]'
              }
            },
            {
              color: 'neutral',
              variant: 'table',
              class: {
                item: 'has-data-[state=checked]:bg-elevated has-data-[state=checked]:border-inverted/50 has-data-[state=checked]:z-[1]'
              }
            },
            {
              variant: 'table',
              disabled: true,
              class: {
                item: 'cursor-not-allowed opacity-75'
              }
            }
          ],
          defaultVariants: {
            size: 'md',
            variant: 'list',
            color: 'primary'
          }
        }
      }
    })
  ]
})
为便于阅读，compoundVariants 中的某些颜色已省略。请在 GitHub 上查看源代码。

更新日志

ffa5b— fix: 将泛型代理到 emits

788d2— 修复：标准化类型接口命名 (#4990)

3173b— fix: proxySlots 响应性 (#4969)

11a03— fix: labelKey 和 valueKey 的点表示法类型支持 (#4933)

5cb65— 特性：导入 @nuxt/ui-pro 组件

7133f— 修复：update:model-value 事件类型错误 (#4853)

b9adc— feat: 在 items 中添加 ui 字段 (#4060)

1b6ab— feat: 添加 table 变体 (#3997)

e6e51— fix：class 应该优先于 ui 属性

7551a— fix: 相对 UCheckbox 导入

bc061— fix: 代理插槽 & ui 属性

9c3d5— 功能：新组件 (#3862)

Checkbox

用于在选中和未选中状态之间切换的输入元素。

ColorPicker

用于选择颜色的组件。