安装

模板
了解如何在 Vue 应用程序中安装和配置 Nuxt UI，兼容纯 Vite 和 Inertia。

设置

添加到 Vue 项目

安装 Nuxt UI 包

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

在你的 vite.config.ts 中添加 Nuxt UI Vite 插件

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui()
  ]
})
Nuxt UI 注册了 unplugin-auto-import 和 unplugin-vue-components，它们将生成 auto-imports.d.ts 和 components.d.ts 类型声明文件。你可能希望将它们添加到 gitignore，并添加到你的 tsconfig 中。
tsconfig.app.json
{
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue", "auto-imports.d.ts", "components.d.ts"]
}
.gitignore
# Auto-generated type declarations
auto-imports.d.ts
components.d.ts
在内部，Nuxt UI 依赖自定义别名来解析主题类型。如果你正在使用 TypeScript，你应该在你的 tsconfig 中添加一个别名，以在你的 vite.config.ts 中启用自动补全。
tsconfig.node.json
{
  "compilerOptions": {
    "paths": {
      "#build/ui": [
        "./node_modules/@nuxt/ui/.nuxt/ui"
      ]
    }
  }
}

使用 Nuxt UI Vue 插件

import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import ui from '@nuxt/ui/vue-plugin'
import App from './App.vue'

const app = createApp(App)

const router = createRouter({
  routes: [],
  history: createWebHistory()
})

app.use(router)
app.use(ui)

app.mount('#app')

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

@import "tailwindcss";
@import "@nuxt/ui";
在你的入口文件中导入 CSS 文件。
import './assets/main.css'

import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import ui from '@nuxt/ui/vue-plugin'
import App from './App.vue'

const app = createApp(App)

const router = createRouter({
  routes: [],
  history: createWebHistory()
})

app.use(router)
app.use(ui)

app.mount('#app')
建议为 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 组件包裹您的应用程序

<template>
  <UApp>
    <RouterView />
  </UApp>
</template>
App 组件设置全局配置，并且是 Toast、Tooltip 和 程序化覆盖层 所必需的。

将 isolate 类添加到你的根容器

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Nuxt UI</title>
  </head>
  <body>
    <div id="app" class="isolate"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>
这确保样式作用于你的应用程序，并防止覆盖层和堆叠上下文的问题。

使用 Vue 模板

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

终端
npm create nuxt@latest -- --no-modules -t ui-vue

你也可以使用我们的 官方模板 之一开始

启动器

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

Dashboard

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

Adonis 启动器

一个使用 Inertia.js 的 AdonisJS 极简 Nuxt UI 模板。

Laravel 启动器

一个使用 Inertia.js 的 Laravel 极简 Nuxt UI 模板。

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

npm create nuxt@latest -- --no-modules -t ui-vue

选项

你可以在你的 vite.config.ts 中提供选项来自定义 Nuxt UI。

prefix

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

  • 默认值：U
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({
      prefix: 'Nuxt'
    })
  ]
})

ui

使用 ui 选项为 Nuxt UI 提供配置。

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: {
        colors: {
          primary: 'green',
          neutral: 'slate'
        }
      }
    })
  ]
})

colorMode

使用 colorMode 选项启用或禁用 @vueuse/core 的颜色模式集成。

  • 默认值：true
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({
      colorMode: false
    })
  ]
})

theme.colors

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

  • 默认值：['primary', 'secondary', 'success', 'info', 'warning', 'error']
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({
      theme: {
        colors: ['primary', 'error']
      }
    })
  ]
})
在主题部分了解更多关于颜色定制和主题的信息。

theme.transitions

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

  • 默认值：true
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({
      theme: {
        transitions: false
      }
    })
  ]
})
此选项会在具有悬停或激活状态的组件上添加 transition-colors 类。

theme.defaultVariants

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

  • 默认值：{ color: 'primary', size: 'md' }
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({
      theme: {
        defaultVariants: {
          color: 'neutral',
          size: 'sm'
        }
      }
    })
  ]
})

inertia

使用 inertia 选项启用与Inertia.js.

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({
      inertia: true
    })
  ]
})
当使用此选项时，不需要 vue-router，因为 Inertia.js 提供了自己的路由系统。通常使用 RouterLink 的组件将自动使用 Inertia 的 InertiaLink 组件。

持续发布

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

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

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