maz-ui
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseMaz-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/iconsMaz-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/iconsQuick Start
快速开始
Vue 3 Installation
Vue 3 安装
bash
undefinedbash
undefinedInstall 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
undefinedbash
undefinedInstall 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:
- - Text input with validation states
MazInput - - Dropdown select
MazSelect - - Multi-line text input
MazTextarea - - Checkbox with label
MazCheckbox - - Radio buttons
MazRadio - - Toggle switch
MazSwitch - - Range slider
MazSlider - - International phone input with validation
MazInputPhoneNumber - - Code/PIN input
MazInputCode - - Currency input with formatting
MazInputPrice - - Tag/chip input
MazInputTags - - Date picker
MazDatePicker - - Searchable checklist
MazChecklist
UI Elements:
- - Button with variants
MazBtn - - Container card
MazCard - - Label badge
MazBadge - - User avatar
MazAvatar - - Icon display
MazIcon - - Loading spinner
MazSpinner - - Data table with sorting/pagination
MazTable - - Tab navigation
MazTabs - - Step indicator
MazStepper - - Pagination controls
MazPagination
Overlays & Modals:
- - Modal dialog
MazDialog - - Confirmation dialog
MazDialogConfirm - - Slide-out drawer
MazDrawer - - Mobile bottom sheet
MazBottomSheet - - Overlay backdrop
MazBackdrop - - Floating popover
MazPopover - - Dropdown menu
MazDropdown
Feedback & Animation:
- - Loading overlay
MazFullscreenLoader - - Progress bar
MazLoadingBar - - Circular progress
MazCircularProgressBar - - Reading progress indicator
MazReadingProgressBar - - Text animations
MazAnimatedText - - Element animations
MazAnimatedElement - - Number counter animation
MazAnimatedCounter - - Card with spotlight effect
MazCardSpotlight
Layout & Display:
- - Image carousel
MazCarousel - - Image gallery
MazGallery - - Collapsible panels
MazAccordion - - Expand/collapse animation
MazExpandAnimation - - Lazy-loaded image
MazLazyImg - - Pull-to-refresh gesture
MazPullToRefresh - - Chart.js integration
MazChart
表单与输入类:
- - 带验证状态的文本输入框
MazInput - - 下拉选择器
MazSelect - - 多行文本输入框
MazTextarea - - 带标签的复选框
MazCheckbox - - 单选按钮
MazRadio - - 切换开关
MazSwitch - - 范围滑块
MazSlider - - 带验证的国际手机号输入框
MazInputPhoneNumber - - 验证码/PIN输入框
MazInputCode - - 带格式化的货币输入框
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 - - Chart.js集成组件
MazChart
🔧 Composables (14+)
🔧 组合式函数(14+)
Theming:
- - Theme and dark mode management
useTheme()
Translations:
- - i18n management
useTranslations()
UI Interactions:
- - Toast notifications
useToast() - - Programmatic dialogs
useDialog() - - Loading states
useWait()
Utilities:
- - Responsive breakpoints
useBreakpoints() - - Window dimensions
useWindowSize() - - Timer/countdown
useTimer() - - Form validation (Valibot)
useFormValidator() - - Idle detection
useIdleTimeout() - - Page visibility
useUserVisibility() - - Swipe gestures
useSwipe() - - Reading time calculation
useReadingTime() - - String utilities
useStringMatching() - - Localized display names
useDisplayNames()
主题相关:
- - 主题与深色模式管理
useTheme()
国际化相关:
- - i18n国际化管理
useTranslations()
UI交互相关:
- - 提示通知组件
useToast() - - 程序化调用对话框
useDialog() - - 加载状态管理
useWait()
工具类:
- - 响应式断点管理
useBreakpoints() - - 窗口尺寸监听
useWindowSize() - - 计时器/倒计时
useTimer() - - 表单验证(基于Valibot)
useFormValidator() - - 闲置状态检测
useIdleTimeout() - - 页面可见性监听
useUserVisibility() - - 滑动手势监听
useSwipe() - - 阅读时长计算
useReadingTime() - - 字符串工具函数
useStringMatching() - - 本地化名称展示
useDisplayNames()
📌 Directives (5)
📌 指令(5个)
- - Tooltips
v-tooltip - - Outside click detection
v-click-outside - - Lazy loading
v-lazy-img - - Image zoom
v-zoom-img - - Fullscreen image viewer
v-fullscreen-img
- - 提示框指令
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/
)
templates/vue/Vue 3 + Vite 模板(templates/vue/
)
templates/vue/- ✅ Pure Vue 3 with Vite
- ✅ Uses standard API
fetch() - ✅ Explicit imports for all dependencies
- ✅ No framework-specific dependencies
- ✅ Optimized for SPA development
Use when: Building Vue 3 applications with Vite
Available templates:
- - Vite configuration with auto-imports
setup/vite.config.ts - - Basic form validation
components/form-basic.vue - - Multi-step form with stepper
components/form-multi-step.vue - - Dialog confirmation patterns
components/dialog-confirm.vue - - Data table with pagination, search, sort
components/data-table.vue
- ✅ 纯Vue 3 + Vite技术栈
- ✅ 使用标准API
fetch() - ✅ 显式导入所有依赖
- ✅ 无框架特定依赖
- ✅ 针对SPA开发优化
适用场景: 基于Vite构建Vue 3应用
可用模板:
- - 带自动导入的Vite配置
setup/vite.config.ts - - 基础表单验证示例
components/form-basic.vue - - 带步骤器的多步表单示例
components/form-multi-step.vue - - 确认对话框示例
components/dialog-confirm.vue - - 带分页、搜索、排序的数据表格示例
components/data-table.vue
Nuxt 3 Templates (templates/nuxt/
)
templates/nuxt/Nuxt 3 模板(templates/nuxt/
)
templates/nuxt/- ✅ Nuxt 3 optimized
- ✅ Uses (Nuxt's ofetch wrapper)
$fetch - ✅ 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:
- - Nuxt configuration with Maz-UI module
setup/nuxt.config.ts - - Basic form validation (auto-imports)
components/form-basic.vue - - Multi-step form (auto-imports)
components/form-multi-step.vue - - Dialog patterns (auto-imports)
components/dialog-confirm.vue - - Data table with reactive data loading
components/data-table.vue
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优化
- ✅ 使用(Nuxt的ofetch封装)
$fetch - ✅ 利用组件和组合式函数的自动导入功能
- ✅ 展示SSR模式和服务端路由
- ✅ 针对全栈Nuxt开发优化
适用场景: 构建Nuxt 3应用
可用模板:
- - 集成Maz-UI模块的Nuxt配置
setup/nuxt.config.ts - - 基础表单验证示例(自动导入)
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份)
- - Building forms, inputs, validation, phone numbers, dates, file uploads, MazInput, MazSelect, MazCheckbox, MazDatePicker
components-forms.md - - Adding loaders, progress bars, animations, toasts, MazFullscreenLoader, MazCircularProgressBar, MazAnimatedText, MazCardSpotlight
components-feedback.md - - Implementing tabs, steppers, pagination, MazTabs, MazStepper, MazPagination
components-navigation.md - - Working with cards, drawers, carousels, galleries, MazCard, MazAccordion, MazDrawer, MazCarousel, MazGallery
components-layout.md
- - 表单构建、输入框、验证、手机号、日期、文件上传、MazInput、MazSelect、MazCheckbox、MazDatePicker
components-forms.md - - 加载器、进度条、动画、提示框、MazFullscreenLoader、MazCircularProgressBar、MazAnimatedText、MazCardSpotlight
components-feedback.md - - 标签页、步骤器、分页、MazTabs、MazStepper、MazPagination
components-navigation.md - - 卡片、抽屉、轮播、画廊、MazCard、MazAccordion、MazDrawer、MazCarousel、MazGallery
components-layout.md
Setup & Configuration (2 files)
配置与安装(2份)
- - Setting up Maz-UI in Vue 3 project, auto-imports with resolvers, Vite/Webpack configuration, performance optimization
setup-vue.md - - Integrating with Nuxt 3, module configuration, theme strategies (hybrid/buildtime/runtime), SSR/SSG considerations
setup-nuxt.md
- - Vue 3项目中Maz-UI的配置、自动导入解析器、Vite/Webpack配置、性能优化
setup-vue.md - - 与Nuxt 3的集成、模块配置、主题策略(混合/构建时/运行时)、SSR/SSG注意事项
setup-nuxt.md
Core Features (5 files)
核心功能(5份)
- - Using all 14 composables: useToast, useTheme, useBreakpoints, useFormValidator, useTimer, useDialog, useTranslations, etc.
composables.md - - Adding directives: v-tooltip, v-click-outside, v-lazy-img, v-zoom-img, v-fullscreen-img
directives.md - - Enabling plugins: AOS (animations on scroll), Dialog, Toast, Wait (loading states)
plugins.md - - CRITICAL: Auto-import configuration with MazComponentsResolver, MazDirectivesResolver, MazModulesResolver for optimal tree-shaking
resolvers.md - - Implementing multi-language support (8 built-in languages), custom locales, lazy loading, SSR hydration
translations.md
- - 14个组合式函数的使用:useToast、useTheme、useBreakpoints、useFormValidator、useTimer、useDialog、useTranslations等
composables.md - - 指令的使用:v-tooltip、v-click-outside、v-lazy-img、v-zoom-img、v-fullscreen-img
directives.md - - 插件的启用:AOS(滚动动画)、Dialog、Toast、Wait(加载状态)
plugins.md - - 关键:使用MazComponentsResolver、MazDirectivesResolver、MazModulesResolver配置自动导入,实现最优摇树优化
resolvers.md - - 多语言支持实现(8种内置语言)、自定义语言、懒加载、SSR水合
translations.md
Tools & Integrations (3 files)
工具与集成(3份)
- - Using @maz-ui/icons package (840+ icons), MazIcon component, icon sizing, colors, animations
icons.md - - Using @maz-ui/cli (legacy v3), theme configuration, migration to v4 themes system
cli.md - - Setting up Model Context Protocol server for AI assistant integration (Claude Code, Claude Desktop, Cursor, Windsurf)
mcp.md
- - @maz-ui/icons包的使用(840+图标)、MazIcon组件、图标尺寸、颜色、动画
icons.md - - @maz-ui/cli的使用(旧版v3)、主题配置、迁移到v4主题系统
cli.md - - 配置Model Context Protocol服务器,实现AI助手集成(Claude Code、Claude Desktop、Cursor、Windsurf)
mcp.md
Advanced Topics (5 files)
进阶主题(5份)
- - Customizing themes, dark mode, color schemes, CSS variables, 4 built-in presets (mazUi, ocean, pristine, obsidian)
theming.md - - Bundle optimization, tree-shaking, lazy loading, code splitting, reducing bundle size from ~300KB to ~15KB
performance.md - - Comprehensive SSR/SSG guide: theme strategies, critical CSS, hydration prevention, dark mode without flash, static site generation
ssr-ssg.md - - WCAG 2.1 AA compliance, keyboard navigation, screen reader support, ARIA attributes, color contrast
accessibility.md - - useFormValidator deep dive, Valibot integration, 5 validation modes (lazy, aggressive, eager, blur, progressive), TypeScript type inference
form-validation.md
- - 自定义主题、深色模式、配色方案、CSS变量、4种内置预设主题(mazUi、ocean、pristine、obsidian)
theming.md - - 包体积优化、摇树优化、懒加载、代码分割、将包体积从约300KB减少到约15KB
performance.md - - 全面的SSR/SSG指南:主题策略、关键CSS、水合阻止、无闪烁深色模式、静态站点生成
ssr-ssg.md - - WCAG 2.1 AA合规、键盘导航、屏幕阅读器支持、ARIA属性、颜色对比度
accessibility.md - - useFormValidator深度解析、Valibot集成、5种验证模式(lazy、aggressive、eager、blur、progressive)、TypeScript类型推断
form-validation.md
Troubleshooting (2 files)
故障排除(2份)
- - Upgrading from Maz-UI v3 to v4, breaking changes, API changes, component renames, TypeScript updates
migration-v4.md - - Debugging errors, common issues, configuration problems, SSR hydration, bundle size issues
troubleshooting.md
- - 从Maz-UI v3升级到v4、破坏性变更、API变更、组件重命名、TypeScript更新
migration-v4.md - - 错误调试、常见问题、配置问题、SSR水合问题、包体积问题
troubleshooting.md
Top 6 Common Errors
6大常见错误
1. Missing Theme Plugin Error
1. 缺失主题插件错误
Error:
Cause: MazUi plugin not installed or theme composable disabled
Fix:
"useTheme must be used within MazUi plugin installation"typescript
// Vue
app.use(MazUi, { theme: { preset: mazUi } })
// Nuxt
export default defineNuxtConfig({
mazUi: {
composables: { useTheme: true },
theme: { preset: 'maz-ui' }
}
})错误信息:
原因: 未安装MazUi插件或禁用了主题组合式函数
修复方案:
"useTheme must be used within MazUi plugin installation"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
undefinedClear 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 lineFix 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:
Cause: Missing type definitions or incorrect import path
Fix:
Cannot find module 'maz-ui/components/MazBtn'typescript
// Correct import
import MazBtn from 'maz-ui/components/MazBtn'
// Or with auto-import (Nuxt)
// No import needed, just use <MazBtn>Ensure includes:
tsconfig.jsonjson
{
"compilerOptions": {
"types": ["maz-ui/types"]
}
}错误信息:
原因: 缺失类型定义或导入路径错误
修复方案:
Cannot find module 'maz-ui/components/MazBtn'typescript
// 正确导入方式
import MazBtn from 'maz-ui/components/MazBtn'
// 或使用Nuxt自动导入(无需手动导入)
// 直接使用<MazBtn>即可确保包含:
tsconfig.jsonjson
{
"compilerOptions": {
"types": ["maz-ui/types"]
}
}5. Phone Input Country Detection Fails
5. 手机号输入框国家检测失败
Error: doesn't detect country or shows wrong flag
Cause: Missing libphonenumber-js dependency or country data not loaded
Fix:
MazInputPhoneNumberbash
undefined错误信息: 无法检测国家或显示错误国旗
原因: 缺失libphonenumber-js依赖或未加载国家数据
修复方案:
MazInputPhoneNumberbash
undefinedInstall 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 instead of translated text
Causes:
inputPhoneNumber.phoneInput.example- Missing locale import
- Lazy loading not awaited properly
- Language file failed to load asynchronously
- Missing configuration
preloadFallback - 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 for comprehensive i18n setup, lazy loading strategies, and production patterns.
references/translations.md错误信息: 翻译键显示为原始字符串,如,而非翻译后的文本
原因:
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>了解更多: 加载获取全面的i18n配置、懒加载策略及生产实践
references/translations.mdTree-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 (, , ) for optimal bundle size, lazy load components with dynamic imports, and split code by feature. Load for comprehensive bundle optimization strategies.
MazComponentsResolverMazDirectivesResolverMazModulesResolverperformance.md通过策略性导入和摇树优化,Maz-UI的包体积可从约300KB减少到约15KB。使用自动导入解析器(、、)实现最优包体积,通过动态导入懒加载组件,按功能拆分代码。加载****获取全面的包体积优化策略。
MazComponentsResolverMazDirectivesResolverMazModulesResolverperformance.mdSSR & 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 . Load for critical CSS patterns, dark mode without flash, and SSR/SSG checklist.
<ClientOnly>ssr-ssg.md完整支持服务端渲染和静态站点生成,提供三种主题策略:混合模式(注入关键CSS,无FOUC)、构建时模式(包体积最小,静态主题)、运行时模式(完整主题切换,包体积较大)。通过将仅客户端组件包裹在中避免水合不匹配。加载****获取关键CSS方案、无闪烁深色模式及SSR/SSG检查清单。
<ClientOnly>ssr-ssg.mdAccessibility
可访问性
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 for keyboard shortcuts, focus trap patterns, and accessibility testing checklist.
accessibility.md所有Maz-UI组件均符合WCAG 2.1 AA标准,具备正确的ARIA属性、键盘导航、焦点管理及屏幕阅读器支持。组件包含语义化HTML、>4.5:1的颜色对比度及可访问的表单验证。加载****获取键盘快捷键、焦点捕获方案及可访问性测试清单。
accessibility.mdForm Validation
表单验证
The 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 for comprehensive validation patterns and real-world examples.
useFormValidator()form-validation.mduseFormValidator()form-validation.mdAuto-Import Resolvers
自动导入解析器
Critical for tree-shaking: Use and 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 for complete resolver configuration and troubleshooting.
unplugin-vue-componentsunplugin-auto-importresolvers.md摇树优化的关键: 使用和配合Maz-UI解析器,仅导入所需内容。与全局导入相比,可减少60-90%的包体积。配置前缀处理避免与其他库命名冲突。加载****获取完整的解析器配置及故障排除指南。
unplugin-vue-componentsunplugin-auto-importresolvers.mdProgressive 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