RadioGroup

RadioGroupGitHub
一组单选按钮，用于从列表中选择单个选项。

用法

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

项目

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

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

const items = ref<RadioGroupItem[]>(['System', 'Light', 'Dark'])
const value = ref<RadioGroupValue>('System')
</script>

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

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

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

const items = ref<RadioGroupItem[]>([
  {
    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<RadioGroupValue>('system')
</script>

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

值键

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

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

const items = ref<RadioGroupItem[]>([
  {
    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<RadioGroupValue>('light')
</script>

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

图例

使用 legend 属性来设置 RadioGroup 的图例。

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

const items = ref<RadioGroupItem[]>(['System', 'Light', 'Dark'])
</script>

<template>
  <URadioGroup legend="Theme" default-value="System" :items="items" />
</template>

颜色

使用 color 属性来更改 RadioGroup 的颜色。

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

const items = ref<RadioGroupItem[]>(['System', 'Light', 'Dark'])
</script>

<template>
  <URadioGroup color="neutral" default-value="System" :items="items" />
</template>

变体 New

使用 variant 属性来更改 RadioGroup 的变体。

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

const items = ref<RadioGroupItem[]>([
  {
    label: 'Pro',
    value: 'pro',
    description: 'Tailored for indie hackers, freelancers and solo founders.'
  },
  {
    label: 'Startup',
    value: 'startup',
    description: 'Best suited for small teams, startups and agencies.'
  },
  {
    label: 'Enterprise',
    value: 'enterprise',
    description: 'Ideal for larger teams and organizations.'
  }
])
</script>

<template>
  <URadioGroup color="primary" variant="table" default-value="pro" :items="items" />
</template>

尺寸

使用 size 属性来更改 RadioGroup 的尺寸。

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

const items = ref<RadioGroupItem[]>(['System', 'Light', 'Dark'])
</script>

<template>
  <URadioGroup size="xl" variant="list" default-value="System" :items="items" />
</template>

方向

使用 orientation 属性来更改单选按钮的排列方向。默认为 vertical。

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

const items = ref<RadioGroupItem[]>(['System', 'Light', 'Dark'])
</script>

<template>
  <URadioGroup orientation="horizontal" variant="list" default-value="System" :items="items" />
</template>

指示器 New

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

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

const items = ref<RadioGroupItem[]>(['System', 'Light', 'Dark'])
</script>

<template>
  <URadioGroup indicator="end" variant="card" default-value="System" :items="items" />
</template>

禁用

使用 disabled 属性来禁用 RadioGroup。

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

const items = ref<RadioGroupItem[]>(['System', 'Light', 'Dark'])
</script>

<template>
  <URadioGroup disabled default-value="System" :items="items" />
</template>

API

属性 (Props)

属性默认值类型
as

'div'

任意

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

图例

string

valueKey

'value'

string

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

labelKey

'label'

string

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

descriptionKey

'description'

string

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

items

RadioGroupItem[]

尺寸

'md'

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

变体

'list'

"card" | "list" | "table"

颜色

'primary'

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

方向

'vertical'

"horizontal" | "vertical"

单选按钮的排列方向。

指示器

'start'

"start" | "end" | "hidden"

指示器的位置。

defaultValue

null | string | number | Record<string, any>

初始渲染时应选中单选项的值。

当你不需要控制单选项状态时使用。

禁用

boolean

当为 true 时，阻止用户与单选项交互。

loop

boolean

当为 true 时，键盘导航将从最后一个项目循环到第一个项目，反之亦然。

modelValue

null | string | number | Record<string, any>

要选中的单选项的受控值。可以绑定为 v-model。

name

string

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

required

boolean

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

ui

{ root?: ClassNameValue; fieldset?: ClassNameValue; legend?: ClassNameValue; item?: ClassNameValue; container?: ClassNameValue; ... 4 more ...; description?: ClassNameValue; }

插槽 (Slots)

插槽类型
图例

{}

label

{ item: RadioGroupItem & { id: string; }; modelValue?: AcceptableValue | undefined; }

description

{ item: RadioGroupItem & { id: string; }; modelValue?: AcceptableValue | undefined; }

事件 (Emits)

事件类型
change

[payload: Event]

update:modelValue

[payload: string]

主题

app.config.ts
export default defineAppConfig({
  ui: {
    radioGroup: {
      slots: {
        root: 'relative',
        fieldset: 'flex gap-x-2',
        legend: 'mb-1 block font-medium text-default',
        item: 'flex items-start',
        container: 'flex items-center',
        base: 'rounded-full ring ring-inset ring-accented overflow-hidden focus-visible:outline-2 focus-visible:outline-offset-2',
        indicator: 'flex items-center justify-center size-full after:bg-default after:rounded-full',
        wrapper: 'w-full',
        label: 'block font-medium text-default',
        description: 'text-muted'
      },
      variants: {
        color: {
          primary: {
            base: 'focus-visible:outline-primary',
            indicator: 'bg-primary'
          },
          secondary: {
            base: 'focus-visible:outline-secondary',
            indicator: 'bg-secondary'
          },
          success: {
            base: 'focus-visible:outline-success',
            indicator: 'bg-success'
          },
          info: {
            base: 'focus-visible:outline-info',
            indicator: 'bg-info'
          },
          warning: {
            base: 'focus-visible:outline-warning',
            indicator: 'bg-warning'
          },
          error: {
            base: 'focus-visible:outline-error',
            indicator: 'bg-error'
          },
          neutral: {
            base: 'focus-visible:outline-inverted',
            indicator: 'bg-inverted'
          }
        },
        variant: {
          list: {
            item: ''
          },
          card: {
            item: 'border border-muted rounded-lg'
          },
          table: {
            item: 'border border-muted'
          }
        },
        orientation: {
          horizontal: {
            fieldset: 'flex-row'
          },
          vertical: {
            fieldset: 'flex-col'
          }
        },
        indicator: {
          start: {
            item: 'flex-row',
            wrapper: 'ms-2'
          },
          end: {
            item: 'flex-row-reverse',
            wrapper: 'me-2'
          },
          hidden: {
            base: 'sr-only',
            wrapper: 'text-center'
          }
        },
        size: {
          xs: {
            fieldset: 'gap-y-0.5',
            legend: 'text-xs',
            base: 'size-3',
            item: 'text-xs',
            container: 'h-4',
            indicator: 'after:size-1'
          },
          sm: {
            fieldset: 'gap-y-0.5',
            legend: 'text-xs',
            base: 'size-3.5',
            item: 'text-xs',
            container: 'h-4',
            indicator: 'after:size-1'
          },
          md: {
            fieldset: 'gap-y-1',
            legend: 'text-sm',
            base: 'size-4',
            item: 'text-sm',
            container: 'h-5',
            indicator: 'after:size-1.5'
          },
          lg: {
            fieldset: 'gap-y-1',
            legend: 'text-sm',
            base: 'size-4.5',
            item: 'text-sm',
            container: 'h-5',
            indicator: 'after:size-1.5'
          },
          xl: {
            fieldset: 'gap-y-1.5',
            legend: 'text-base',
            base: 'size-5',
            item: 'text-base',
            container: 'h-6',
            indicator: 'after:size-2'
          }
        },
        disabled: {
          true: {
            base: 'cursor-not-allowed opacity-75',
            label: 'cursor-not-allowed opacity-75'
          }
        },
        required: {
          true: {
            legend: "after:content-['*'] after:ms-0.5 after:text-error"
          }
        }
      },
      compoundVariants: [
        {
          size: 'xs',
          variant: [
            'card',
            'table'
          ],
          class: {
            item: 'p-2.5'
          }
        },
        {
          size: 'sm',
          variant: [
            'card',
            'table'
          ],
          class: {
            item: 'p-3'
          }
        },
        {
          size: 'md',
          variant: [
            'card',
            'table'
          ],
          class: {
            item: 'p-3.5'
          }
        },
        {
          size: 'lg',
          variant: [
            'card',
            'table'
          ],
          class: {
            item: 'p-4'
          }
        },
        {
          size: 'xl',
          variant: [
            'card',
            'table'
          ],
          class: {
            item: 'p-4.5'
          }
        },
        {
          orientation: 'horizontal',
          variant: 'table',
          class: {
            item: 'first-of-type:rounded-l-lg last-of-type:rounded-r-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: 'card',
          class: {
            item: 'has-data-[state=checked]:border-primary'
          }
        },
        {
          color: 'neutral',
          variant: 'card',
          class: {
            item: 'has-data-[state=checked]:border-inverted'
          }
        },
        {
          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: [
            'card',
            'table'
          ],
          disabled: true,
          class: {
            item: 'cursor-not-allowed opacity-75'
          }
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'primary',
        variant: 'list',
        orientation: 'vertical',
        indicator: 'start'
      }
    }
  }
})
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: {
        radioGroup: {
          slots: {
            root: 'relative',
            fieldset: 'flex gap-x-2',
            legend: 'mb-1 block font-medium text-default',
            item: 'flex items-start',
            container: 'flex items-center',
            base: 'rounded-full ring ring-inset ring-accented overflow-hidden focus-visible:outline-2 focus-visible:outline-offset-2',
            indicator: 'flex items-center justify-center size-full after:bg-default after:rounded-full',
            wrapper: 'w-full',
            label: 'block font-medium text-default',
            description: 'text-muted'
          },
          variants: {
            color: {
              primary: {
                base: 'focus-visible:outline-primary',
                indicator: 'bg-primary'
              },
              secondary: {
                base: 'focus-visible:outline-secondary',
                indicator: 'bg-secondary'
              },
              success: {
                base: 'focus-visible:outline-success',
                indicator: 'bg-success'
              },
              info: {
                base: 'focus-visible:outline-info',
                indicator: 'bg-info'
              },
              warning: {
                base: 'focus-visible:outline-warning',
                indicator: 'bg-warning'
              },
              error: {
                base: 'focus-visible:outline-error',
                indicator: 'bg-error'
              },
              neutral: {
                base: 'focus-visible:outline-inverted',
                indicator: 'bg-inverted'
              }
            },
            variant: {
              list: {
                item: ''
              },
              card: {
                item: 'border border-muted rounded-lg'
              },
              table: {
                item: 'border border-muted'
              }
            },
            orientation: {
              horizontal: {
                fieldset: 'flex-row'
              },
              vertical: {
                fieldset: 'flex-col'
              }
            },
            indicator: {
              start: {
                item: 'flex-row',
                wrapper: 'ms-2'
              },
              end: {
                item: 'flex-row-reverse',
                wrapper: 'me-2'
              },
              hidden: {
                base: 'sr-only',
                wrapper: 'text-center'
              }
            },
            size: {
              xs: {
                fieldset: 'gap-y-0.5',
                legend: 'text-xs',
                base: 'size-3',
                item: 'text-xs',
                container: 'h-4',
                indicator: 'after:size-1'
              },
              sm: {
                fieldset: 'gap-y-0.5',
                legend: 'text-xs',
                base: 'size-3.5',
                item: 'text-xs',
                container: 'h-4',
                indicator: 'after:size-1'
              },
              md: {
                fieldset: 'gap-y-1',
                legend: 'text-sm',
                base: 'size-4',
                item: 'text-sm',
                container: 'h-5',
                indicator: 'after:size-1.5'
              },
              lg: {
                fieldset: 'gap-y-1',
                legend: 'text-sm',
                base: 'size-4.5',
                item: 'text-sm',
                container: 'h-5',
                indicator: 'after:size-1.5'
              },
              xl: {
                fieldset: 'gap-y-1.5',
                legend: 'text-base',
                base: 'size-5',
                item: 'text-base',
                container: 'h-6',
                indicator: 'after:size-2'
              }
            },
            disabled: {
              true: {
                base: 'cursor-not-allowed opacity-75',
                label: 'cursor-not-allowed opacity-75'
              }
            },
            required: {
              true: {
                legend: "after:content-['*'] after:ms-0.5 after:text-error"
              }
            }
          },
          compoundVariants: [
            {
              size: 'xs',
              variant: [
                'card',
                'table'
              ],
              class: {
                item: 'p-2.5'
              }
            },
            {
              size: 'sm',
              variant: [
                'card',
                'table'
              ],
              class: {
                item: 'p-3'
              }
            },
            {
              size: 'md',
              variant: [
                'card',
                'table'
              ],
              class: {
                item: 'p-3.5'
              }
            },
            {
              size: 'lg',
              variant: [
                'card',
                'table'
              ],
              class: {
                item: 'p-4'
              }
            },
            {
              size: 'xl',
              variant: [
                'card',
                'table'
              ],
              class: {
                item: 'p-4.5'
              }
            },
            {
              orientation: 'horizontal',
              variant: 'table',
              class: {
                item: 'first-of-type:rounded-l-lg last-of-type:rounded-r-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: 'card',
              class: {
                item: 'has-data-[state=checked]:border-primary'
              }
            },
            {
              color: 'neutral',
              variant: 'card',
              class: {
                item: 'has-data-[state=checked]:border-inverted'
              }
            },
            {
              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: [
                'card',
                'table'
              ],
              disabled: true,
              class: {
                item: 'cursor-not-allowed opacity-75'
              }
            }
          ],
          defaultVariants: {
            size: 'md',
            color: 'primary',
            variant: 'list',
            orientation: 'vertical',
            indicator: 'start'
          }
        }
      }
    })
  ]
})
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: {
        radioGroup: {
          slots: {
            root: 'relative',
            fieldset: 'flex gap-x-2',
            legend: 'mb-1 block font-medium text-default',
            item: 'flex items-start',
            container: 'flex items-center',
            base: 'rounded-full ring ring-inset ring-accented overflow-hidden focus-visible:outline-2 focus-visible:outline-offset-2',
            indicator: 'flex items-center justify-center size-full after:bg-default after:rounded-full',
            wrapper: 'w-full',
            label: 'block font-medium text-default',
            description: 'text-muted'
          },
          variants: {
            color: {
              primary: {
                base: 'focus-visible:outline-primary',
                indicator: 'bg-primary'
              },
              secondary: {
                base: 'focus-visible:outline-secondary',
                indicator: 'bg-secondary'
              },
              success: {
                base: 'focus-visible:outline-success',
                indicator: 'bg-success'
              },
              info: {
                base: 'focus-visible:outline-info',
                indicator: 'bg-info'
              },
              warning: {
                base: 'focus-visible:outline-warning',
                indicator: 'bg-warning'
              },
              error: {
                base: 'focus-visible:outline-error',
                indicator: 'bg-error'
              },
              neutral: {
                base: 'focus-visible:outline-inverted',
                indicator: 'bg-inverted'
              }
            },
            variant: {
              list: {
                item: ''
              },
              card: {
                item: 'border border-muted rounded-lg'
              },
              table: {
                item: 'border border-muted'
              }
            },
            orientation: {
              horizontal: {
                fieldset: 'flex-row'
              },
              vertical: {
                fieldset: 'flex-col'
              }
            },
            indicator: {
              start: {
                item: 'flex-row',
                wrapper: 'ms-2'
              },
              end: {
                item: 'flex-row-reverse',
                wrapper: 'me-2'
              },
              hidden: {
                base: 'sr-only',
                wrapper: 'text-center'
              }
            },
            size: {
              xs: {
                fieldset: 'gap-y-0.5',
                legend: 'text-xs',
                base: 'size-3',
                item: 'text-xs',
                container: 'h-4',
                indicator: 'after:size-1'
              },
              sm: {
                fieldset: 'gap-y-0.5',
                legend: 'text-xs',
                base: 'size-3.5',
                item: 'text-xs',
                container: 'h-4',
                indicator: 'after:size-1'
              },
              md: {
                fieldset: 'gap-y-1',
                legend: 'text-sm',
                base: 'size-4',
                item: 'text-sm',
                container: 'h-5',
                indicator: 'after:size-1.5'
              },
              lg: {
                fieldset: 'gap-y-1',
                legend: 'text-sm',
                base: 'size-4.5',
                item: 'text-sm',
                container: 'h-5',
                indicator: 'after:size-1.5'
              },
              xl: {
                fieldset: 'gap-y-1.5',
                legend: 'text-base',
                base: 'size-5',
                item: 'text-base',
                container: 'h-6',
                indicator: 'after:size-2'
              }
            },
            disabled: {
              true: {
                base: 'cursor-not-allowed opacity-75',
                label: 'cursor-not-allowed opacity-75'
              }
            },
            required: {
              true: {
                legend: "after:content-['*'] after:ms-0.5 after:text-error"
              }
            }
          },
          compoundVariants: [
            {
              size: 'xs',
              variant: [
                'card',
                'table'
              ],
              class: {
                item: 'p-2.5'
              }
            },
            {
              size: 'sm',
              variant: [
                'card',
                'table'
              ],
              class: {
                item: 'p-3'
              }
            },
            {
              size: 'md',
              variant: [
                'card',
                'table'
              ],
              class: {
                item: 'p-3.5'
              }
            },
            {
              size: 'lg',
              variant: [
                'card',
                'table'
              ],
              class: {
                item: 'p-4'
              }
            },
            {
              size: 'xl',
              variant: [
                'card',
                'table'
              ],
              class: {
                item: 'p-4.5'
              }
            },
            {
              orientation: 'horizontal',
              variant: 'table',
              class: {
                item: 'first-of-type:rounded-l-lg last-of-type:rounded-r-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: 'card',
              class: {
                item: 'has-data-[state=checked]:border-primary'
              }
            },
            {
              color: 'neutral',
              variant: 'card',
              class: {
                item: 'has-data-[state=checked]:border-inverted'
              }
            },
            {
              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: [
                'card',
                'table'
              ],
              disabled: true,
              class: {
                item: 'cursor-not-allowed opacity-75'
              }
            }
          ],
          defaultVariants: {
            size: 'md',
            color: 'primary',
            variant: 'list',
            orientation: 'vertical',
            indicator: 'start'
          }
        }
      }
    })
  ]
})
compoundVariants 中的一些颜色为便于阅读已省略。请在 GitHub 上查看源代码。

Progress

显示任务进度的指示器。

Select

用于从选项列表中选择的 select 元素。