Switch

一个在两种状态之间切换的控件。

用法

使用 v-model 指令来控制 Switch 的选中状态。

<script setup lang="ts">
const value = ref(true)
</script>

<template>
  <USwitch v-model="value" />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref(true)
</script>

<template>
  <USwitch v-model="value" />
</template>

使用 default-value prop 在您不需要控制其状态时设置初始值。

<template>
  <USwitch default-value />
</template>

描述

使用 description 属性来设置 Switch 的描述信息。

description

选中我

这是一个复选框。

<template>
  <USwitch label="Check me" description="This is a checkbox." />
</template>

Icon

使用 checked-icon 和 unchecked-icon 属性来设置 Switch 在选中和未选中状态下的图标。

未选中图标 (uncheckedIcon)

checkedIcon

选中我

<template>
  <USwitch
    unchecked-icon="i-lucide-x"
    checked-icon="i-lucide-check"
    default-value
    label="Check me"
  />
</template>

加载中

使用 loading 属性在 Switch 上显示加载图标。

选中我

<template>
  <USwitch loading default-value label="Check me" />
</template>

加载图标

使用 loading-icon prop 来自定义加载图标。默认为 i-lucide-loader-circle。

loadingIcon

选中我

<template>
  <USwitch loading loading-icon="i-lucide-loader" default-value label="Check me" />
</template>

你可以在 app.config.ts 中的 ui.icons.loading 键下全局自定义此图标。

你可以在 vite.config.ts 中的 ui.icons.loading 键下全局自定义此图标。

颜色

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

color

选中我

<template>
  <USwitch color="neutral" default-value label="Check me" />
</template>

尺寸

使用 size 属性更改 Switch 的尺寸。

尺寸

选中我

<template>
  <USwitch size="xl" default-value label="Check me" />
</template>

禁用

使用 disabled 属性禁用 Switch。

disabled

选中我

<template>
  <USwitch disabled label="Check me" />
</template>

API

属性

属性	默认值	类型
`as`	`'div'`	`any` 此组件应渲染为的元素或组件。
`color`	`'primary'`	`"primary" \| "secondary" \| "success" \| "info" \| "warning" \| "error" \| "neutral"`
`尺寸`	`'md'`	`"md" \| "xs" \| "sm" \| "lg" \| "xl"`
`高亮`		`boolean` 高亮环形颜色，如同焦点状态。
`loading`		`boolean` 当为 `true` 时，将显示加载图标。
`loadingIcon`	`appConfig.ui.icons.loading`	`any` 当 `loading` prop 为 `true` 时显示的图标。
`checkedIcon`		`any` 当开关被选中时显示图标。
`未选中图标 (uncheckedIcon)`		`any` 当开关未被选中时显示图标。
`label`		`string`
`description`		`string`
`disabled`		`boolean` 当设为 `true` 时，禁止用户与开关交互。
`id`		`string`
`name`		`string` 字段的名称。作为名称/值对的一部分随其所属表单提交。
`required`		`boolean` 当为 `true` 时，表示用户必须在提交所属表单之前设置值。
`value`		`string` 当与 `name` 一起提交时，作为数据给定的值。
`defaultValue`		`T` 初始渲染时开关的状态。当不需要控制其状态时使用。
`modelValue`		`null \| T` 开关的受控状态。可以绑定为 `v-model`。
`trueValue`		`T` 开关开启时使用的值。默认为 `true`。
`falseValue`		`T` 开关关闭时使用的值。默认为 `false`。
`autofocus`		`false \| true \| "true" \| "false"`
`ui`		`{ root?: SlotClass; base?: SlotClass; container?: SlotClass; thumb?: SlotClass; icon?: SlotClass; wrapper?: SlotClass; label?: SlotClass; description?: SlotClass; }`

此组件还支持所有原生 <button> HTML 属性。

插槽

插槽	类型
`label`	`{ label: string \| undefined; }`
`description`	`{ description: string \| undefined; }`

事件

事件	类型
`change`	`[事件: Event]`
`update:modelValue`	`[payload: T]`

主题

app.config.ts

export default defineAppConfig({
  ui: {
    switch: {
      slots: {
        root: 'relative flex items-start',
        base: [
          'inline-flex items-center shrink-0 rounded-full border-2 border-transparent focus-visible:outline-3 data-[state=unchecked]:bg-accented',
          'transition-[background] duration-200'
        ],
        container: 'flex items-center',
        thumb: 'group pointer-events-none rounded-full bg-default shadow-lg ring-0 transition-transform duration-200 data-[state=unchecked]:translate-x-0 data-[state=unchecked]:rtl:-translate-x-0 flex items-center justify-center',
        icon: [
          'absolute shrink-0 group-data-[state=unchecked]:text-dimmed opacity-0 size-10/12',
          'transition-[color,opacity] duration-200'
        ],
        wrapper: 'ms-2',
        label: 'block font-medium text-default',
        description: 'text-muted'
      },
      variants: {
        color: {
          primary: {
            base: 'data-[state=checked]:bg-primary outline-primary/25',
            icon: 'group-data-[state=checked]:text-primary'
          },
          secondary: {
            base: 'data-[state=checked]:bg-secondary outline-secondary/25',
            icon: 'group-data-[state=checked]:text-secondary'
          },
          success: {
            base: 'data-[state=checked]:bg-success outline-success/25',
            icon: 'group-data-[state=checked]:text-success'
          },
          info: {
            base: 'data-[state=checked]:bg-info outline-info/25',
            icon: 'group-data-[state=checked]:text-info'
          },
          warning: {
            base: 'data-[state=checked]:bg-warning outline-warning/25',
            icon: 'group-data-[state=checked]:text-warning'
          },
          error: {
            base: 'data-[state=checked]:bg-error outline-error/25',
            icon: 'group-data-[state=checked]:text-error'
          },
          neutral: {
            base: 'data-[state=checked]:bg-inverted outline-inverted/25',
            icon: 'group-data-[state=checked]:text-highlighted'
          }
        },
        size: {
          xs: {
            base: 'w-7',
            container: 'h-4',
            thumb: 'size-3 data-[state=checked]:translate-x-3 data-[state=checked]:rtl:-translate-x-3',
            wrapper: 'text-xs'
          },
          sm: {
            base: 'w-8',
            container: 'h-4',
            thumb: 'size-3.5 data-[state=checked]:translate-x-3.5 data-[state=checked]:rtl:-translate-x-3.5',
            wrapper: 'text-xs'
          },
          md: {
            base: 'w-9',
            container: 'h-5',
            thumb: 'size-4 data-[state=checked]:translate-x-4 data-[state=checked]:rtl:-translate-x-4',
            wrapper: 'text-sm'
          },
          lg: {
            base: 'w-10',
            container: 'h-5',
            thumb: 'size-4.5 data-[state=checked]:translate-x-4.5 data-[state=checked]:rtl:-translate-x-4.5',
            wrapper: 'text-sm'
          },
          xl: {
            base: 'w-11',
            container: 'h-6',
            thumb: 'size-5 data-[state=checked]:translate-x-5 data-[state=checked]:rtl:-translate-x-5',
            wrapper: 'text-base'
          }
        },
        checked: {
          true: {
            icon: 'group-data-[state=checked]:opacity-100'
          }
        },
        unchecked: {
          true: {
            icon: 'group-data-[state=unchecked]:opacity-100'
          }
        },
        loading: {
          true: {
            icon: 'animate-spin'
          }
        },
        highlight: {
          true: ''
        },
        required: {
          true: {
            label: "after:content-['*'] after:ms-0.5 after:text-error"
          }
        },
        disabled: {
          true: {
            root: 'opacity-75',
            base: 'cursor-not-allowed',
            label: 'cursor-not-allowed',
            description: 'cursor-not-allowed'
          }
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          highlight: true,
          class: {
            base: 'ring ring-primary'
          }
        },
        {
          color: 'neutral',
          highlight: true,
          class: {
            base: 'ring ring-inverted'
          }
        }
      ],
      defaultVariants: {
        color: 'primary',
        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: {
        switch: {
          slots: {
            root: 'relative flex items-start',
            base: [
              'inline-flex items-center shrink-0 rounded-full border-2 border-transparent focus-visible:outline-3 data-[state=unchecked]:bg-accented',
              'transition-[background] duration-200'
            ],
            container: 'flex items-center',
            thumb: 'group pointer-events-none rounded-full bg-default shadow-lg ring-0 transition-transform duration-200 data-[state=unchecked]:translate-x-0 data-[state=unchecked]:rtl:-translate-x-0 flex items-center justify-center',
            icon: [
              'absolute shrink-0 group-data-[state=unchecked]:text-dimmed opacity-0 size-10/12',
              'transition-[color,opacity] duration-200'
            ],
            wrapper: 'ms-2',
            label: 'block font-medium text-default',
            description: 'text-muted'
          },
          variants: {
            color: {
              primary: {
                base: 'data-[state=checked]:bg-primary outline-primary/25',
                icon: 'group-data-[state=checked]:text-primary'
              },
              secondary: {
                base: 'data-[state=checked]:bg-secondary outline-secondary/25',
                icon: 'group-data-[state=checked]:text-secondary'
              },
              success: {
                base: 'data-[state=checked]:bg-success outline-success/25',
                icon: 'group-data-[state=checked]:text-success'
              },
              info: {
                base: 'data-[state=checked]:bg-info outline-info/25',
                icon: 'group-data-[state=checked]:text-info'
              },
              warning: {
                base: 'data-[state=checked]:bg-warning outline-warning/25',
                icon: 'group-data-[state=checked]:text-warning'
              },
              error: {
                base: 'data-[state=checked]:bg-error outline-error/25',
                icon: 'group-data-[state=checked]:text-error'
              },
              neutral: {
                base: 'data-[state=checked]:bg-inverted outline-inverted/25',
                icon: 'group-data-[state=checked]:text-highlighted'
              }
            },
            size: {
              xs: {
                base: 'w-7',
                container: 'h-4',
                thumb: 'size-3 data-[state=checked]:translate-x-3 data-[state=checked]:rtl:-translate-x-3',
                wrapper: 'text-xs'
              },
              sm: {
                base: 'w-8',
                container: 'h-4',
                thumb: 'size-3.5 data-[state=checked]:translate-x-3.5 data-[state=checked]:rtl:-translate-x-3.5',
                wrapper: 'text-xs'
              },
              md: {
                base: 'w-9',
                container: 'h-5',
                thumb: 'size-4 data-[state=checked]:translate-x-4 data-[state=checked]:rtl:-translate-x-4',
                wrapper: 'text-sm'
              },
              lg: {
                base: 'w-10',
                container: 'h-5',
                thumb: 'size-4.5 data-[state=checked]:translate-x-4.5 data-[state=checked]:rtl:-translate-x-4.5',
                wrapper: 'text-sm'
              },
              xl: {
                base: 'w-11',
                container: 'h-6',
                thumb: 'size-5 data-[state=checked]:translate-x-5 data-[state=checked]:rtl:-translate-x-5',
                wrapper: 'text-base'
              }
            },
            checked: {
              true: {
                icon: 'group-data-[state=checked]:opacity-100'
              }
            },
            unchecked: {
              true: {
                icon: 'group-data-[state=unchecked]:opacity-100'
              }
            },
            loading: {
              true: {
                icon: 'animate-spin'
              }
            },
            highlight: {
              true: ''
            },
            required: {
              true: {
                label: "after:content-['*'] after:ms-0.5 after:text-error"
              }
            },
            disabled: {
              true: {
                root: 'opacity-75',
                base: 'cursor-not-allowed',
                label: 'cursor-not-allowed',
                description: 'cursor-not-allowed'
              }
            }
          },
          compoundVariants: [
            {
              color: 'primary',
              highlight: true,
              class: {
                base: 'ring ring-primary'
              }
            },
            {
              color: 'neutral',
              highlight: true,
              class: {
                base: 'ring ring-inverted'
              }
            }
          ],
          defaultVariants: {
            color: 'primary',
            size: 'md'
          }
        }
      }
    })
  ]
})

为便于阅读，compoundVariants 中的某些颜色已省略。请在 GitHub 上查看源代码。

更新日志

暂无近期更新

滑块 (Slider)

用于在范围内选择数值的输入组件。

多行文本框 (Textarea)

用于输入多行文本的文本域元素。