样式覆盖与主题指南 v1.0.0
MuzhiyuUI 专为 UniApp 全端打造，内置 SCSS 极奢设计 Token 变量、4 种组件样式覆盖机制、微信小程序虚拟节点 (virtualHost) 穿透 与 原生暗黑模式。
💅 1. 组件样式的 4 种覆盖层级
在实际开发中，如果需要对组件外观进行个性化微调，可以通过以下 4 种层级的方式灵活覆盖样式：
方式 1：使用组件专用 Style / Prop 快捷覆盖（推荐首选）
几乎所有 MuzhiyuUI 组件都内置了 background、color、width、height、padding、margin 等快捷样式属性，直接传值即可覆盖：
<!-- 自定义渐变背景与文本颜色 -->
<mu-button background="linear-gradient(135deg, #6366F1, #A855F7)" color="#FFFFFF">
极奢渐变按钮
</mu-button>
<!-- 自定义容器宽高与内边距 -->
<mu-card width="100%" padding="32rpx" background="#F8FAFC">
卡片内容
</mu-card>方式 2：使用 customStyle 内联样式对象/字符串
组件均支持 :customStyle 接收一个 Style 对象或者字符串，直接作用于组件的最外层核心节点：
<!-- 对象写法 (支持 rpx 与 px) -->
<mu-button :customStyle="{ borderRadius: '24rpx', boxShadow: '0 8rpx 24rpx rgba(99,102,241,0.3)' }">
圆角按钮
</mu-button>
<!-- 字符串写法 -->
<mu-button customStyle="margin-top: 20rpx; letter-spacing: 2rpx;">
外边距按钮
</mu-button>方式 3：使用传统 class 扩展类名
支持直接在组件标签上挂载自定义 CSS 类名，结合页面的 <style scoped> 进行样式修饰：
<template>
<mu-button class="my-custom-btn">自定义类名按钮</mu-button>
</template>
<style scoped>
.my-custom-btn {
transform: translateY(-4rpx);
transition: all 0.25s ease;
}
</style>方式 4：Vue 3 :deep() 穿透选择器覆盖内部子节点
如果需要深层次修改组件内部的 HTML/WXML 子节点样式，请使用 Vue 3 官方推荐的 :deep() 深度作用选择器：
<template>
<mu-input class="custom-input" placeholder="请输入内容" />
</template>
<style scoped lang="scss">
/* 深度修改 input 组件内部占位符的颜色与字号 */
.custom-input :deep(.mu-input__placeholder) {
color: #6366F1;
font-size: 24rpx;
}
</style>⚡ 2. 微信小程序虚拟节点 (virtualHost) 穿透
为了彻底解决微信小程序中自定义组件会被一层默认的 <mu-button> 或 <mu-card> 标签包裹导致 Flex 轴向错位、width: 100% 不生效 的痛点，MuzhiyuUI 所有组件默认启用了微信原生虚拟节点：
// 组件内部配置
options: {
virtualHost: true // 将组件最外层虚拟化，消除小程序标签阻断
}虚拟节点特性说明
启用 virtualHost: true 后：
- 组件直接融入父级的 Flex / Grid 布局中，不需要额外写
display: block。 - 在小程序端使用
class或customStyle赋值时，样式会直接无缝挂载到组件的实际 DOM 节点上。
🎨 3. SCSS 全局设计 Token 变量
在项目根目录 uni.scss 中引入并覆盖默认 SCSS 变量，即可完成全局品牌颜色的重构：
/* 替换极奢主色调 */
$mu-primary: #6366F1; // 品牌主色
$mu-primary-gradient: linear-gradient(135deg, #6366F1, #A855F7); // 主色渐变
$mu-success: #10B981; // 成功色
$mu-warning: #F59E0B; // 警告色
$mu-error: #F43F5E; // 错误/危险色
$mu-info: #38BDF8; // 信息色
/* 移动端 Squircle 圆角矩阵 */
$mu-radius-xs: 6rpx; // 极小标签圆角
$mu-radius-sm: 10rpx; // 小号按钮圆角
$mu-radius-md: 16rpx; // 移动端标准触控圆角 (iOS/Android)
$mu-radius-lg: 20rpx; // 大号卡片圆角
$mu-radius-xl: 24rpx; // 面板容器圆角
$mu-radius-full: 999rpx; // 胶囊全圆角
/* 弥散光晕阴影 */
$mu-shadow-sm: 0 4rpx 14rpx rgba(15, 23, 42, 0.03);
$mu-shadow-md: 0 12rpx 32rpx -4rpx rgba(15, 23, 42, 0.06);
$mu-shadow-button-primary: 0 10rpx 28rpx -4rpx rgba(23, 23, 23, 0.35);
/* 动效贝塞尔曲线 */
$mu-ease: cubic-bezier(0.32, 0.72, 0, 1);
$mu-ease-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275);🌙 4. 暗黑模式与主题色冲突解决方案 (双轨制主题色系统)
在深色背景下，如果直接使用亮色模式的主题色（如较深的蓝色或紫色），可能会因为对比度不足显得沉闷或看不清。
MuzhiyuUI 提出了 双轨制动态主题色 (Dual-Track Primary Tokens) 解决方案：
1. 亮色模式主题色 (Light Primary)
- 品牌主色：
$mu-primary: #6366F1（饱满的靛蓝） - 主色渐变：
$mu-primary-gradient: linear-gradient(135deg, #6366F1, #A855F7)
2. 暗黑模式自适应高亮主题色 (Dark Primary Shift)
当进入暗黑模式 (.mu-dark 或 @media (prefers-color-scheme: dark)) 时，组件库自动将文本、图标、激活状态的主题色向上提升明度（WCAG AA 级高对比度标准）：
- 暗黑主色：
$mu-dark-primary: #818CF8（高亮透蓝紫，在纯黑背景下极其清澈透亮） - 暗黑渐变：
$mu-dark-primary-gradient: linear-gradient(135deg, #818CF8, #C084FC)
/* 在 uni.scss 中自由定制暗黑主题色提频 */
$mu-dark-primary: #818CF8;
$mu-dark-primary-gradient: linear-gradient(135deg, #818CF8 0%, #C084FC 100%);🌙 5. 暗黑模式触发机制
自动响应系统深色模式
组件库全量配置了 CSS 媒体查询 @media (prefers-color-scheme: dark)。当手机系统或微信客户端开启暗黑模式时，所有组件背景、文本与分割线会自动转换为 OLED 极奢深色：
@media (prefers-color-scheme: dark) {
/* 自动转换为暗黑视觉 */
}手动控制页面深色模式
如果需要在 app/小程序内部通过代码手动控制开关，只需在页面顶层根视图添加 .mu-dark 类名：
<template>
<view :class="{ 'mu-dark': isDark }">
<mu-card title="卡片标题">
暗黑模式内容展示
</mu-card>
</view>
</template>
<script setup>
import { ref } from 'vue'
const isDark = ref(true) // 手动开启暗黑模式
</script>🛠️ 5. 内置通用样式工具类
组件库内置了一系列高频 CSS 实用工具类，可在任意页面直接使用：
| 类名 | 功能说明 |
|---|---|
.mu-touchable-flat | 给点击元素添加微缩放物理按压触控反馈动画 |
.mu-spin-pulse | 让元素持续 360 度顺时针旋转 (常用于 Loading) |
.mu-text-ellipsis | 单行文本超长自动省略号 (...) |
.mu-text-ellipsis-2 | 双行文本超长自动省略号 (...) |