安装

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

设置

添加到 Nuxt 项目

安装 Nuxt UI 包

pnpm add @nuxt/ui
如果您正在使用 pnpm，请确保您在 .npmrc 文件中设置了shamefully-hoist=true在你的 .npmrc 文件中，或在你的项目根目录中安装 tailwindcss。

在你的 nuxt.config.ts 中添加 Nuxt UI 模块

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui']
})

在你的 CSS 中导入 Tailwind CSS 和 Nuxt UI

@import "tailwindcss";
@import "@nuxt/ui";
建议为 VSCode 安装Tailwind CSS IntelliSense扩展并添加以下设置
.vscode/settings.json
{
  "files.associations": {
    "*.css": "tailwindcss"
  },
  "editor.quickSuggestions": {
    "strings": "on"
  },
  "tailwindCSS.classAttributes": ["class", "ui"],
  "tailwindCSS.experimental.classRegex": [
    ["ui:\\s*{([^)]*)\\s*}", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
  ]
}

用 App 组件包裹您的应用程序

app.vue
<template>
  <UApp>
    <NuxtPage />
  </UApp>
</template>
App 组件提供全局配置，是 Toast、Tooltip 组件以及 Programmatic Overlays 正常工作所必需的。

使用 Nuxt 模板

要快速开始使用 Nuxt UI，你可以使用入门模板通过运行

终端
npm create nuxt@latest -- -t ui

你也可以从我们的 官方模板 开始

启动器

一个用于开始使用 Nuxt UI 的最小模板。

着陆页

一个由 Nuxt Content 驱动的现代着陆页模板。

文档

一个由 Nuxt Content 驱动的文档模板。

SaaS

一个由 Nuxt Content 驱动的 SaaS 模板，包含着陆页、定价、文档和博客。

Dashboard

一个带有多列布局的仪表板模板，用于构建复杂的管理界面。

聊天

一个由 Nuxt MDC 和 Vercel AI SDK 驱动的 AI 聊天机器人模板，用于构建你自己的聊天机器人。

作品集

一个由 Nuxt Content 驱动的时尚作品集模板，用于展示你的作品、技能和博客。

更新日志

一个由 Nuxt MDC 驱动的更新日志模板，用于显示你的 GitHub 仓库发布说明。

你可以使用 GitHub 上的 Use this template 按钮创建一个新仓库或使用 CLI

npm create nuxt@latest -- -t ui

选项

你可以通过在 nuxt.config.ts 中提供选项来自定义 Nuxt UI。

prefix

使用 prefix 选项更改组件的前缀。

  • 默认值: U
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    prefix: 'Nuxt'
  }
})

字体

使用 fonts 选项启用或禁用@nuxt/fonts模块。

  • 默认值: true
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    fonts: false
  }
})

colorMode

使用 colorMode 选项启用或禁用@nuxt/color-mode模块。

  • 默认值: true
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    colorMode: false
  }
})

theme.colors

使用 theme.colors 选项定义用于生成组件主题的动态颜色别名。

  • 默认值: ['primary', 'secondary', 'success', 'info', 'warning', 'error']
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      colors: ['primary', 'error']
    }
  }
})
在主题部分了解更多关于颜色定制和主题的信息。

theme.transitions

使用 theme.transitions 选项启用或禁用组件上的过渡。

  • 默认值: true
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      transitions: false
    }
  }
})
此选项会在具有悬停或激活状态的组件上添加 transition-colors 类。

theme.defaultVariants

使用 theme.defaultVariants 选项覆盖组件的默认 color 和 size 变体。

  • 默认值: { color: 'primary', size: 'md'}
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      defaultVariants: {
        color: 'neutral',
        size: 'sm'
      }
    }
  }
})

theme.prefix 4.2+

使用 theme.prefix 选项配置你在 Tailwind CSS 导入中设置的相同前缀。这确保 Nuxt UI 组件使用正确的前缀工具类和 CSS 变量。

export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      prefix: 'tw'
    }
  }
})
你可能需要启用 fonts.processCSSVariables 才能将前缀选项与 @nuxt/fonts 模块一起使用
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      prefix: 'tw'
    }
  },
  fonts: {
    processCSSVariables: true
  }
})

这将自动为 Nuxt UI 组件主题中的所有 Tailwind 工具类和 CSS 变量添加前缀

<!-- Without prefix -->
<button class="px-2 py-1 text-xs hover:bg-primary/75">Button</button>

<!-- With prefix: tw -->
<button class="tw:px-2 tw:py-1 tw:text-xs tw:hover:bg-primary/75">Button</button>
了解更多关于在 Tailwind CSS 文档中使用前缀的信息。

mdc

即使未安装 @nuxtjs/mdc 或 @nuxt/content，使用 mdc 选项也会强制导入 Nuxt UI <Prose> 组件。

  • 默认值: false
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    mdc: true
  }
})

内容

即使未安装 @nuxt/content（@nuxtjs/mdc 由 @nuxt/content 安装），使用 content 选项也会强制导入 Nuxt UI <Prose> 和 <UContent> 组件。

  • 默认值: false
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    content: true
  }
})

experimental.componentDetection 4.1+

使用 experimental.componentDetection 选项启用自动组件检测以进行摇树优化。此功能会扫描你的源代码以检测实际使用的组件，并仅为这些组件（包括其依赖项）生成必要的 CSS。

  • 默认值: false
  • 类型: boolean | string[]

启用自动检测

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    experimental: {
      componentDetection: true
    }
  }
})

包含用于动态使用的额外组件

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    experimental: {
      componentDetection: ['Modal', 'Dropdown', 'Popover']
    }
  }
})
当提供组件名称数组时，自动检测会被启用，并且这些组件（及其依赖项）将保证被包含在内。这对于像 <component :is="..." /> 这样无法进行静态分析的动态组件非常有用。

持续发布

Nuxt UI 使用pkg.pr.new进行持续预览发布，为开发者提供即时访问最新功能和错误修复的能力，无需等待官方发布。

所有对 v4 分支的提交和 PR 都会创建自动预览发布。通过将你的包版本替换为特定的提交哈希或 PR 号来使用它们。

package.json
{
  "dependencies": {
-   "@nuxt/ui": "^4.0.0",
+   "@nuxt/ui": "https://pkg.pr.new/@nuxt/ui@4c96909",
  }
}
pkg.pr.new 将自动在 PR 上评论安装 URL，方便测试更改。

简介

Nuxt UI 是一个全面的 Vue 和 Nuxt 应用程序 UI 库，提供了一系列完全样式化和可访问的组件。

迁移

从 Nuxt UI v3 迁移到 Nuxt UI v4 的综合指南。