MuzhiyuUI 极奢全端组件库

MuzhiyuUI 是一套专为 UniApp + Vue 3 打造的全端极奢 UI 组件库。包含 90+ 生产级高频组件、Axios 级拦截器 HTTP 客户端、格式化与正则校验工具箱、TypeScript 全量智能提示 以及 全平台暗黑模式原生适配。

🌟 核心特性 (Key Features)

• ⚡ Vue 3 + <script setup> 驱动：全量采用 Vue 3 Composition API 重构，逻辑清晰，性能卓越；
• 📘 TypeScript 原生类型支持：内置 index.d.ts 声明文件与 @vue/runtime-core 全局组件模板智能补全，提供极其流畅的 IDE 编码体验；
• 🎨 极奢流光美学设计：拒绝大众平庸调色，采用现代微渐变、毛玻璃浮岛、Bento 悬浮卡片与动效细节；
• 📱 100% 微信小程序 + H5 + App 全端兼容：重构虚拟节点 virtualHost: true，彻底消除小程序自定义组件壳导致的 Flex 错位与样式压缩问题；
• 🌙 原生暗黑模式 (Dark Mode)：全量组件支持 prefers-color-scheme: dark 自动跟从系统深色切换；
• 📦 支持 easycom 按需加载：无需手动 import 组件，随用随写，打包体积小巧；
• 🛠️ 完整工具链集结 ($mu)：自带网络请求拦截器 (http)、表单正则校验 (validate)、脱敏/格式化 (format) 与颜色计算器 (color)。

📦 目录结构 (Directory Structure)

uni_modules/muzhiyu-ui/
├── components/            <-- 90+ 核心 UI 组件
├── utils/                 <-- 统一网络请求与工具函数
│   ├── request.js         <-- HTTP 客户端拦截器
│   └── index.js           <-- 正则/格式化/脱敏工具箱
├── index.js               <-- Vue 3 插件注册入口
├── index.d.ts             <-- TypeScript 全量类型声明文件
├── theme.scss             <-- 全局 SCSS 主题变量
└── package.json           <-- 插件市场配置文件

🚀 快速上手 (Quick Start)

方式一：作为 uni_modules 使用（推荐）

1. 在 DCloud 插件市场点击 “导入到 HBuilderX” 或下载解压至项目的 uni_modules/muzhiyu-ui 目录下；
2. 打开项目的 pages.json，配置 easycom 按需自动解析规则：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^mu-(.*)": "@/uni_modules/muzhiyu-ui/components/mu-$1/mu-$1.vue"
    }
  }
}

配置完成后，无需在任何页面引入，直接在 .vue 模板中使用组件即可！

方式二：作为 npm 包使用

1. 在项目根目录终端运行安装命令：

   npm install muzhiyu-ui

2. 在 pages.json 中配置 easycom：

   {
     "easycom": {
       "autoscan": true,
       "custom": {
         "^mu-(.*)": "muzhiyu-ui/components/muzhiyu/mu-$1/mu-$1.vue"
       }
     }
   }

🛠️ 全局挂载与工具函数 ($mu)

在 main.js 中挂载全局插件：

import { createApp } from 'vue'
import App from './App.vue'
import muzhiyuUI from 'muzhiyu-ui'

const app = createApp(App)
app.use(muzhiyuUI)
app.mount('#app')

在页面中零 import 全局调用 (uni.$mu)：

挂载后，可以在任何页面、<script setup>、工具 JS 或 Pinia/Vuex 中零 import 直接调用原生 uni.$mu：

// 1. 发起网络请求 (支持全局拦截器)
uni.$mu.http.get('/api/user/info', { id: 1001 }).then(res => {
  console.log('用户信息:', res)
})

// 2. 快捷 JS Toast 弹窗 / Notify 通知
uni.$mu.toast('保存成功', 'success')
uni.$mu.notify({ message: '预约确认成功', type: 'success' })

// 3. 手机号脱敏
console.log(uni.$mu.util.maskPhone('13812345678')) // "138****5678"

// 4. 正则校验
console.log(uni.$mu.validate.isEmail('[email protected]')) // true

📚 90+ 核心组件全景清单

1. 基础组件 (Basic)

| 组件名 | 说明 | 示例标签 | | :--- | :--- | :--- | | mu-button | 极奢按钮（支持流光、圆角、加载、禁用与各种尺寸） | <mu-button type="primary">确认提交</mu-button> | | mu-image | 极奢图片（支持骨架屏占位、失败降级、圆角/头像、全屏预览、淡入） | <mu-image src="..." width="200" height="200" preview /> | | mu-icon | 矢量图标（内置 100+ 高频极简图标库） | <mu-icon name="heart" size="24" color="#F43F5E" /> | | mu-cell | 单元格组（支持图标、箭头、副标题与右侧插槽） | <mu-cell title="个人资料" is-link /> | | mu-tag | 标签（支持渐变、镂空、胶囊与点状） | <mu-tag type="success">已完成</mu-tag> | | mu-badge | 徽标角标（数字角标与小红点） | <mu-badge :count="99"><view>消息</view></mu-badge> | | mu-divider | 分割线（支持带有文案或纯线） | <mu-divider text="我是有底线的" /> | | mu-space | 垂直/水平弹性留白距 | <mu-space height="30" /> | | mu-blank | 两侧固定留白容器 | <mu-blank width="32">内容...</mu-blank> |

2. 表单与输入组件 (Form & Inputs)

| 组件名 | 说明 | 示例标签 | | :--- | :--- | :--- | | mu-input | 文本输入框（带清除、前后缀、密码切换） | <mu-input v-model="form.name" placeholder="请输入姓名" /> | | mu-checkbox | 复选框与复选框组 | <mu-checkbox-group v-model="checkedList">...</mu-checkbox-group> | | mu-radio | 单选框与单选框组 | <mu-radio-group v-model="radioVal">...</mu-radio-group> | | mu-switch | 异步开关 | <mu-switch v-model="enabled" /> | | mu-rate | 评分组件（支持半星与自定义图标） | <mu-rate v-model="score" allow-half /> | | mu-slider | 滑块选择器 | <mu-slider v-model="volume" /> | | mu-upload | 多图/视频上传（支持进度条、预览与删除） | <mu-upload v-model:file-list="fileList" /> | | mu-code-input | 验证码/密码分割输入框 | <mu-code-input :length="6" v-model="code" /> | | mu-signature | 手写电子签名板（输出 Canvas 图像） | <mu-signature @confirm="onSignDone" /> |

3. 布局与容器组件 (Layout)

| 组件名 | 说明 | 示例标签 | | :--- | :--- | :--- | | mu-grid | 宫格布局（金刚区、Bento 悬浮卡片、支持 border 与 square） | <mu-grid :columns="4" border><mu-grid-item text="首页" /></mu-grid> | | mu-card | 奢华卡片容器（支持封面、标题与底部操作栏） | <mu-card title="VisionOS 规范" cover="..." /> | | mu-waterfall | 动态瀑布流布局（双列贪心算法自动分配高度） | <mu-waterfall :data="goodsList" /> | | mu-table | 高级表格（支持表头固定、左右固定列与斑马纹） | <mu-table :columns="cols" :data="tableData" /> |

4. 导航与选项卡 (Navigation)

| 组件名 | 说明 | 示例标签 | | :--- | :--- | :--- | | mu-navbar | 顶部导航栏（支持沉浸式、返回按键与自定义插槽） | <mu-navbar title="订单详情" :is-back="true" /> | | mu-tabs | 选项卡（支持滚动、居中、居左与 sticky 原生粘性吸顶） | <mu-tabs :tabs="tabList" sticky :offset-top="0" /> | | mu-tabbar | 底部导航栏（普通模式、悬浮毛玻璃浮岛模式、异形凸起模式） | <mu-tabbar :items="tabbarItems" mode="island" /> | | mu-sidebar | 联动侧边导航栏 | <mu-sidebar :options="categories" v-model:active="activeIdx" /> | | mu-steps | 步骤条 | <mu-steps :options="stepList" :current="1" /> | | mu-index-list | 拼音首字母索引列表（通讯录风格） | <mu-index-list :data="cityData" /> |

5. 反馈与弹层组件 (Feedback & Modals)

| 组件名 | 说明 | 示例标签 | | :--- | :--- | :--- | | mu-modal | 极奢对话框（支持异步按钮与插槽自定义） | <mu-modal v-model:show="showModal" title="确认提示" /> | | mu-toast | 快捷消息轻提示 | this.$refs.toast.show({ title: '保存成功' }) | | mu-notify | 顶部通知提醒栏 | this.$refs.notify.show({ type: 'warning', message: '网络异常' }) | | mu-popup | 多方向弹出层（顶部/底部/左侧/右侧） | <mu-popup v-model:show="showPopup" position="bottom">...</mu-popup> | | mu-cropper | 高性能图片裁剪器（支持旋转、缩放与正方形/圆形导出） | <mu-cropper :src="tempImg" @confirm="onCropped" /> |

💻 典型代码使用范例

1. 吸顶 Tabs 与 4 列金刚区 Demo

<template>
  <view class="container">
    <!-- 1. 吸顶选项卡 -->
    <mu-tabs :tabs="categoryTabs" :current="activeTab" sticky :offset-top="0" @change="activeTab = $event" />

    <!-- 2. 经典 4 列金刚区 -->
    <mu-grid :columns="4" border>
      <mu-grid-item v-for="(item, i) in gridList" :key="i" :text="item.name" :icon="item.icon" :badge="item.badge" />
    </mu-grid>
  </view>
</template>

<script setup>
import { ref } from 'vue'
const activeTab = ref(0)
const categoryTabs = ['精选推荐', '热门排行', '最新上架', '手机数码']
const gridList = [
  { name: '扫一扫', icon: 'scan', badge: 0 },
  { name: '付款码', icon: 'qr_code', badge: 0 },
  { name: '卡券包', icon: 'credit_card', badge: 'HOT' },
  { name: '消息', icon: 'message', badge: 5 }
]
</script>

📄 开源协议 (License)

MIT License