安装 - Nuxt UI - Nuxt 框架

设置

添加到 Nuxt 项目

将 @nuxt/ui 模块添加到您的项目

npx nuxi@latest module add ui

将其添加到您的 nuxt.config.ts 文件中的 modules 部分

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@nuxt/ui']
})

就是这样！您现在可以在您的 Nuxt 应用中使用所有组件和可组合函数 ✨

使用 Nuxt 启动器

Nuxt 启动器模板使您可以轻松开始使用 Nuxt UI。Nuxt 启动器模板可通过 nuxi init 命令获得。

npx nuxi@latest init -t ui

请查看 nuxt/starter 了解详细信息。

模块

Nuxt UI 将自动为您安装 @nuxt/icon、@nuxtjs/tailwindcss 和 @nuxtjs/color-mode 模块。

如果您之前已安装这些模块，则应将其从您的 modules 和 dependencies 中删除。

`@nuxt/icon`

此模块安装是为了提供一种简单的方法，让您可以在应用程序中使用图标。您可以使用 UIcon 组件显示来自 Iconify 的任何图标。

您可以在主题部分中了解更多信息。

`@nuxtjs/tailwindcss`

此模块已预先配置，并将自动加载以下插件

请注意，@tailwindcss/aspect-ratio 插件会禁用默认的纵横比实用程序

aspect-auto
aspect-square
aspect-video

您可以通过将以下内容添加到您的 tailwind.config.ts 文件中重新启用它们

tailwind.config.ts

import type { Config } from 'tailwindcss'

export default <Partial<Config>>{
  theme: {
    extend: {
      aspectRatio: {
        auto: 'auto',
        square: '1 / 1',
        video: '16 / 9'
      }
    }
  }
}

`@nuxtjs/color-mode`

此模块安装是为了提供开箱即用的暗黑模式支持，这得益于 Tailwind CSS 暗黑模式 class 策略。

您可以在主题部分中了解更多信息。

TypeScript

此模块用 TypeScript 编写，并为所有组件和可组合函数提供类型。您可以查看源代码以查看所有可用的类型。

您可以在官方 Nuxt 文档中了解更多有关 TypeScript 的信息。

您可以通过从 #ui/types 导入它们来在您自己的组件中使用这些类型，例如在定义包装器组件时

<template>
  <UBreadcrumb :links="links">
    <template #icon="{ link }">
      <UIcon :name="link.icon" />
    </template>
  </UBreadcrumb>
</template>

<script setup lang="ts">
import type { BreadcrumbLink } from '#ui/types'

export interface Props {
  links: BreadcrumbLink[]
}

defineProps<Props>()
</script>

您不必自己使用 TypeScript，但这样做可以让您访问道具验证和自动完成功能。

我们已成功在 color、size、variant 等道具上提供动态类型，这些类型基于您的自定义配置。例如，当使用 Button 组件并使用以下 app.config.ts 文件时，系统会建议使用 custom 颜色和 subtle 变体

app.config.ts

export default defineAppConfig({
  ui: {
    button: {
      color: {
        custom: {
          subtle: '...'
        }
      }
    }
  }
})

您可以在主题部分中了解更多有关组件配置的信息。

IntelliSense

如果您使用的是 VSCode，则可以安装 Tailwind CSS IntelliSense 扩展程序，以便为类获得自动完成功能。

您可以在 @nuxtjs/tailwindcss 模块文档中了解更多关于如何设置它的信息，但概括地说，您需要将以下内容添加到您的 .vscode/settings.json 文件中

.vscode/settings.json

{
  "files.associations": {
      "*.css": "tailwindcss"
  },
  "editor.quickSuggestions": {
      "strings": true
  }
}

您可以像这样用 TypeScript 编写您的 tailwind.config 文件

tailwind.config.ts

import type { Config } from 'tailwindcss'

export default <Partial<Config>> {
  content: [
    'docs/content/**/*.md'
  ]
}

如果您这样做，则需要将以下内容添加到您的 .vscode/settings.json 文件中

.vscode/settings.json

{
  "tailwindCSS.experimental.configFile": "tailwind.config.ts"
}

请注意，扩展程序默认情况下不会在您在 app.config.ts 文件中编写类时工作。

此外，您可能希望在 SFC 中使用 /*ui*/ 前缀来为对象提供 IntelliSense。

要启用这两个功能，您可以将以下内容添加到您的 .vscode/settings.json 文件中

.vscode/settings.json

{
  "tailwindCSS.experimental.classRegex": [
    ["ui:\\s*{([^)]*)\\s*}", "[\"'`]([^\"'`]*).*?[\"'`]"],
    ["/\\*\\s?ui\\s?\\*/\\s*{([^;]*)}", ":\\s*[\"'`]([^\"'`]*).*?[\"'`]"]
  ]
}

一个使用 IntelliSense 的 SFC 示例（请注意 /*ui*/ 前缀，也适用于 ref()）

example.vue

<template>
  <UCard :ui="ui" />
</template>

<script setup lang="ts">
const ui = /* ui */ {
  background: 'bg-white dark:bg-slate-900'
}
</script>

您还可以将以下内容添加到您的 .vscode/settings.json 文件中，以便在使用 ui 道具时启用 IntelliSense

.vscode/settings.json

{
  "tailwindCSS.classAttributes": [
    "class",
    "className",
    "ngClass",
    "ui"
  ]
}

选项

键	默认值	描述
`prefix`	`u`	定义导入的组件的前缀。
`global`	`false`	全局暴露组件。
`safelistColors`	`['primary']`	强制列入安全列表的颜色，以防需要被清除。
`disableGlobalStyles`	`false`	禁用模块注入的全局 CSS 样式。

像这样在您的 nuxt.config.ts 文件中配置选项

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  ui: {
    global: true
  }
})

Edge

要使用 dev 分支上推送的最新更新，您可以使用 @nuxt/ui-edge。

将您的 package.json 文件更新为以下内容

package.json

{
  "devDependencies": {
-   "@nuxt/ui": "^2.11.0"
+   "@nuxt/ui": "npm:@nuxt/ui-edge@latest"
  }
}

然后运行 pnpm install、yarn install 或 npm install。

简介

Nuxt 的完全样式化和可自定义的组件。

主题

了解如何自定义组件的外观和感觉。