安装

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

设置

添加到 Vue 项目

安装 Nuxt UI 包

pnpm add @nuxt/ui

yarn add @nuxt/ui

npm install @nuxt/ui

bun 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()
  ]
})

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

export default defineConfig({
  plugins: [
    laravel({
      input: ['resources/js/app.ts'],
      refresh: true
    }),
    vue({
      template: {
        transformAssetUrls: {
          base: null,
          includeAbsolute: false
        }
      }
    }),
    ui({
      inertia: true
    })
  ]
})

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

export default defineConfig({
  plugins: [
    adonisjs({
      entrypoints: ['inertia/app/app.ts'],
      reload: ['resources/views/**/*.edge']
    }),
    inertia(),
    vue(),
    ui({
      inertia: true
    })
  ]
})

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

import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import ui from '@nuxt/ui/vue-plugin'
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'
import { createApp, h } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'Laravel x Nuxt UI'

createInertiaApp({
  title: title => (title ? `${title} - ${appName}` : appName),
  resolve: name =>
    resolvePageComponent(
      `./pages/${name}.vue`,
      import.meta.glob<DefineComponent>('./pages/**/*.vue')
    ),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(ui)
      .mount(el)
  }
})

import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import ui from '@nuxt/ui/vue-plugin'
import { resolvePageComponent } from '@adonisjs/inertia/helpers'
import { createApp, h } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'AdonisJS x Nuxt UI'

createInertiaApp({
  title: title => (title ? `${title} - ${appName}` : appName),
  resolve: name =>
    resolvePageComponent(
      `../pages/${name}.vue`,
      import.meta.glob<DefineComponent>('../pages/**/*.vue')
    ),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(ui)
      .mount(el)
  }
})

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

@import "tailwindcss";
@import "@nuxt/ui";

@import "tailwindcss";
@import "@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')

import '../css/app.css'
import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import ui from '@nuxt/ui/vue-plugin'
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'
import { createApp, h } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'Laravel x Nuxt UI'

createInertiaApp({
  title: title => (title ? `${title} - ${appName}` : appName),
  resolve: name =>
    resolvePageComponent(
      `./pages/${name}.vue`,
      import.meta.glob<DefineComponent>('./pages/**/*.vue')
    ),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(ui)
      .mount(el)
  }
})

import '../css/app.css'
import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import ui from '@nuxt/ui/vue-plugin'
import { resolvePageComponent } from '@adonisjs/inertia/helpers'
import { createApp, h } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'AdonisJS x Nuxt UI'

createInertiaApp({
  title: title => (title ? `${title} - ${appName}` : appName),
  resolve: name =>
    resolvePageComponent(
      `../pages/${name}.vue`,
      import.meta.glob<DefineComponent>('../pages/**/*.vue')
    ),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(ui)
      .mount(el)
  }
})

建议为 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>

<template>
  <UApp>
    <!-- Your content goes here -->
  </UApp>
</template>

<template>
  <UApp>
    <!-- Your content goes here -->
  </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>

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1">
    @inertiaHead
    @vite('resources/js/app.ts')
  </head>
  <body>
    <div class="isolate">
        @inertia
    </div>
  </body>
</html>

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1">
    @inertiaHead()
    @vite(['inertia/app/app.ts', `inertia/pages/${page.component}.vue`])
  </head>
  <body>
    @inertia({ class: 'isolate' })
  </body>
</html>

这确保了样式限定在你的应用程序中，并防止了叠加层和堆叠上下文的问题。

使用 Vue 模板

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

终端

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

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

启动器

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

Dashboard

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

入门 Adonis

一个用于 AdonisJS 的最小 Nuxt UI 模板，使用 Inertia.js。

入门 Laravel

一个用于 Laravel 的最小 Nuxt UI 模板，使用 Inertia.js。

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

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

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

选项

你可以通过在你的 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 都会创建自动预览发布。通过将你的包版本替换为特定的提交哈希或 PR 号来使用它们。

package.json

{
  "dependencies": {
-   "@nuxt/ui": "^4.0.0",
+   "@nuxt/ui": "https://pkg.pr.new/@nuxt/ui@4c96909",
  }
}

pkg.pr.new 将自动在 PR 上评论安装 URL，方便测试更改。