安装PRO

启动器演练场
了解如何在 Vue 应用程序中安装和配置 Nuxt UI Pro。

Nuxt UI Pro 是一系列基于 Nuxt UI 构建的 Vue 组件、可组合函数和工具,专注于结构和布局,旨在用作应用程序的构建块。

虽然 Nuxt UI 是免费开源的,但 Nuxt UI Pro 是一款高级产品,有助于支持 Nuxt OSS 的开发,请查阅许可部分了解更多信息。

设置

添加到 Vue 项目

安装 Nuxt UI Pro 包

pnpm add @nuxt/ui-pro
如果您正在使用 pnpm,请确保您在 .npmrc 文件中设置了shamefully-hoist=true或者在项目根目录中安装 tailwindcssvue-router@unhead/vue

vite.config.ts 中添加 Nuxt UI Pro Vite 插件

vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import uiPro from '@nuxt/ui-pro/vite'

export default defineConfig({
  plugins: [
    vue(),
    uiPro()
  ]
})
Nuxt UI 注册了 unplugin-auto-importunplugin-vue-components,这将生成 auto-imports.d.tscomponents.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"
      ]
    }
  }
}

在您的 main.ts 中使用 Nuxt UI Vue 插件

main.ts
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')
如果您正在使用Inertia.js,您可以跳过 vue-router 设置,因为 Inertia 提供了自己的路由系统。

在您的 CSS 中导入 Tailwind CSS 和 Nuxt UI Pro

assets/main.css
@import "tailwindcss";
@import "@nuxt/ui-pro";
在您的 main.ts 中导入 CSS 文件。
main.ts
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 组件包裹您的应用程序

App.vue
<template>
  <UApp>
    <RouterView />
  </UApp>
</template>
App 组件设置了全局配置,并且是 ToastTooltip编程式覆盖所必需的。

isolate 类添加到您的根容器中

index.html
<!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>
这确保样式作用于您的应用程序,并防止与覆盖层和堆叠上下文相关的问题。

从 Nuxt UI 升级

@nuxt/ui 包替换为 @nuxt/ui-pro

package.json
{
  "dependencies": {
-   "@nuxt/ui": "^3.0.0",
+   "@nuxt/ui-pro": "^3.0.0",
  }
}

@nuxt/ui vite 插件替换为 @nuxt/ui-pro

vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
- import ui from '@nuxt/ui/vite'
+ import uiPro from '@nuxt/ui-pro/vite'

export default defineConfig({
  plugins: [
    vue(),
-   ui(),
+   uiPro()
  ]
})

@nuxt/ui CSS 导入替换为 @nuxt/ui-pro

assets/css/main.css
@import "tailwindcss";
- @import "@nuxt/ui";
+ @import "@nuxt/ui-pro";

使用官方模板

您可以使用我们的官方 Vue 模板开始

Dashboard

一个多列布局的 Vue 仪表盘模板。

Starter Vue

一个用于 Vue 的极简 Nuxt UI Pro 设置。

Starter Adonis

一个用于 AdonisJS 和 Inertia.js 的极简 Nuxt UI Pro 设置。

Starter Laravel

一个用于 Laravel 和 Inertia.js 的极简 Nuxt UI Pro 设置。

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

npx giget@latest gh:nuxt-ui-pro/starter-vue my-vue-starter

创建目录后,您可以使用 npm run dev 命令安装依赖并启动开发服务器。

选项

您可以通过在 vite.config.ts 中提供选项来定制 Nuxt UI Pro。

prefix

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

  • 默认值: U
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import uiPro from '@nuxt/ui-pro/vite'

export default defineConfig({
  plugins: [
    vue(),
    uiPro({
      prefix: 'Nuxt'
    })
  ]
})

ui

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

vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import uiPro from '@nuxt/ui-pro/vite'

export default defineConfig({
  plugins: [
    vue(),
    uiPro({
      ui: {
        colors: {
          primary: 'green',
          neutral: 'slate'
        }
      }
    })
  ]
})

uiPro

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

vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import uiPro from '@nuxt/ui-pro/vite'

export default defineConfig({
  plugins: [
    vue(),
    uiPro({
      uiPro: {
        pageHero: {
          slots: {
            title: 'font-light'
          }
        }
      }
    })
  ]
})

colorMode

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

  • 默认值: true
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import uiPro from '@nuxt/ui-pro/vite'

export default defineConfig({
  plugins: [
    vue(),
    uiPro({
      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 uiPro from '@nuxt/ui-pro/vite'

export default defineConfig({
  plugins: [
    vue(),
    uiPro({
      theme: {
        colors: ['primary', 'error']
      }
    })
  ]
})
在主题部分了解更多关于颜色定制和主题的信息。

theme.transitions

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

  • 默认值: true
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import uiPro from '@nuxt/ui-pro/vite'

export default defineConfig({
  plugins: [
    vue(),
    uiPro({
      theme: {
        transitions: false
      }
    })
  ]
})
此选项会在具有悬停或激活状态的组件上添加 transition-colors 类。

theme.defaultVariants

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

  • 默认值: { color: 'primary', size: 'md' }
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import uiPro from '@nuxt/ui-pro/vite'

export default defineConfig({
  plugins: [
    vue(),
    uiPro({
      theme: {
        defaultVariants: {
          color: 'neutral',
          size: 'sm'
        }
      }
    })
  ]
})

inertia

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

vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import uiPro from '@nuxt/ui-pro/vite'

export default defineConfig({
  plugins: [
    vue(),
    uiPro({
      inertia: true
    })
  ]
})
When using this option, vue-router is not required as Inertia.js provides its own routing system. The components that would normally use RouterLink will automatically use Inertia's InertiaLink component instead.

license

使用 license 选项覆盖从 NUXT_UI_PRO_LICENSE 环境变量读取许可证密钥的默认行为。

vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import uiPro from '@nuxt/ui-pro/vite'

export default defineConfig({
  plugins: [
    vue(),
    uiPro({
      license: process.env.MY_ENVIRONMENT_VARIABLE
    })
  ]
})
请勿将您的许可证密钥提交到公共仓库,以避免暴露。

持续发布

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

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

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