自定义组件
了解如何使用 Tailwind Variants API 自定义 Nuxt UI 组件，以实现高级、灵活且可维护的样式。
Tailwind Variants
Nuxt UI 组件使用Tailwind VariantsAPI 进行样式设置，它提供了一种强大的方式来创建变体和管理组件样式。
插槽
组件可以有多个 slots，每个 slot 代表组件内不同的 HTML 元素或部分。这些 slot 允许灵活的内容插入和样式设置。
以具有多个 slot 的 Card 组件为例
export default {
slots: {
root: 'bg-default ring ring-default divide-y divide-default rounded-lg',
header: 'p-4 sm:px-6',
body: 'p-4 sm:p-6',
footer: 'p-4 sm:px-6'
}
}
<template>
<div :class="ui.root({ class: [props.ui?.root, props.class] })">
<div :class="ui.header({ class: props.ui?.header })">
<slot name="header" />
</div>
<div :class="ui.body({ class: props.ui?.body })">
<slot />
</div>
<div :class="ui.footer({ class: props.ui?.footer })">
<slot name="footer" />
</div>
</div>
</template>
有些组件没有 slot，它们只由一个根元素组成。在这种情况下，主题只定义 base slot，例如 Container 组件
export default {
base: 'max-w-(--ui-container) mx-auto px-4 sm:px-6 lg:px-8'
}
<template>
<div :class="container({ class: props.class })">
<slot />
</div>
</template>
变体
组件支持 variants，它允许您根据组件 props 动态调整不同 slots 的样式。
例如，Avatar 组件使用 size 变体来控制其外观
src/theme/avatar.ts
export default {
slots: {
root: 'inline-flex items-center justify-center shrink-0 select-none overflow-hidden rounded-full align-middle bg-elevated',
image: 'h-full w-full rounded-[inherit] object-cover'
},
variants: {
size: {
sm: {
root: 'size-7 text-sm'
},
md: {
root: 'size-8 text-base'
},
lg: {
root: 'size-9 text-lg'
}
}
},
defaultVariants: {
size: 'md'
}
}
这样，size prop 将把相应的样式应用到 root slot。
<template>
<UAvatar src="https://github.com/nuxt.png" size="lg" />
</template>
默认变体
defaultVariants 属性设置每个变体的默认值，当没有传递 prop 时。
例如，Avatar 组件的默认大小设置为 md
src/theme/avatar.ts
export default {
slots: {
root: 'inline-flex items-center justify-center shrink-0 select-none overflow-hidden rounded-full align-middle bg-elevated',
image: 'h-full w-full rounded-[inherit] object-cover'
},
variants: {
size: {
sm: {
root: 'size-7 text-sm'
},
md: {
root: 'size-8 text-base'
},
lg: {
root: 'size-9 text-lg'
}
}
},
defaultVariants: {
size: 'md'
}
}
复合变体
有些组件使用 compoundVariants 属性，在同时满足多个变体条件时应用类。
例如，Button 组件使用 compoundVariants 属性来为特定的 color 和 variant 组合应用类。
src/theme/button.ts
import type { ModuleOptions } from '../module'
export default (options: Required<ModuleOptions>) => ({
slots: {
base: ['rounded-md font-medium inline-flex items-center disabled:cursor-not-allowed aria-disabled:cursor-not-allowed disabled:opacity-75 aria-disabled:opacity-75', options.theme.transitions && 'transition-colors']
},
variants: {
color: {
...Object.fromEntries((options.theme.colors || []).map((color: string) => [color, ''])),
neutral: ''
},
variant: {
solid: '',
outline: '',
soft: '',
subtle: '',
ghost: '',
link: ''
}
},
compoundVariants: [
...(options.theme.colors || []).map((color: string) => ({
color,
variant: 'outline',
class: `ring ring-inset ring-${color}/50 text-${color} hover:bg-${color}/10 active:bg-${color}/10 disabled:bg-transparent aria-disabled:bg-transparent dark:disabled:bg-transparent dark:aria-disabled:bg-transparent focus:outline-none focus-visible:ring-2 focus-visible:ring-${color}`
})),
{
color: 'neutral',
variant: 'outline',
class: 'ring ring-inset ring-accented text-default bg-default hover:bg-elevated active:bg-elevated disabled:bg-default aria-disabled:bg-default focus:outline-none focus-visible:ring-2 focus-visible:ring-inverted'
}
],
defaultVariants: {
color: 'primary',
variant: 'solid'
}
})
自定义主题
您可以通过多种方式自定义 Nuxt UI 组件的外观，可以一次性为所有组件进行自定义，也可以按组件进行自定义。
Tailwind Variants 在底层使用
tailwind-merge来合并类，所以您不必担心类冲突。您可以通过两种方式探索每个组件的主题
- 查看每个单独组件文档中的
Theme部分。 - 直接在 GitHub 仓库中浏览源代码，路径为
src/theme.
全局配置
您可以使用与主题对象完全相同的结构，在 app.config.ts 中全局覆盖组件主题。
您可以使用与主题对象完全相同的结构，在 vite.config.ts 中全局覆盖组件主题。
您可以自定义slots, variants, compoundVariants和defaultVariants以更改组件的默认主题
app.config.ts
export default defineAppConfig({
ui: {
button: {
slots: {
base: 'font-bold'
},
variants: {
size: {
md: {
leadingIcon: 'size-4'
}
}
},
compoundVariants: [{
color: 'neutral',
variant: 'outline',
class: 'ring-default hover:bg-accented'
}],
defaultVariants: {
color: 'neutral',
variant: 'outline'
}
}
}
})
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: {
button: {
slots: {
base: 'font-bold'
},
variants: {
size: {
md: {
leadingIcon: 'size-4'
}
}
},
compoundVariants: [{
color: 'neutral',
variant: 'outline',
class: 'ring-default hover:bg-accented'
}],
defaultVariants: {
color: 'neutral',
variant: 'outline'
}
}
}
})
]
})
在此示例中，
font-bold 覆盖了所有按钮上的 font-medium，当 size="md" 时，size-4 覆盖了前置图标上的 size-5 类，并且当 color="neutral" 和 variant="outline" 时，ring-default hover:bg-accented 覆盖了 ring-accented hover:bg-elevated。按钮现在默认使用 color="neutral" 和 variant="outline"。ui 属性
您还可以使用 ui prop 覆盖组件的 slots。这优先于全局配置和已解析的 variants。
<template>
<UButton
trailing-icon="i-lucide-chevron-right"
size="md"
color="neutral"
variant="outline"
:ui="{
trailingIcon: 'rotate-90 size-3'
}"
>
Button
</UButton>
</template>
在此示例中，
trailingIcon slot 被 size-3 覆盖，即使 md 大小变体将对其应用 size-5 类。class 属性
class prop 允许您覆盖 root 或 base slot 的类。这优先于全局配置和已解析的 variants。
<template>
<UButton class="font-bold rounded-full">Button</UButton>
</template>
在此示例中，
font-bold 类将覆盖此按钮上的默认 font-medium 类。