maz-ui

Maz-UI v4 - Vue 与 Nuxt 组件库

Maz-UI 是一套功能全面、独立的组件库，适用于 Vue 3 和 Nuxt 3 应用，提供 50 多个可用于生产环境的组件、强大的主题功能、国际化支持以及出色的开发体验。

最新版本：4.9.3（截至 2026-08-03） 软件包：maz-ui | @maz-ui/nuxt | @maz-ui/themes | @maz-ui/translations | @maz-ui/icons

快速开始

Vue 3 安装

# Install core packages
pnpm add maz-ui @maz-ui/themes

# Or with npm
npm install maz-ui @maz-ui/themes

在 main.ts 中进行设置：

import { createApp } from 'vue'
import { MazUi } from 'maz-ui/plugins/maz-ui'
import { mazUi } from '@maz-ui/themes'
import { en } from '@maz-ui/translations'
import 'maz-ui/styles'
import App from './App.vue'

const app = createApp(App)

app.use(MazUi, {
  theme: { preset: mazUi },
  translations: { messages: { en } }
})

app.mount('#app')

使用组件：

<script setup>
import MazBtn from 'maz-ui/components/MazBtn'
import MazInput from 'maz-ui/components/MazInput'
import { ref } from 'vue'

const inputValue = ref('')
</script>

<template>
  <MazInput v-model="inputValue" label="Name" />
  <MazBtn color="primary">Submit</MazBtn>
</template>

Nuxt 3 安装

# Install Nuxt module
pnpm add @maz-ui/nuxt

在 nuxt.config.ts 中进行设置：

export default defineNuxtConfig({
  modules: ['@maz-ui/nuxt']
  // That's it! Auto-imports enabled 🎉
})

使用组件（无需导入）：

<script setup>
// Auto-imported composables
const theme = useTheme()
const toast = useToast()
const inputValue = ref('')
</script>

<template>
  
  <MazInput v-model="inputValue" label="Name" />
  <MazBtn color="primary" @click="toast.success('Submitted!')">
    Submit
  </MazBtn>
</template>

核心功能

🎨 组件（50+）

表单与输入：

• MazInput - 带验证状态的文本输入框
• MazSelect - 下拉选择框
• MazTextarea - 多行文本输入框
• MazCheckbox - 带标签的复选框
• MazRadio - 单选按钮
• MazSwitch - 切换开关
• MazSlider - 范围滑块
• MazInputPhoneNumber - 带验证的国际电话号码输入框
• MazInputCode - 代码/PIN 输入框
• MazInputPrice - 带格式化功能的货币输入框
• MazInputTags - 标签/标记输入框
• MazDatePicker - 日期选择器
• MazChecklist - 可搜索的清单

UI 元素：

• MazBtn - 带多种样式的按钮
• MazCard - 容器卡片
• MazBadge - 标签徽章
• MazAvatar - 用户头像
• MazIcon - 图标显示
• MazSpinner - 加载旋转图标
• MazTable - 带排序/分页功能的数据表格
• MazTabs - 标签页导航
• MazStepper - 步骤指示器
• MazPagination - 分页控件

覆盖层与模态框：

• MazDialog - 模态对话框
• MazDialogConfirm - 确认对话框
• MazDrawer - 滑出式抽屉
• MazBottomSheet - 移动端底部面板
• MazBackdrop - 覆盖层背景
• MazPopover - 浮动弹出框
• MazDropdown - 下拉菜单

反馈与动画：

• MazFullscreenLoader - 加载覆盖层
• MazLoadingBar - 进度条
• MazCircularProgressBar - 圆形进度条
• MazReadingProgressBar - 阅读进度指示器
• MazAnimatedText - 文本动画
• MazAnimatedElement - 元素动画
• MazAnimatedCounter - 数字计数动画
• MazCardSpotlight - 带聚光效果的卡片

布局与显示：

• MazCarousel - 图片轮播
• MazGallery - 图片库
• MazAccordion - 可折叠面板
• MazExpandAnimation - 展开/收起动画
• MazLazyImg - 懒加载图片
• MazPullToRefresh - 下拉刷新手势
• MazChart - Chart.js 集成

🔧 组合式函数（14+）

主题：

• useTheme() - 主题与深色模式管理

翻译：

• useTranslations() - 国际化管理

UI 交互：

• useToast() - Toast 通知
• useDialog() - 编程式对话框
• useWait() - 加载状态

实用工具：

• useBreakpoints() - 响应式断点
• useWindowSize() - 窗口尺寸
• useTimer() - 计时器/倒计时
• useFormValidator() - 表单验证（Valibot）
• useIdleTimeout() - 空闲状态检测
• useUserVisibility() - 页面可见性
• useSwipe() - 滑动手势
• useReadingTime() - 阅读时间计算
• useStringMatching() - 字符串工具
• useDisplayNames() - 本地化显示名称

📌 指令（5）

• v-tooltip - 工具提示
• v-click-outside - 外部点击检测
• v-lazy-img - 懒加载
• v-zoom-img - 图片缩放
• v-fullscreen-img - 全屏图片查看器

🔌 插件（4）

• AOS - 滚动动画
• Dialog - 无需模板的对话框
• Toast - 通知
• Wait - 全局加载状态

主要特性

✅ 独立组件 - 只导入所需内容，零冗余 ✅ 支持 SSR/SSG - 完整支持 Nuxt 3，并提供自动导入 ✅ TypeScript 优先 - 开箱即用的完整类型安全 ✅ 暗色模式 - 内置深色/浅色主题切换 ✅ 支持 Tree-Shaking - 优化打包体积 ✅ 响应式 - 移动端优先设计 ✅ 无障碍 - 符合 ARIA 标准的组件 ✅ 支持主题定制 - 4 个内置预设 + 自定义主题 ✅ i18n - 通过 @maz-ui/translations 支持多语言 ✅ 840+ 个图标 - 优化的 SVG 图标库 (@maz-ui/icons)

模板结构

Maz-UI 提供两套可用于生产环境的模板，按框架分类：

Vue 3 + Vite 模板 (templates/vue/)

• ✅ 纯 Vue 3 和 Vite
• ✅ 使用标准 fetch() API
• ✅ 显式导入所有依赖
• ✅ 不依赖特定框架
• ✅ 针对 SPA 开发进行了优化

适用场景：使用 Vite 构建 Vue 3 应用

可用模板：

• setup/vite.config.ts - 配置了自动导入的 Vite 配置
• components/form-basic.vue - 基本表单验证
• components/form-multi-step.vue - 带步骤条的多步表单
• components/dialog-confirm.vue - 对话框确认模式
• components/data-table.vue - 带分页、搜索和排序的数据表格

Nuxt 3 模板 (templates/nuxt/)

• ✅ 针对 Nuxt 3 优化
• ✅ 使用 $fetch（Nuxt 的 ofetch 封装器）
• ✅ 利用自动导入功能导入组件和组合式函数
• ✅ 展示 SSR 模式和服务端路由
• ✅ 针对全栈 Nuxt 开发进行了优化

适用场景：构建 Nuxt 3 应用

可用模板：

• setup/nuxt.config.ts - 配置了 Maz-UI 模块的 Nuxt 配置
• components/form-basic.vue - 基本表单验证（自动导入）
• components/form-multi-step.vue - 多步表单（自动导入）
• components/dialog-confirm.vue - 对话框模式（自动导入）
• components/data-table.vue - 支持响应式数据加载的数据表格

两套模板均：

• ✅ 修复所有验证、类型推断和分页问题
• ✅ 遵循框架最佳实践
• ✅ 可用于生产环境且经过全面测试
• ✅ 包含设置配置和组件示例

何时加载参考资料

根据要实现的功能加载参考文件。全部 21 个参考文件按用途分组，方便快速查找：

组件（4 个文件）

• components-forms.md - 构建表单、输入控件和验证，处理电话号码、日期、文件上传，以及使用 MazInput、MazSelect、MazCheckbox、MazDatePicker
• components-feedback.md - 添加加载指示器、进度条、动画、提示消息，以及使用 MazFullscreenLoader、MazCircularProgressBar、MazAnimatedText、MazCardSpotlight
• components-navigation.md - 实现标签页、步骤条、分页，以及使用 MazTabs、MazStepper、MazPagination
• components-layout.md - 使用卡片、抽屉、轮播图、图库，以及使用 MazCard、MazAccordion、MazDrawer、MazCarousel、MazGallery

设置与配置（2 个文件）

• setup-vue.md - 在 Vue 3 项目中设置 Maz-UI，使用解析器配置自动导入，配置 Vite/Webpack，优化性能
• setup-nuxt.md - 与 Nuxt 3 集成、模块配置、主题策略（hybrid/buildtime/runtime）、SSR/SSG 注意事项

核心功能（5 个文件）

• composables.md - 使用全部 14 个组合式函数：useToast、useTheme、useBreakpoints、useFormValidator、useTimer、useDialog、useTranslations 等
• directives.md - 添加指令：v-tooltip、v-click-outside、v-lazy-img、v-zoom-img、v-fullscreen-img
• plugins.md - 启用插件：AOS（滚动时播放动画）、Dialog、Toast、Wait（加载状态）
• resolvers.md - 至关重要：使用 MazComponentsResolver、MazDirectivesResolver、MazModulesResolver 配置自动导入，以实现最佳 Tree-Shaking
• translations.md - 实现多语言支持（内置 8 种语言）、自定义语言区域、延迟加载、SSR 水合

工具与集成（3 个文件）

• icons.md - 使用 @maz-ui/icons package（840+ 个图标）、MazIcon 组件、图标尺寸、颜色和动画
• cli.md - 使用 @maz-ui/cli（旧版 v3）、主题配置、迁移到 v4 主题系统
• mcp.md - 设置 Model Context Protocol 服务，以集成 AI 助手（Claude Code、Claude Desktop、Cursor、Windsurf）

高级主题（5 个文件）

• theming.md - 自定义主题、深色模式、配色方案、CSS 变量、4 个内置预设（mazUi、ocean、pristine、obsidian）
• performance.md - Bundle 优化、tree-shaking、延迟加载、代码拆分、将 bundle 大小从约 300KB 缩减至约 15KB
• ssr-ssg.md - 全面的 SSR/SSG 指南：主题策略、关键 CSS、防止 hydration、避免深色模式闪屏、静态站点生成
• accessibility.md - 符合 WCAG 2.1 AA 标准、键盘导航、屏幕阅读器支持、ARIA 属性、颜色对比度
• form-validation.md - 深入介绍 useFormValidator、Valibot 集成、5 种验证模式（lazy、aggressive、eager、blur、progressive）、TypeScript 类型推断

故障排除（2 个文件）

• migration-v4.md - 从 Maz-UI v3 升级到 v4、破坏性变更、API 变更、组件重命名、TypeScript 更新
• troubleshooting.md - 调试错误、常见问题、配置问题、SSR hydration、bundle 大小问题

6 个常见错误

1. 缺少主题插件错误

错误："useTheme must be used within MazUi plugin installation" 原因：未安装 MazUi 插件或已禁用主题 composable 修复：

// Vue
app.use(MazUi, { theme: { preset: mazUi } })

// Nuxt
export default defineNuxtConfig({
  mazUi: {
    composables: { useTheme: true },
    theme: { preset: 'maz-ui' }
  }
})

2. 自动导入不起作用（Nuxt）

错误：安装 Nuxt 模块后仍找不到组件/composable 原因：模块配置不正确或存在缓存问题 修复：

# Clear Nuxt cache
rm -rf .nuxt node_modules/.cache
pnpm install

验证 nuxt.config.ts：

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

3. 样式未应用

错误：组件已渲染，但没有样式 原因：未导入 CSS Vue 修复：

import 'maz-ui/styles' // Add this line

Nuxt 修复：

export default defineNuxtConfig({
  mazUi: {
    css: { injectMainCss: true } // Ensure this is true
  }
})

4. 组件的 TypeScript 错误

错误：Cannot find module 'maz-ui/components/MazBtn' 原因：缺少类型定义或导入路径不正确 修复：

// Correct import
import MazBtn from 'maz-ui/components/MazBtn'

// Or with auto-import (Nuxt)
// No import needed, just use <MazBtn>

确保 tsconfig.json 包含：

{
  "compilerOptions": {
    "types": ["maz-ui/types"]
  }
}

5. 电话号码输入框无法检测国家/地区

错误：MazInputPhoneNumber 无法检测国家/地区或显示了错误的旗帜 原因：缺少 libphonenumber-js 依赖，或未加载国家/地区数据 修复：

# Install peer dependency
pnpm add libphonenumber-js

<MazInputPhoneNumber
  v-model="phone"
  default-country-code="US"
  preferred-countries="['US', 'CA', 'GB']"
/>

6. 翻译未加载或显示原始键值

错误：翻译键显示为原始字符串，例如 inputPhoneNumber.phoneInput.example，而不是翻译后的文本 原因：

• 缺少 locale 导入
• 未正确等待延迟加载完成
• 语言文件异步加载失败
• 缺少 preloadFallback 配置
• SSR hydration 不匹配（Nuxt）

Vue 修复（立即加载）：

import { fr } from '@maz-ui/translations'

app.use(MazUi, {
  translations: {
    locale: 'fr',
    fallbackLocale: 'en',
    preloadFallback: true,
    messages: { fr } // Import immediately
  }
})

Vue 修复（延迟加载）：

app.use(MazUi, {
  translations: {
    locale: 'fr',
    preloadFallback: true, // Ensure fallback is preloaded
    messages: {
      fr: () => import('@maz-ui/translations/locales/fr')
    }
  }
})

// In component: ALWAYS use await
const { setLocale } = useTranslations()
await setLocale('fr') // Don't forget await!

Nuxt 修复（避免 hydration）：

import { fr } from '@maz-ui/translations'

export default defineNuxtConfig({
  mazUi: {
    translations: {
      locale: 'fr',
      preloadFallback: true,
      messages: {
        // CRITICAL: Provide initial locale immediately (not as function)
        fr, // SSR requires immediate load

        // Other languages can be lazy
        es: () => import('@maz-ui/translations/locales/es')
      }
    }
  }
})

错误处理：

<script setup>
const { setLocale } = useTranslations()
const toast = useToast()

async function switchLanguage(locale) {
  try {
    await setLocale(locale)
    toast.success(`Language changed to ${locale}`)
  } catch (error) {
    console.error('Translation loading error:', error)
    toast.error('Failed to load translations')
  }
}
</script>

了解更多：加载 references/translations.md，了解全面的 i18n 设置、延迟加载策略和生产环境模式。

Tree-Shaking 最佳实践

直接导入（优化效果最佳）：

// ✅✅✅ Best - smallest bundle
import MazBtn from 'maz-ui/components/MazBtn'
import { useToast } from 'maz-ui/composables/useToast'
import { vClickOutside } from 'maz-ui/directives/vClickOutside'

索引导入（效果良好）：

// ✅ Good - tree-shakable
import { MazBtn, MazInput } from 'maz-ui/components'
import { useToast, useTheme } from 'maz-ui/composables'

避免使用（无法 tree-shaking）：

// ❌ Imports everything
import * as MazUI from 'maz-ui'

高级主题

性能优化

通过合理使用导入和 tree-shaking，可将 Maz-UI 从约 300KB 优化至约 15KB。使用自动导入解析器（MazComponentsResolver、MazDirectivesResolver、MazModulesResolver）以优化 bundle 大小，通过动态导入延迟加载组件，并按功能拆分代码。加载 performance.md，了解全面的 bundle 优化策略。

SSR 与 SSG

全面支持服务器端渲染和静态站点生成，提供三种主题策略：hybrid（注入关键 CSS，不会出现 FOUC）、buildtime（包体积最小，主题为静态主题）和 runtime（可完整切换主题，但包体积较大）。将仅限客户端的组件包裹在 <ClientOnly> 中，避免水合不匹配。加载 ssr-ssg.md，了解关键 CSS 模式、无闪烁的暗色模式以及 SSR/SSG 检查清单。

无障碍功能

所有 Maz-UI 组件均符合 WCAG 2.1 AA 标准，具备适当的 ARIA 属性、键盘导航、焦点管理和屏幕阅读器支持。组件使用语义化 HTML，色彩对比度大于 4.5:1，并提供无障碍表单验证。加载 accessibility.md，了解键盘快捷键、焦点陷阱模式和无障碍测试检查清单。

表单验证

useFormValidator() 组合式函数可与 Valibot 集成，实现类型安全的架构验证，并提供完整的 TypeScript 类型推断。支持 5 种验证模式（lazy、aggressive、eager、blur、progressive）、异步验证、自定义验证器和实时错误消息。加载 form-validation.md，了解全面的验证模式和真实场景示例。

自动导入解析器

对摇树优化至关重要：使用 unplugin-vue-components 和 unplugin-auto-import 搭配 Maz-UI 解析器，仅导入实际用到的内容。与全局导入相比，可将包体积减少 60-90%。配置前缀处理，避免与其他库发生命名冲突。加载 resolvers.md，了解完整的解析器配置和故障排除方法。

渐进式披露摘要

此 SKILL.md 提供：

1. 快速入门 - 在 5 分钟内完成运行
2. 核心能力 - 概述所有功能
3. 错误预防 - 解决 5 大常见问题

如需了解详细实现：

• 根据当前任务加载参考文件（见上文“何时加载参考资料”）
• 每个参考文件都包含全面的指南、代码示例和高级配置
• 参考资料按领域分类（组件、设置、主题等），便于查找

软件包生态系统

• maz-ui - 核心组件库
• @maz-ui/nuxt - 支持自动导入的 Nuxt 3 模块
• @maz-ui/themes - 主题系统和预设
• @maz-ui/translations - i18n 支持（内置 8 种语言：en、fr、es、de、it、pt、ja、zh-CN）
• @maz-ui/icons - 840+ 个经过优化的 SVG 图标
• @maz-ui/mcp - AI Agent 文档服务

官方资源

• 文档：https://maz-ui.com
• GitHub：https://github.com/LouisMazel/maz-ui
• NPM：https://www.npmjs.com/package/maz-ui
• Discord：https://discord.gg/maz-ui
• 更新日志：https://github.com/LouisMazel/maz-ui/blob/master/CHANGELOG.md