Maz-UI前端组件库技能 maz-ui

---

名称: maz-ui 描述: Maz-UI v4 - 现代Vue和Nuxt组件库，拥有50多个独立组件、可组合函数、指令、主题化、i18n和SSR支持。适用于构建具有表单、对话框、表格、动画的Vue/Nuxt应用程序，或需要响应式设计系统与暗模式。

Maz-UI v4 - Vue和Nuxt组件库

Maz-UI是一个全面、独立的组件库，用于Vue 3和Nuxt 3应用程序，提供50多个生产就绪的组件、强大的主题化、国际化以及卓越的开发者体验。

最新版本: 4.3.3 (截至2025-12-29) 包: maz-ui | @maz-ui/nuxt | @maz-ui/themes | @maz-ui/translations | @maz-ui/icons

快速开始

Vue 3 安装

# 安装核心包
pnpm add maz-ui @maz-ui/themes

# 或使用 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="名称" />
  <MazBtn color="primary">提交</MazBtn>
</template>

Nuxt 3 安装

# 安装 Nuxt 模块
pnpm add @maz-ui/nuxt

设置 在 nuxt.config.ts 中：

export default defineNuxtConfig({
  modules: ['@maz-ui/nuxt']
  // 就这样！自动导入已启用 🎉
})

使用组件 (无需导入)：

<script setup>
// 自动导入的可组合函数
const theme = useTheme()
const toast = useToast()
const inputValue = ref('')
</script>

<template>
  <!-- 自动导入的组件 -->
  <MazInput v-model="inputValue" label="名称" />
  <MazBtn color="primary" @click="toast.success('已提交！')">
    提交
  </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() - i18n 管理

UI 交互：

• useToast() - 吐司通知
• 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 优先 - 开箱即用的完整类型安全 ✅ 暗模式 - 内置暗/亮主题切换 ✅ 树可摇 - 优化的包大小 ✅ 响应式 - 移动优先设计 ✅ 可访问 - 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 集成、模块配置、主题策略 (混合/构建时/运行时)、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 的自动导入配置，以实现最优树摇
• translations.md - 实现多语言支持 (8 种内置语言)、自定义区域设置、懒加载、SSR 水合

工具和集成 (3 个文件)

• icons.md - 使用 @maz-ui/icons 包 (840+ 图标)、MazIcon 组件、图标大小、颜色、动画
• cli.md - 使用 @maz-ui/cli (旧版 v3)、主题配置、迁移到 v4 主题系统
• mcp.md - 设置模型上下文协议服务器，用于 AI 助手集成 (Claude Code、Claude Desktop、Cursor、Windsurf)

高级主题 (5 个文件)

• theming.md - 自定义主题、暗模式、配色方案、CSS 变量、4 个内置预设 (mazUi、ocean、pristine、obsidian)
• performance.md - 包优化、树摇、懒加载、代码分割、将包大小从 ~300KB 减少到 ~15KB
• ssr-ssg.md - 全面的 SSR/SSG 指南：主题策略、关键 CSS、水合预防、无闪光的暗模式、静态站点生成
• accessibility.md - WCAG 2.1 AA 合规性、键盘导航、屏幕阅读器支持、ARIA 属性、颜色对比度
• form-validation.md - useFormValidator 深入探讨、Valibot 集成、5 种验证模式 (惰性、激进、急切、模糊、渐进)、TypeScript 类型推断

故障排除 (2 个文件)

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

前 6 个常见错误

1. 缺少主题插件错误

错误: "useTheme must be used within MazUi plugin installation" 原因: MazUi 插件未安装或主题可组合函数禁用 修复:

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

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

2. 自动导入不工作 (Nuxt)

错误: 组件/可组合函数未找到，尽管 Nuxt 模块已安装 原因: 模块未正确配置或缓存问题 修复:

# 清除 Nuxt 缓存
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' // 添加此行

修复 Nuxt:

export default defineNuxtConfig({
  mazUi: {
    css: { injectMainCss: true } // 确保此为 true
  }
})

4. TypeScript 错误与组件

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

// 正确导入
import MazBtn from 'maz-ui/components/MazBtn'

// 或带自动导入 (Nuxt)
// 无需导入，只需使用 <MazBtn>

确保 tsconfig.json 包括:

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

5. 电话输入国家检测失败

错误: MazInputPhoneNumber 未检测到国家或显示错误标志 原因: 缺少 libphonenumber-js 依赖项或国家数据未加载 修复:

# 安装对等依赖项
pnpm add libphonenumber-js

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

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

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

• 缺少区域设置导入
• 懒加载未正确等待
• 语言文件异步加载失败
• 缺少 preloadFallback 配置
• SSR 水合不匹配 (Nuxt)

修复 Vue (立即加载):

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

app.use(MazUi, {
  translations: {
    locale: 'fr',
    fallbackLocale: 'en',
    preloadFallback: true,
    messages: { fr } // 立即导入
  }
})

修复 Vue (懒加载):

app.use(MazUi, {
  translations: {
    locale: 'fr',
    preloadFallback: true, // 确保回退已预加载
    messages: {
      fr: () => import('@maz-ui/translations/locales/fr')
    }
  }
})

// 在组件中: 总是使用 await
const { setLocale } = useTranslations()
await setLocale('fr') // 别忘了 await!

修复 Nuxt (避免水合):

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

export default defineNuxtConfig({
  mazUi: {
    translations: {
      locale: 'fr',
      preloadFallback: true,
      messages: {
        // 关键: 立即提供初始区域设置 (不作为函数)
        fr, // SSR 需要立即加载

        // 其他语言可以懒加载
        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(`语言已更改为 ${locale}`)
  } catch (error) {
    console.error('翻译加载错误:', error)
    toast.error('加载翻译失败')
  }
}
</script>

了解更多: 加载 references/translations.md 以获取全面的 i18n 设置、懒加载策略和生产模式。

树摇最佳实践

直接导入 (最优化):

// ✅✅✅ 最佳 - 最小包
import MazBtn from 'maz-ui/components/MazBtn'
import { useToast } from 'maz-ui/composables/useToast'
import { vClickOutside } from 'maz-ui/directives/vClickOutside'

索引导入 (好):

// ✅ 好 - 树可摇
import { MazBtn, MazInput } from 'maz-ui/components'
import { useToast, useTheme } from 'maz-ui/composables'

避免 (不可树摇):

// ❌ 导入所有内容
import * as MazUI from 'maz-ui'

高级主题

性能优化

Maz-UI 可以通过战略导入和树摇从 ~300KB 优化到 ~15KB。使用自动导入解析器 (MazComponentsResolver、MazDirectivesResolver、MazModulesResolver) 以实现最优包大小，通过动态导入懒加载组件，并按功能拆分代码。加载 performance.md 以获取全面的包优化策略。

SSR 和 SSG

完整的服务器端渲染和静态站点生成支持，带三种主题策略：混合 (关键 CSS 注入，无 FOUC)、构建时 (最小包，静态主题) 和 运行时 (完整主题切换，较大包)。通过将仅客户端组件包装在 <ClientOnly> 中来防止水合不匹配。加载 ssr-ssg.md 以获取关键 CSS 模式、无闪光的暗模式和 SSR/SSG 检查清单。

可访问性

所有 Maz-UI 组件都符合 WCAG 2.1 AA 标准，具有适当的 ARIA 属性、键盘导航、焦点管理和屏幕阅读器支持。组件包括语义 HTML、颜色对比度比 >4.5:1 和可访问的表单验证。加载 accessibility.md 以获取键盘快捷键、焦点陷阱模式和可访问性测试检查清单。

表单验证

useFormValidator() 可组合函数与 Valibot 集成，用于类型安全模式验证，带完整的 TypeScript 推断。支持 5 种验证模式 (惰性、激进、急切、模糊、渐进)、异步验证、自定义验证器和实时错误消息。加载 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 代理文档服务器

官方资源

• 文档: 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