maz-ui

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Maz-UI v4 - Vue & Nuxt Component Library

Maz-UI v4 - Vue & Nuxt组件库

Maz-UI is a comprehensive, standalone component library for Vue 3 and Nuxt 3 applications, offering 50+ production-ready components, powerful theming, internationalization, and exceptional developer experience.
Latest Version: 4.3.3 (as of 2025-12-29) Package:
maz-ui
|
@maz-ui/nuxt
|
@maz-ui/themes
|
@maz-ui/translations
|
@maz-ui/icons
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

Quick Start

快速开始

Vue 3 Installation

Vue 3 安装

bash
undefined
bash
undefined

Install core packages

Install core packages

pnpm add maz-ui @maz-ui/themes
pnpm add maz-ui @maz-ui/themes

Or with npm

Or with npm

npm install maz-ui @maz-ui/themes

**Setup** in `main.ts`:

```typescript
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')
Use Components:
vue
<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>
npm install maz-ui @maz-ui/themes

**在`main.ts`中配置**:

```typescript
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')
使用组件:
vue
<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 Installation

Nuxt 3 安装

bash
undefined
bash
undefined

Install Nuxt module

Install Nuxt module

pnpm add @maz-ui/nuxt

**Setup** in `nuxt.config.ts`:

```typescript
export default defineNuxtConfig({
  modules: ['@maz-ui/nuxt']
  // That's it! Auto-imports enabled 🎉
})
Use Components (no imports needed):
vue
<script setup>
// Auto-imported composables
const theme = useTheme()
const toast = useToast()
const inputValue = ref('')
</script>

<template>
  <!-- Auto-imported components -->
  <MazInput v-model="inputValue" label="Name" />
  <MazBtn color="primary" @click="toast.success('Submitted!')">
    Submit
  </MazBtn>
</template>
pnpm add @maz-ui/nuxt

**在`nuxt.config.ts`中配置**:

```typescript
export default defineNuxtConfig({
  modules: ['@maz-ui/nuxt']
  // That's it! Auto-imports enabled 🎉
})
使用组件(无需手动导入):
vue
<script setup>
// Auto-imported composables
const theme = useTheme()
const toast = useToast()
const inputValue = ref('')
</script>

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

Core Capabilities

核心功能

🎨 Components (50+)

🎨 组件(50+)

Forms & Inputs:
  • MazInput
    - Text input with validation states
  • MazSelect
    - Dropdown select
  • MazTextarea
    - Multi-line text input
  • MazCheckbox
    - Checkbox with label
  • MazRadio
    - Radio buttons
  • MazSwitch
    - Toggle switch
  • MazSlider
    - Range slider
  • MazInputPhoneNumber
    - International phone input with validation
  • MazInputCode
    - Code/PIN input
  • MazInputPrice
    - Currency input with formatting
  • MazInputTags
    - Tag/chip input
  • MazDatePicker
    - Date picker
  • MazChecklist
    - Searchable checklist
UI Elements:
  • MazBtn
    - Button with variants
  • MazCard
    - Container card
  • MazBadge
    - Label badge
  • MazAvatar
    - User avatar
  • MazIcon
    - Icon display
  • MazSpinner
    - Loading spinner
  • MazTable
    - Data table with sorting/pagination
  • MazTabs
    - Tab navigation
  • MazStepper
    - Step indicator
  • MazPagination
    - Pagination controls
Overlays & Modals:
  • MazDialog
    - Modal dialog
  • MazDialogConfirm
    - Confirmation dialog
  • MazDrawer
    - Slide-out drawer
  • MazBottomSheet
    - Mobile bottom sheet
  • MazBackdrop
    - Overlay backdrop
  • MazPopover
    - Floating popover
  • MazDropdown
    - Dropdown menu
Feedback & Animation:
  • MazFullscreenLoader
    - Loading overlay
  • MazLoadingBar
    - Progress bar
  • MazCircularProgressBar
    - Circular progress
  • MazReadingProgressBar
    - Reading progress indicator
  • MazAnimatedText
    - Text animations
  • MazAnimatedElement
    - Element animations
  • MazAnimatedCounter
    - Number counter animation
  • MazCardSpotlight
    - Card with spotlight effect
Layout & Display:
  • MazCarousel
    - Image carousel
  • MazGallery
    - Image gallery
  • MazAccordion
    - Collapsible panels
  • MazExpandAnimation
    - Expand/collapse animation
  • MazLazyImg
    - Lazy-loaded image
  • MazPullToRefresh
    - Pull-to-refresh gesture
  • MazChart
    - Chart.js integration
表单与输入类:
  • 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集成组件

🔧 Composables (14+)

🔧 组合式函数(14+)

Theming:
  • useTheme()
    - Theme and dark mode management
Translations:
  • useTranslations()
    - i18n management
UI Interactions:
  • useToast()
    - Toast notifications
  • useDialog()
    - Programmatic dialogs
  • useWait()
    - Loading states
Utilities:
  • useBreakpoints()
    - Responsive breakpoints
  • useWindowSize()
    - Window dimensions
  • useTimer()
    - Timer/countdown
  • useFormValidator()
    - Form validation (Valibot)
  • useIdleTimeout()
    - Idle detection
  • useUserVisibility()
    - Page visibility
  • useSwipe()
    - Swipe gestures
  • useReadingTime()
    - Reading time calculation
  • useStringMatching()
    - String utilities
  • useDisplayNames()
    - Localized display names
主题相关:
  • useTheme()
    - 主题与深色模式管理
国际化相关:
  • useTranslations()
    - i18n国际化管理
UI交互相关:
  • useToast()
    - 提示通知组件
  • useDialog()
    - 程序化调用对话框
  • useWait()
    - 加载状态管理
工具类:
  • useBreakpoints()
    - 响应式断点管理
  • useWindowSize()
    - 窗口尺寸监听
  • useTimer()
    - 计时器/倒计时
  • useFormValidator()
    - 表单验证(基于Valibot)
  • useIdleTimeout()
    - 闲置状态检测
  • useUserVisibility()
    - 页面可见性监听
  • useSwipe()
    - 滑动手势监听
  • useReadingTime()
    - 阅读时长计算
  • useStringMatching()
    - 字符串工具函数
  • useDisplayNames()
    - 本地化名称展示

📌 Directives (5)

📌 指令(5个)

  • v-tooltip
    - Tooltips
  • v-click-outside
    - Outside click detection
  • v-lazy-img
    - Lazy loading
  • v-zoom-img
    - Image zoom
  • v-fullscreen-img
    - Fullscreen image viewer
  • v-tooltip
    - 提示框指令
  • v-click-outside
    - 点击外部区域检测指令
  • v-lazy-img
    - 图片懒加载指令
  • v-zoom-img
    - 图片缩放指令
  • v-fullscreen-img
    - 图片全屏查看指令

🔌 Plugins (4)

🔌 插件(4个)

  • AOS - Animations on scroll
  • Dialog - Template-free dialogs
  • Toast - Notifications
  • Wait - Global loading states
  • AOS - 滚动触发动画插件
  • Dialog - 无模板对话框插件
  • Toast - 通知提示插件
  • Wait - 全局加载状态插件

Key Features

关键特性

Standalone Components - Import only what you need, zero bloat ✅ SSR/SSG Ready - Full Nuxt 3 support with auto-imports ✅ TypeScript-First - Complete type safety out of the box ✅ Dark Mode - Built-in dark/light theme switching ✅ Tree-Shakable - Optimized bundle sizes ✅ Responsive - Mobile-first design ✅ Accessible - ARIA-compliant components ✅ Themeable - 4 built-in presets + custom themes ✅ i18n - Multi-language support with @maz-ui/translations ✅ 840+ Icons - Optimized SVG icon library (@maz-ui/icons)
独立组件 - 仅导入所需组件,无冗余代码 ✅ SSR/SSG支持 - 完整支持Nuxt 3,包含自动导入功能 ✅ TypeScript优先 - 开箱即用的完整类型安全 ✅ 深色模式 - 内置深色/浅色主题切换 ✅ 摇树优化 - 优化的包体积 ✅ 响应式设计 - 移动端优先的设计 ✅ 可访问性 - 符合ARIA标准的组件 ✅ 可定制主题 - 4种内置预设主题 + 自定义主题 ✅ 国际化 - 基于@maz-ui/translations的多语言支持 ✅ 840+图标 - 优化的SVG图标库(@maz-ui/icons)

Template Structure

模板结构

Maz-UI provides two sets of production-ready templates organized by framework:
Maz-UI 提供两套生产就绪的模板,按框架分类:

Vue 3 + Vite Templates (
templates/vue/
)

Vue 3 + Vite 模板(
templates/vue/

  • ✅ Pure Vue 3 with Vite
  • ✅ Uses standard
    fetch()
    API
  • ✅ Explicit imports for all dependencies
  • ✅ No framework-specific dependencies
  • ✅ Optimized for SPA development
Use when: Building Vue 3 applications with Vite
Available templates:
  • setup/vite.config.ts
    - Vite configuration with auto-imports
  • components/form-basic.vue
    - Basic form validation
  • components/form-multi-step.vue
    - Multi-step form with stepper
  • components/dialog-confirm.vue
    - Dialog confirmation patterns
  • components/data-table.vue
    - Data table with pagination, search, sort
  • ✅ 纯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 (
templates/nuxt/
)

Nuxt 3 模板(
templates/nuxt/

  • ✅ Nuxt 3 optimized
  • ✅ Uses
    $fetch
    (Nuxt's ofetch wrapper)
  • ✅ Leverages auto-imports for components and composables
  • ✅ Showcases SSR patterns and server routes
  • ✅ Optimized for full-stack Nuxt development
Use when: Building Nuxt 3 applications
Available templates:
  • setup/nuxt.config.ts
    - Nuxt configuration with Maz-UI module
  • components/form-basic.vue
    - Basic form validation (auto-imports)
  • components/form-multi-step.vue
    - Multi-step form (auto-imports)
  • components/dialog-confirm.vue
    - Dialog patterns (auto-imports)
  • components/data-table.vue
    - Data table with reactive data loading
Both template sets:
  • ✅ Fix all validation, type inference, and pagination issues
  • ✅ Follow framework best practices
  • ✅ Are production-ready and fully tested
  • ✅ Include setup configs and component examples
  • ✅ 针对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
    - 带响应式数据加载的数据表格示例
两套模板均具备:
  • ✅ 修复所有验证、类型推断和分页问题
  • ✅ 遵循框架最佳实践
  • ✅ 生产就绪且经过全面测试
  • ✅ 包含配置文件和组件示例

When to Load References

参考文档加载指南

Load reference files based on what you're implementing. All 21 reference files are grouped by purpose for quick discovery:
根据你正在实现的功能加载对应参考文档。所有21份参考文档按用途分组,便于快速查找:

Components (4 files)

组件相关(4份)

  • components-forms.md
    - Building forms, inputs, validation, phone numbers, dates, file uploads, MazInput, MazSelect, MazCheckbox, MazDatePicker
  • components-feedback.md
    - Adding loaders, progress bars, animations, toasts, MazFullscreenLoader, MazCircularProgressBar, MazAnimatedText, MazCardSpotlight
  • components-navigation.md
    - Implementing tabs, steppers, pagination, MazTabs, MazStepper, MazPagination
  • components-layout.md
    - Working with cards, drawers, carousels, galleries, MazCard, MazAccordion, MazDrawer, MazCarousel, MazGallery
  • 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

Setup & Configuration (2 files)

配置与安装(2份)

  • setup-vue.md
    - Setting up Maz-UI in Vue 3 project, auto-imports with resolvers, Vite/Webpack configuration, performance optimization
  • setup-nuxt.md
    - Integrating with Nuxt 3, module configuration, theme strategies (hybrid/buildtime/runtime), SSR/SSG considerations
  • setup-vue.md
    - Vue 3项目中Maz-UI的配置、自动导入解析器、Vite/Webpack配置、性能优化
  • setup-nuxt.md
    - 与Nuxt 3的集成、模块配置、主题策略(混合/构建时/运行时)、SSR/SSG注意事项

Core Features (5 files)

核心功能(5份)

  • composables.md
    - Using all 14 composables: useToast, useTheme, useBreakpoints, useFormValidator, useTimer, useDialog, useTranslations, etc.
  • directives.md
    - Adding directives: v-tooltip, v-click-outside, v-lazy-img, v-zoom-img, v-fullscreen-img
  • plugins.md
    - Enabling plugins: AOS (animations on scroll), Dialog, Toast, Wait (loading states)
  • resolvers.md
    - CRITICAL: Auto-import configuration with MazComponentsResolver, MazDirectivesResolver, MazModulesResolver for optimal tree-shaking
  • translations.md
    - Implementing multi-language support (8 built-in languages), custom locales, lazy loading, SSR hydration
  • 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水合

Tools & Integrations (3 files)

工具与集成(3份)

  • icons.md
    - Using @maz-ui/icons package (840+ icons), MazIcon component, icon sizing, colors, animations
  • cli.md
    - Using @maz-ui/cli (legacy v3), theme configuration, migration to v4 themes system
  • mcp.md
    - Setting up Model Context Protocol server for AI assistant integration (Claude Code, Claude Desktop, Cursor, Windsurf)
  • icons.md
    - @maz-ui/icons包的使用(840+图标)、MazIcon组件、图标尺寸、颜色、动画
  • cli.md
    - @maz-ui/cli的使用(旧版v3)、主题配置、迁移到v4主题系统
  • mcp.md
    - 配置Model Context Protocol服务器,实现AI助手集成(Claude Code、Claude Desktop、Cursor、Windsurf)

Advanced Topics (5 files)

进阶主题(5份)

  • theming.md
    - Customizing themes, dark mode, color schemes, CSS variables, 4 built-in presets (mazUi, ocean, pristine, obsidian)
  • performance.md
    - Bundle optimization, tree-shaking, lazy loading, code splitting, reducing bundle size from ~300KB to ~15KB
  • ssr-ssg.md
    - Comprehensive SSR/SSG guide: theme strategies, critical CSS, hydration prevention, dark mode without flash, static site generation
  • accessibility.md
    - WCAG 2.1 AA compliance, keyboard navigation, screen reader support, ARIA attributes, color contrast
  • form-validation.md
    - useFormValidator deep dive, Valibot integration, 5 validation modes (lazy, aggressive, eager, blur, progressive), TypeScript type inference
  • 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种验证模式(lazy、aggressive、eager、blur、progressive)、TypeScript类型推断

Troubleshooting (2 files)

故障排除(2份)

  • migration-v4.md
    - Upgrading from Maz-UI v3 to v4, breaking changes, API changes, component renames, TypeScript updates
  • troubleshooting.md
    - Debugging errors, common issues, configuration problems, SSR hydration, bundle size issues
  • migration-v4.md
    - 从Maz-UI v3升级到v4、破坏性变更、API变更、组件重命名、TypeScript更新
  • troubleshooting.md
    - 错误调试、常见问题、配置问题、SSR水合问题、包体积问题

Top 6 Common Errors

6大常见错误

1. Missing Theme Plugin Error

1. 缺失主题插件错误

Error:
"useTheme must be used within MazUi plugin installation"
Cause: MazUi plugin not installed or theme composable disabled Fix:
typescript
// Vue
app.use(MazUi, { theme: { preset: mazUi } })

// Nuxt
export default defineNuxtConfig({
  mazUi: {
    composables: { useTheme: true },
    theme: { preset: 'maz-ui' }
  }
})
错误信息:
"useTheme must be used within MazUi plugin installation"
原因: 未安装MazUi插件或禁用了主题组合式函数 修复方案:
typescript
// Vue
app.use(MazUi, { theme: { preset: mazUi } })

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

2. Auto-Import Not Working (Nuxt)

2. Nuxt自动导入不生效

Error: Components/composables not found despite Nuxt module installed Cause: Module not properly configured or cache issue Fix:
bash
undefined
错误信息: 已安装Nuxt模块,但组件/组合式函数找不到 原因: 模块配置不正确或缓存问题 修复方案:
bash
undefined

Clear Nuxt cache

清除Nuxt缓存

rm -rf .nuxt node_modules/.cache pnpm install
**Verify** `nuxt.config.ts`:
```typescript
export default defineNuxtConfig({
  modules: ['@maz-ui/nuxt']
})
rm -rf .nuxt node_modules/.cache pnpm install
**验证`nuxt.config.ts`**:
```typescript
export default defineNuxtConfig({
  modules: ['@maz-ui/nuxt']
})

3. Styles Not Applied

3. 样式未生效

Error: Components render but have no styling Cause: CSS not imported Fix Vue:
typescript
import 'maz-ui/styles' // Add this line
Fix Nuxt:
typescript
export default defineNuxtConfig({
  mazUi: {
    css: { injectMainCss: true } // Ensure this is true
  }
})
错误信息: 组件渲染但无样式 原因: 未导入CSS Vue修复方案:
typescript
import 'maz-ui/styles' // 添加此行
Nuxt修复方案:
typescript
export default defineNuxtConfig({
  mazUi: {
    css: { injectMainCss: true } // 确保此值为true
  }
})

4. TypeScript Errors with Components

4. 组件TypeScript错误

Error:
Cannot find module 'maz-ui/components/MazBtn'
Cause: Missing type definitions or incorrect import path Fix:
typescript
// Correct import
import MazBtn from 'maz-ui/components/MazBtn'

// Or with auto-import (Nuxt)
// No import needed, just use <MazBtn>
Ensure
tsconfig.json
includes:
json
{
  "compilerOptions": {
    "types": ["maz-ui/types"]
  }
}
错误信息:
Cannot find module 'maz-ui/components/MazBtn'
原因: 缺失类型定义或导入路径错误 修复方案:
typescript
// 正确导入方式
import MazBtn from 'maz-ui/components/MazBtn'

// 或使用Nuxt自动导入(无需手动导入)
// 直接使用<MazBtn>即可
确保
tsconfig.json
包含
:
json
{
  "compilerOptions": {
    "types": ["maz-ui/types"]
  }
}

5. Phone Input Country Detection Fails

5. 手机号输入框国家检测失败

Error:
MazInputPhoneNumber
doesn't detect country or shows wrong flag Cause: Missing libphonenumber-js dependency or country data not loaded Fix:
bash
undefined
错误信息:
MazInputPhoneNumber
无法检测国家或显示错误国旗 原因: 缺失libphonenumber-js依赖或未加载国家数据 修复方案:
bash
undefined

Install peer dependency

安装peer依赖

pnpm add libphonenumber-js
```vue
<MazInputPhoneNumber
  v-model="phone"
  default-country-code="US"
  preferred-countries="['US', 'CA', 'GB']"
/>
pnpm add libphonenumber-js
```vue
<MazInputPhoneNumber
  v-model="phone"
  default-country-code="US"
  preferred-countries="['US', 'CA', 'GB']"
/>

6. Translations Not Loading or Showing Raw Keys

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

Error: Translation keys showing as raw strings like
inputPhoneNumber.phoneInput.example
instead of translated text Causes:
  • Missing locale import
  • Lazy loading not awaited properly
  • Language file failed to load asynchronously
  • Missing
    preloadFallback
    configuration
  • SSR hydration mismatch (Nuxt)
Fix Vue (Immediate Loading):
typescript
import { fr } from '@maz-ui/translations'

app.use(MazUi, {
  translations: {
    locale: 'fr',
    fallbackLocale: 'en',
    preloadFallback: true,
    messages: { fr } // Import immediately
  }
})
Fix Vue (Lazy Loading):
typescript
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!
Fix Nuxt (Avoid Hydration):
typescript
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')
      }
    }
  }
})
Error Handling:
vue
<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>
Learn More: Load
references/translations.md
for comprehensive i18n setup, lazy loading strategies, and production patterns.
错误信息: 翻译键显示为原始字符串,如
inputPhoneNumber.phoneInput.example
,而非翻译后的文本 原因:
  • 缺失语言包导入
  • 懒加载未正确等待
  • 语言文件异步加载失败
  • 缺失
    preloadFallback
    配置
  • Nuxt SSR水合不匹配
Vue修复方案(立即加载):
typescript
import { fr } from '@maz-ui/translations'

app.use(MazUi, {
  translations: {
    locale: 'fr',
    fallbackLocale: 'en',
    preloadFallback: true,
    messages: { fr } // 立即导入
  }
})
Vue修复方案(懒加载):
typescript
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修复方案(避免水合问题):
typescript
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')
      }
    }
  }
})
错误处理:
vue
<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 Practices

摇树优化最佳实践

Direct Imports (Most Optimized):
typescript
// ✅✅✅ Best - smallest bundle
import MazBtn from 'maz-ui/components/MazBtn'
import { useToast } from 'maz-ui/composables/useToast'
import { vClickOutside } from 'maz-ui/directives/vClickOutside'
Index Imports (Good):
typescript
// ✅ Good - tree-shakable
import { MazBtn, MazInput } from 'maz-ui/components'
import { useToast, useTheme } from 'maz-ui/composables'
Avoid (Not Tree-Shakable):
typescript
// ❌ Imports everything
import * as MazUI from 'maz-ui'
直接导入(最优):
typescript
// ✅✅✅ 最佳方式 - 包体积最小
import MazBtn from 'maz-ui/components/MazBtn'
import { useToast } from 'maz-ui/composables/useToast'
import { vClickOutside } from 'maz-ui/directives/vClickOutside'
索引导入(推荐):
typescript
// ✅ 推荐 - 支持摇树优化
import { MazBtn, MazInput } from 'maz-ui/components'
import { useToast, useTheme } from 'maz-ui/composables'
避免(不支持摇树优化):
typescript
// ❌ 导入所有内容
import * as MazUI from 'maz-ui'

Advanced Topics

进阶主题

Performance Optimization

性能优化

Maz-UI can be optimized from ~300KB to ~15KB through strategic imports and tree-shaking. Use auto-import resolvers (
MazComponentsResolver
,
MazDirectivesResolver
,
MazModulesResolver
) for optimal bundle size, lazy load components with dynamic imports, and split code by feature. Load
performance.md
for comprehensive bundle optimization strategies.
通过策略性导入和摇树优化,Maz-UI的包体积可从约300KB减少到约15KB。使用自动导入解析器(
MazComponentsResolver
MazDirectivesResolver
MazModulesResolver
)实现最优包体积,通过动态导入懒加载组件,按功能拆分代码。加载**
performance.md
**获取全面的包体积优化策略。

SSR & SSG

SSR & SSG

Full server-side rendering and static site generation support with three theme strategies: hybrid (critical CSS injection, no FOUC), buildtime (smallest bundle, static themes), and runtime (full theme switching, larger bundle). Prevent hydration mismatches by wrapping client-only components in
<ClientOnly>
. Load
ssr-ssg.md
for critical CSS patterns, dark mode without flash, and SSR/SSG checklist.
完整支持服务端渲染和静态站点生成,提供三种主题策略:混合模式(注入关键CSS,无FOUC)、构建时模式(包体积最小,静态主题)、运行时模式(完整主题切换,包体积较大)。通过将仅客户端组件包裹在
<ClientOnly>
中避免水合不匹配。加载**
ssr-ssg.md
**获取关键CSS方案、无闪烁深色模式及SSR/SSG检查清单。

Accessibility

可访问性

All Maz-UI components are WCAG 2.1 AA compliant with proper ARIA attributes, keyboard navigation, focus management, and screen reader support. Components include semantic HTML, color contrast ratios >4.5:1, and accessible form validation. Load
accessibility.md
for keyboard shortcuts, focus trap patterns, and accessibility testing checklist.
所有Maz-UI组件均符合WCAG 2.1 AA标准,具备正确的ARIA属性、键盘导航、焦点管理及屏幕阅读器支持。组件包含语义化HTML、>4.5:1的颜色对比度及可访问的表单验证。加载**
accessibility.md
**获取键盘快捷键、焦点捕获方案及可访问性测试清单。

Form Validation

表单验证

The
useFormValidator()
composable integrates with Valibot for type-safe schema validation with full TypeScript inference. Supports 5 validation modes (lazy, aggressive, eager, blur, progressive), async validation, custom validators, and real-time error messages. Load
form-validation.md
for comprehensive validation patterns and real-world examples.
useFormValidator()
组合式函数与Valibot集成,实现类型安全的Schema验证及完整TypeScript类型推断。支持5种验证模式(lazy、aggressive、eager、blur、progressive)、异步验证、自定义验证器及实时错误提示。加载**
form-validation.md
**获取全面的验证方案及实战示例。

Auto-Import Resolvers

自动导入解析器

Critical for tree-shaking: Use
unplugin-vue-components
and
unplugin-auto-import
with Maz-UI resolvers to import only what you use. Reduces bundle size by 60-90% compared to global imports. Configure prefix handling to avoid naming conflicts with other libraries. Load
resolvers.md
for complete resolver configuration and troubleshooting.
摇树优化的关键: 使用
unplugin-vue-components
unplugin-auto-import
配合Maz-UI解析器,仅导入所需内容。与全局导入相比,可减少60-90%的包体积。配置前缀处理避免与其他库命名冲突。加载**
resolvers.md
**获取完整的解析器配置及故障排除指南。

Progressive Disclosure Summary

渐进式内容说明

This SKILL.md provides:
  1. Quick Start - Get running in <5 minutes
  2. Core Capabilities - Overview of all features
  3. Error Prevention - Top 5 common issues solved
For detailed implementation:
  • Load reference files based on your current task (see "When to Load References" above)
  • Each reference contains comprehensive guides, code examples, and advanced configurations
  • References are organized by domain (components, setup, theming, etc.) for easy navigation
本SKILL.md包含:
  1. 快速开始 - 5分钟内快速上手
  2. 核心功能 - 所有功能概览
  3. 错误预防 - 解决5大常见问题
如需详细实现指南:
  • 根据当前任务加载参考文档(见上方"参考文档加载指南")
  • 每份参考文档包含全面指南、代码示例及进阶配置
  • 参考文档按领域(组件、配置、主题等)分类,便于导航

Package Ecosystem

包生态系统

  • maz-ui - Core component library
  • @maz-ui/nuxt - Nuxt 3 module with auto-imports
  • @maz-ui/themes - Theming system and presets
  • @maz-ui/translations - i18n support (8 built-in languages: en, fr, es, de, it, pt, ja, zh-CN)
  • @maz-ui/icons - 840+ optimized SVG icons
  • @maz-ui/mcp - AI agent documentation server
  • maz-ui - 核心组件库
  • @maz-ui/nuxt - 带自动导入的Nuxt 3模块
  • @maz-ui/themes - 主题系统及预设
  • @maz-ui/translations - 国际化支持(8种内置语言:en、fr、es、de、it、pt、ja、zh-CN)
  • @maz-ui/icons - 840+优化的SVG图标
  • @maz-ui/mcp - AI助手文档服务器

Official Resources

官方资源