安装

模板
了解如何在 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 组件以及程序化叠加层是必需的。

使用 Nuxt 模板

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

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

您也可以从我们的 官方模板 中选择一个开始

启动器

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

着陆页

一个由 Nuxt Content 提供支持的现代登录页面模板。

文档

一个由 Nuxt Content 提供支持的文档模板。

SaaS

一个由 Nuxt Content 提供支持的 SaaS 模板，包含登录、定价、文档和博客。

Dashboard

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

聊天

一个 AI 聊天机器人模板，由 Nuxt MDC 和 Vercel AI SDK 提供支持，用于构建您自己的聊天机器人。

作品集

一个时尚的个人作品集模板，由 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
  }
})

持续发布

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。