Nuxt UI——快速入手网站首页 技术杂谈

Nuxt UI——快速入手

樋口 2026-07-02 00:01:05

简介Nuxt UI——快速入手

Nuxt UI简介

本文基于Nuxt UI v2.21.0版本官方文档编写

介绍

Nuxt UI 是一个模块，它提供了一组 Vue 组件以及使用 Tailwind CSS 和 Headless UI 构建的可组合组件，以帮助您构建美观且易于访问的用户界面。

它的目标是在构建 Nuxt 应用程序时提供与用户界面相关的一切。其中包括组件、图标、颜色、暗模式以及键盘快捷键。

特点

基于 Headless UI 与 Tailwind CSS 创建
通过 Nuxt App Config 支持 HMR（热模块替换）
支持暗黑模式
支持LTR（从左到右）和RTL（从右到左）语言
键盘快捷键
包含图标库
完全类型化
Figma 设计套件Figma Kit

相关项

Nuxt

Nuxt.js是一个基于Vue.js的通用应用框架，用于构建Web应用。它简化了Vue.js应用的创建过程，并提供了一系列内置功能，使得开发者可以更快速、更轻松地开发复杂的Web应用。

以下是Nuxt.js的一些主要特点：

服务器端渲染（SSR）：Nuxt.js支持服务器端渲染，这有助于提高应用的性能和SEO（搜索引擎优化）。
静态站点生成：可以生成静态HTML文件，适用于不需要服务器端渲染的场景，如博客、文档等。
自动路由：根据页面目录结构自动生成路由，无需手动配置。
Vuex集成：内置了对Vuex的支持，方便状态管理。
模块化：提供了丰富的模块，如 Tailwind CSS、Axios、PWA等，可以轻松集成到项目中。
开发工具：提供了热模块替换（HMR）、开发服务器等开发工具，提升了开发体验。
类型支持：支持TypeScript，提供了更好的类型检查和开发体验。
插件系统：可以通过插件扩展Nuxt.js的功能。
社区支持：拥有活跃的社区，提供了大量的资源、教程和插件。
易于部署：可以轻松部署到各种平台，如Netlify、Vercel、GitHub Pages等。

Nuxt.js适用于各种类型的Web应用，从简单的静态站点到复杂的交互式应用。它的设计理念是让开发者专注于业务逻辑，而不是繁琐的配置和基础设施。通过Nuxt.js，开发者可以更高效地构建现代化、高性能的Web应用。

color-mode

Nuxt.js 的 color-mode 是一个内置模块，用于在应用中实现主题切换功能，允许用户在预设的颜色模式（如浅色模式、深色模式等）之间进行切换。这个模块简化了主题切换的实现过程，使得开发者可以轻松地为应用添加颜色模式切换功能。

以下是color-mode的一些主要特点：

预设模式：支持多种预设颜色模式，如 light（浅色模式）和 dark（深色模式）。
自动检测：可以自动检测用户系统的颜色偏好，并相应地应用颜色模式。
持久化：用户选择的颜色模式会被持久化存储，以便在下次访问时保持一致。
响应式：颜色模式的变化是响应式的，可以在应用运行时动态切换。
自定义：允许开发者自定义颜色模式，不仅限于浅色和深色。

tailwindcss

Tailwind CSS 是一个实用优先（utility-first）的 CSS 框架，用于快速构建自定义用户界面。与传统的 CSS 框架不同，Tailwind 不提供预定义的组件和样式，而是提供了一系列低级别的、可组合的实用类，允许开发者直接在 HTML 中应用样式。

以下是tailwind css的一些主要特点：

实用优先：Tailwind 提供了大量可以直接应用于 HTML 元素的实用类，如颜色、字体、间距、边框等，减少了编写自定义 CSS 的需求。
响应式设计：内置了响应式设计功能，可以通过简单的类名后缀来为不同屏幕尺寸定义样式。
主题定制：允许开发者自定义设计主题，包括颜色、字体、断点等，以适应项目需求。
高效开发：通过直接在 HTML 中应用样式，减少了在 CSS 和 JavaScript 之间的切换，提高了开发效率。
可维护性：由于样式是直接应用于 HTML 的，因此可以更容易地理解和维护。
插件生态系统：拥有丰富的插件生态系统，可以扩展 Tailwind 的功能，如添加新的实用类、组件等。

headlessui

Headless UI 是一个由 Tailwind Labs 创建的库，它提供了一组完全无样式、可访问的 UI 组件，旨在与 Tailwind CSS 配合使用。这些组件是“无头”的，意味着它们不包含任何默认样式，允许开发者完全控制组件的外观，同时确保组件的语义和可访问性。

以下是headless ui的一些主要特点：

无样式：组件不包含任何默认样式，允许开发者使用 Tailwind CSS 或其他 CSS 框架来定制样式。
可访问性：组件设计考虑了可访问性，确保在使用键盘、屏幕阅读器等辅助技术时也能正常工作。
易集成：与 Tailwind CSS 无缝集成，但也适用于其他 CSS 框架或自定义样式。
响应式：组件支持响应式设计，适应不同屏幕尺寸和设备。
组件丰富：包括模态框、下拉菜单、切换开关、标签页、对话框等常用 UI 组件。

vueuse

VueUse 是一个基于 Vue 3 的实用函数库，它提供了一系列用于常见任务的可重用 Composition API 组件和函数。这个库的目的是简化 Vue 3 开发中的一些常见操作，使得开发者可以更轻松地实现各种功能，同时保持代码的清晰和可维护性。

VueUse 的主要特点包括：

丰富的实用函数：涵盖了从状态管理、生命周期钩子、响应式引用到更复杂的操作（如拖放、滚动、窗口大小变化等）的各种实用函数。
易于集成：由于它是专门为 Vue 3 设计的，因此可以无缝地集成到 Vue 3 项目中，与 Vue 的其他功能完美配合。
类型安全：VueUse 利用 TypeScript 提供了完整的类型定义，使得在使用这些函数时能够享受到类型安全的优势。
可扩展性：允许开发者根据需要自定义和扩展功能。
社区驱动：作为一个开源项目，VueUse 拥有一个活跃的社区，不断有新的功能和改进被贡献进来。

安装

对于已有的Nuxt项目

安装nuxt ui到本地

npx nuxi@latest module add ui

添加模组到nuxt项目中

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

对于未创建的Nuxt项目

Nuxt Starter 模板可让您轻松开始使用 Nuxt UI。 Nuxt Starter 模板可通过 nuxi init 命令获得。

npx nuxi@latest init -t ui

模组

Nuxt UI在安装时会自动安装@nuxt/icon ， @nuxtjs/tailwindcss 和 @nuxtjs/color-mode，如果以前安装过这些模块和依赖项，则应将其从模块和依赖项中移除。

@nxut/icon

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

Iconify Design: All popular icon sets, one framework.

@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 暗夜模式的策略，该模块可以提供开箱即用的暗夜模式支持。

TypeScript 类型定义

这些模块由 TypeScript 编写，为所有Component组件和nuxt中的Composables可组合函数提供了类型定义。这些组件和可组合函数的类型定义可以通过查看nuxt/ui仓库的源代码获取。

同时，也可以通过 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，但这样做可以让您获得Props的自动验证和补全功能。

我们已设法根据您的自定义配置提供了诸如color（颜色）、size（大小）、variant（变体）等属性的动态类型定义。例如，当您需要创建一个带有自定义颜色custom和自定义变体subtle的按钮组件时，我们会建议您根据以下内容进行设置。

// app.config.ts
export default defineAppConfig({
  ui: {
    button: {
      color: {
        custom: {
          subtle: '...'
        }
      }
    }
  }
})

IntelliSense

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

Tailwind CSS IntelliSense 是一个为 Tailwind CSS 提供智能提示和自动完成功能的扩展，主要集成在代码编辑器中，如 Visual Studio Code。这个扩展旨在提高开发者在使用 Tailwind CSS 进行开发时的效率和体验。

您可以在 @nuxtjs/tailwindcss 模块文档中阅读更多关于如何设置的信息，但总的来说，您需要在 .vscode/settings.json 中添加以下内容：

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

您可以这样用 TypeScript 编写 tailwind.config：

import type { Config } from 'tailwindcss'

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

如果这样做，您需要在 .vscode/settings.json 中添加以下内容：

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

请注意，默认情况下，在 app.config.ts 中编写类时，该扩展将不起作用。

此外，您可能希望在 SFC 中的对象上使用 IntelliSense，即以 /*ui*/ 作为前缀。

要启用这两项功能，您可以在 .vscode/settings.json 中添加以下内容：

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

使用 IntelliSense 的 SFC 示例（注意前缀 /*ui*/，同样适用于 ref()）：

这个功能通常用于组件ui的设置，通过导入该扩展将有所便利

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

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

您还可以在 .vscode/settings.json 中添加以下内容，以便在使用 ui props时启用智能提示：

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

Key	Default	Description
`prefix`	`u`	定义导入组件的前缀（如Table组件名为UTable）。
`global`	`false`	是否在全局范围内公开组件。
`safelistColors`	`['primary']`	指定某些颜色类名不被 Tailwind 的purge（清除）功能移除
`disableGlobalStyles`	`false`	禁用模块注入的 global CSS styles。