安装

模板
了解如何在 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，您可以使用starter template（入门模板）通过运行

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

您还可以从我们的 官方模板 开始

启动器

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

着陆页

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

文档

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

SaaS

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

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'
      }
    }
  }
})

mdc

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

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

内容

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

  • 默认值：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。