Nuxt UI v3-alpha 已发布！

试试看
入门

主题

了解如何自定义组件的外观。

该模块依赖于 Nuxt 应用配置 文件，以使用 HMR（热模块替换）在运行时自定义组件的外观。

颜色

配置

组件基于 primary 和 gray 颜色。您可以在 app.config.ts 中更改它们。

app.config.ts
export default defineAppConfig({
  ui: {
    primary: 'green',
    gray: 'cool'
  }
})
尝试通过点击标题中的 按钮来更改 primary 和 gray 颜色。

由于该模块在底层使用 Tailwind CSS，因此您可以使用任何 Tailwind CSS 颜色 或者您自己的自定义颜色或组，例如 brand.primary。默认情况下，primary 颜色为 green，gray 颜色为 cool。

当 使用自定义颜色 或 添加额外颜色 通过 extend 键在您的 tailwind.config.ts 中，您需要确保定义从 50 到 950 的所有色调，因为它们中的大多数用于在 ui.config/ 目录中定义的组件配置中。

tailwind.config.ts
import type { Config } from 'tailwindcss'
import defaultTheme from 'tailwindcss/defaultTheme'

export default <Partial<Config>>{
  theme: {
    extend: {
      colors: {
        green: {
          50: '#EFFDF5',
          100: '#D9FBE8',
          200: '#B3F5D1',
          300: '#75EDAE',
          400: '#00DC82',
          500: '#00C16A',
          600: '#00A155',
          700: '#007F45',
          800: '#016538',
          900: '#0A5331',
          950: '#052e16'
        }
      }
    }
  }
}

CSS 变量

为了提供可以在运行时更改的动态颜色，该模块使用 CSS 变量。由于 Tailwind CSS 已经有一个 gray 颜色，因此该模块会自动将其重命名为 cool 以避免冲突 (coolGray 在 Tailwind CSS v3.0 发布时被重命名为 gray)。

同样，您不能在 tailwind.config.ts 中定义 primary 颜色，因为它会与模块定义的 primary 颜色冲突。

建议您在组件和页面中使用这些颜色，例如 text-primary-500 dark:text-primary-400、bg-gray-100 dark:bg-gray-900 等，以便您的应用在更改 app.config.ts 时自动适应。

primary 颜色还有一个 DEFAULT 色调，它根据主题而变化。在浅色模式下为 500，在深色模式下为 400。您可以在组件和页面中用作快捷方式，例如 text-primary、bg-primary、focus-visible:ring-primary 等。

智能安全列表

具有 color 属性的组件，例如 头像、徽章、按钮、输入框（继承自 选择框 和 选择菜单）、单选按钮组、复选框、开关、范围 和 通知 默认情况下将使用 primary 颜色，但会处理在您的 tailwind.config.ts 中定义的所有颜色或默认的 Tailwind CSS 颜色。

这些组件的变体类使用类似 bg-{color}-500 dark:bg-{color}-400 的语法定义，因此它们可以与任何颜色一起使用。但是，这意味着 Tailwind 找不到这些类，因此不会生成相应的 CSS。

该模块使用 Tailwind CSS 安全列表 功能来强制生成所有 primary 颜色的类，因为它默认是所有组件的默认颜色。

然后，该模块会自动检测您何时使用具有颜色的组件，并为您将其安全列入列表。这意味着如果您对按钮组件使用 red 颜色，则 red 颜色类将仅对按钮组件进行安全列入列表。这将使 CSS 包大小尽可能小。

有一种情况是您可能想要强制安全列入某个颜色。例如，如果您已在 app.config.ts 中将按钮组件的默认颜色设置为 orange。

app.config.ts
export default defineAppConfig({
  ui: {
    button: {
      default: {
        color: 'orange'
      }
    }
  }
})

这将在使用默认的 <UButton /> 时应用橙色。您需要在 nuxt.config.ts 的 ui 选项中手动安全列入此颜色，因为我们无法自动检测它。您可以通过 safelistColors 选项来完成，该选项默认为 ['primary']。

nuxt.config.ts
export default defineNuxtConfig({
  ui: {
    safelistColors: ['orange']
  }
})

这也可能发生在您将动态颜色绑定到组件时：<UBadge :color="color" />、<UAvatar :chip-color="statuses[user.status]" /> 等。在这种情况下，您也需要手动安全列入可能的颜色值。

组件

app.config.ts

您可以在自己的 app.config.ts 中覆盖组件配置。

app.config.ts
export default defineAppConfig({
  ui: {
    container: {
      constrained: 'max-w-5xl'
    }
  }
})

每个组件的可用选项应该自动完成，您可以使用 IDE 的功能（例如 Cmd+Click）查看每个组件的默认值（这些文件可以在 src/runtime/ui.config/ 中找到）。

感谢 tailwind-merge，app.config.ts 会智能地与默认配置合并。这意味着您不必重写所有内容。

您可以在 app.config.ts 中将 strategy 设置为 override 来更改此行为。

app.config.ts
export default defineAppConfig({
  ui: {
    strategy: 'override',
    button: {
      color: {
        white: {
          solid: 'bg-white dark:bg-gray-900'
        }
      }
    }
  }
})

ui 属性

每个组件都有一个 ui 属性，允许您专门自定义所有内容。

<template>
  <UContainer :ui="{ constrained: 'max-w-2xl' }">
    <slot />
  </UContainer>
</template>
您可以在 Config 部分找到每个组件的默认类。

感谢 tailwind-merge，ui 属性会智能地与配置合并。这意味着您不必重写所有内容。

例如，FormGroup 组件的默认预设如下所示

{
  "label": {
    "base": "block font-medium text-gray-700 dark:text-gray-200"
  }
}

要更改 label 的字体，您只需要写

<UFormGroup name="email" label="Email" :ui="{ label: { base: 'font-semibold' } }" />

这将智能地将 font-medium 替换为 font-semibold，并防止任何类重复和任何类优先级问题。

您可以在 ui 属性内将 strategy 设置为 override 来更改此行为。

<UButton
  to="https://github.com/nuxt/ui"
  :ui="{
    strategy: 'override',
    color: {
      white: {
        solid: 'bg-white dark:bg-gray-900'
      }
    }
  }"
/>

class 属性

您也可以使用 class 属性向组件添加类。

<template>
  <UButton label="Button" class="rounded-full" />
</template>

同样，使用 tailwind-merge，这将智能地将类与 ui 属性和配置合并。

默认值

一些组件属性，例如 size、color、variant 等，具有默认值，您可以在 app.config.ts 中覆盖这些值。

app.config.ts
export default defineAppConfig({
  ui: {
    button: {
      default: {
        size: 'md',
        color: 'gray',
        variant: 'ghost'
      }
    }
  }
})

深色模式

所有组件在设计时都考虑了深色模式。

感谢 Tailwind CSS 深色模式 类策略和 @nuxtjs/color-mode 模块，您实际上不需要做任何事情。

您可以在 nuxt.config.ts 中将 preference 设置为 light 而不是 system 来禁用深色模式。

nuxt.config.ts
export default defineNuxtConfig({
  colorMode: {
    preference: 'light'
  }
})
如果您在更改此设置后仍然处于深色模式，则可能需要从浏览器本地存储中删除 nuxt-color-mode 条目。

您可以轻松地使用 @nuxtjs/color-mode 中的 useColorMode 组合器来构建颜色模式按钮。

<script setup lang="ts">
const colorMode = useColorMode()
const isDark = computed({
  get () {
    return colorMode.value === 'dark'
  },
  set () {
    colorMode.preference = colorMode.value === 'dark' ? 'light' : 'dark'
  }
})
</script>

<template>
  <ClientOnly>
    <UButton
      :icon="isDark ? 'i-heroicons-moon-20-solid' : 'i-heroicons-sun-20-solid'"
      color="gray"
      variant="ghost"
      aria-label="Theme"
      @click="isDark = !isDark"
    />
    <template #fallback>
      <div class="w-8 h-8" />
    </template>
  </ClientOnly>
</template>

图标

感谢 @nuxt/icon，您可以将 200,000 多个现成的图标添加到您的 Nuxt 应用程序中，这些图标基于 Iconify。

您可以使用 https://icones.js.org 集合中的任何名称，例如 i- 前缀（例如，i-heroicons-cog），并使用

  • 任何组件中可用的 icon 属性
<template>
  <UButton icon="i-heroicons-magnifying-glass" />
</template>
  • UIcon 组件，可以在任何地方使用图标
<template>
  <UIcon name="i-heroicons-moon" class="w-5 h-5 text-primary-500" />
</template>

集合

强烈建议您使用以下命令在本地安装图标集合：

pnpm i @iconify-json/{collection_name}

例如，要使用 i-uil-github 图标，请使用 @iconify-json/uil 安装其集合。这样，图标就可以从本地或您的无服务器函数中提供服务，这在 SSR 和客户端上都更快、更可靠。

阅读有关 @nuxt/icon 文档中的自定义集合的更多信息。

默认值

您可以在 app.config.ts 中轻松替换所有组件的默认图标。

app.config.ts
export default defineAppConfig({
  ui: {
    button: {
      default: {
        loadingIcon: 'i-octicon-sync-24'
      }
    },
    input: {
      default: {
        loadingIcon: 'i-octicon-sync-24'
      }
    },
    select: {
      default: {
        loadingIcon: 'i-octicon-sync-24',
        trailingIcon: 'i-octicon-chevron-down-24'
      }
    },
    selectMenu: {
      default: {
        selectedIcon: 'i-octicon-check-24'
      }
    },
    notification: {
      default: {
        closeButton: {
          icon: 'i-octicon-x-24'
        }
      }
    },
    commandPalette: {
      default: {
        icon: 'i-octicon-search-24',
        loadingIcon: 'i-octicon-sync-24',
        selectedIcon: 'i-octicon-check-24',
        emptyState: {
          icon: 'i-octicon-search-24'
        }
      }
    },
    table: {
      default: {
        sortAscIcon: 'i-octicon-sort-asc-24',
        sortDescIcon: 'i-octicon-sort-desc-24',
        sortButton: {
          icon: 'i-octicon-arrow-switch-24'
        },
        loadingState: {
          icon: 'i-octicon-sync-24'
        },
        emptyState: {
          icon: 'i-octicon-database-24'
        }
      }
    },
    pagination: {
      default: {
        firstButton: {
          icon: 'i-octicon-chevron-left-24'
        },
        prevButton: {
          icon: 'i-octicon-arrow-left-24'
        },
        nextButton: {
          icon: 'i-octicon-arrow-right-24'
        },
        lastButton: {
          icon: 'i-octicon-chevron-right-24'
        }
      }
    },
    accordion: {
      default: {
        openIcon: 'i-octicon-chevron-down-24'
      }
    },
    breadcrumb: {
      default: {
        divider: 'i-octicon-chevron-right-24'
      }
    }
  }
})

安装

了解如何在您的应用程序中安装和配置 Nuxt UI。

快捷键

了解如何在您的应用程序中显示和定义键盘快捷键。