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

pnpm add maz-ui @maz-ui/themes

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

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

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:

Quick Start - Get running in <5 minutes
Core Capabilities - Overview of all features
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包含:

快速开始 - 5分钟内快速上手
核心功能 - 所有功能概览
错误预防 - 解决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

官方资源

Documentation: 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
Changelog: https://github.com/LouisMazel/maz-ui/blob/master/CHANGELOG.md

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

maz-ui

Original

Translation

Maz-UI v4 - Vue & Nuxt Component Library

Maz-UI v4 - Vue & Nuxt组件库

Quick Start

快速开始

Vue 3 Installation

Vue 3 安装

Install core packages

Install core packages

Or with npm

Or with npm

Nuxt 3 Installation

Nuxt 3 安装

Install Nuxt module

Install Nuxt module

Core Capabilities

核心功能

🎨 Components (50+)

🎨 组件（50+）

🔧 Composables (14+)

🔧 组合式函数（14+）

📌 Directives (5)

📌 指令（5个）

🔌 Plugins (4)

🔌 插件（4个）

Key Features

关键特性

Template Structure

模板结构

Vue 3 + Vite Templates (templates/vue/)

Vue 3 + Vite 模板（templates/vue/）

Nuxt 3 Templates (templates/nuxt/)

Nuxt 3 模板（templates/nuxt/）

When to Load References

参考文档加载指南

Components (4 files)

组件相关（4份）

Setup & Configuration (2 files)

配置与安装（2份）

Core Features (5 files)

核心功能（5份）

Tools & Integrations (3 files)

工具与集成（3份）

Advanced Topics (5 files)

进阶主题（5份）

Troubleshooting (2 files)

故障排除（2份）

Top 6 Common Errors

6大常见错误

1. Missing Theme Plugin Error

1. 缺失主题插件错误

2. Auto-Import Not Working (Nuxt)

2. Nuxt自动导入不生效

Clear Nuxt cache

清除Nuxt缓存

3. Styles Not Applied

3. 样式未生效

4. TypeScript Errors with Components

4. 组件TypeScript错误

5. Phone Input Country Detection Fails

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

Install peer dependency

安装peer依赖

6. Translations Not Loading or Showing Raw Keys

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

Tree-Shaking Best Practices

摇树优化最佳实践

Advanced Topics

进阶主题

Performance Optimization

性能优化

SSR & SSG

SSR & SSG

Accessibility

可访问性

Form Validation

表单验证

Auto-Import Resolvers

Vue 3 + Vite Templates (
`templates/vue/`
)

Vue 3 + Vite 模板（
`templates/vue/`
）

Nuxt 3 Templates (
`templates/nuxt/`
)

Nuxt 3 模板（
`templates/nuxt/`
）