Mural Plus

暗黑模式 ​

mural-plus 内置亮色 / 暗黑两套主题，基于 CSS 变量实现，可跟随系统、手动切换，并支持自定义品牌色。

工作原理 ​

组件样式统一使用 --mu-* 形式的 CSS 变量（如 --mu-bg-color、--mu-text-main-color、--mu-color-primary），采用「亮色默认、暗色覆盖」的方式定义：

  • 亮色：变量挂在页面根节点（小程序 / App 的 page，Web 的 html、uni-app）上。
  • 暗色：通过 .theme-dark 类覆盖同一批变量。
  • 跟随系统：@media (prefers-color-scheme: dark) 命中时自动应用暗色变量。

因此，只要切换 .theme-dark 类（或系统主题），所有组件外观会同步变化，无需逐个修改组件样式。

引入 ​

请先按快速上手完成组件库引入（其全局样式 index.scss 会生成主题所需的 CSS 变量），再完成以下两步即可启用暗黑模式。

初始化主题 ​

在 App.uvue 启动时调用 initTheme()，读取并恢复上次保存的主题：

html
<script setup lang="uts">
	import { initTheme } from "@/uni_modules/mural-plus/libs/theme.uts"

	onLaunch(() => {
		initTheme()
	})
</script>

开启暗黑能力 ​

在 manifest.json 中按平台开启 darkmode：

json
{
	"mp-weixin": { "darkmode": true },
	"web": { "darkmode": true },
	"app": { "defaultAppTheme": "auto" }
}

同时建议在 theme.json 中配置 App 端原生导航栏、TabBar 的明暗配色，使其与页面主题一致。

使用暗黑模式 ​

方式一：跟随系统（默认） ​

不做任何手动切换即可。组件通过 @media (prefers-color-scheme: dark) 自动跟随系统深浅色。

方式二：手动切换 ​

mu-page 作为页面容器，会自动依据 themeState.isDark 在根节点添加 theme-dark 类。用 mu-page 包裹页面内容，再用开关控制 themeState.isDark，即可全局切换：

html
<template>
	<mu-page bg-color="var(--mu-bg-color)">
		<template #header>
			<mu-navbar title="主题演示">
				<mu-switch v-model="themeState.isDark" :size="40" @change="onThemeChange"></mu-switch>
			</mu-navbar>
		</template>

		<view class="content">
			<mu-card title="暗黑模式演示" subtitle="切换右上角开关查看效果">
				<view class="row">
					<mu-button type="primary">主要按钮</mu-button>
					<mu-button plain type="success">成功按钮</mu-button>
				</view>
				<mu-cell-group :inset="true">
					<mu-cell title="单元格标题" value="内容" is-link></mu-cell>
					<mu-cell title="开关项">
						<mu-switch :size="36"></mu-switch>
					</mu-cell>
				</mu-cell-group>
			</mu-card>
		</view>
	</mu-page>
</template>

<script setup lang="uts">
	import { themeState, persistTheme } from "@/uni_modules/mural-plus/libs/theme.uts"

	const onThemeChange = (value : boolean) => {
		persistTheme(value)
	}
</script>

<style lang="scss">
	.content {
		display: flex;
		flex-direction: column;
		padding: 40rpx;
	}

	.row {
		display: flex;
		flex-direction: row;
		gap: 16rpx;
		margin-bottom: 24rpx;
	}
</style>

persistTheme(dark) 会：更新 themeState.isDark、写入本地缓存、并在 App 端调用 uni.setAppTheme 同步原生容器。下次启动时 initTheme() 会自动恢复上次的选择。

不使用 mu-page 时 ​

若页面没有使用 mu-page，需要自行给根节点绑定 theme-dark 类，否则不会随 themeState 变化：

html
<template>
	<view class="page" :class="{ 'theme-dark': themeState.isDark }">
		<view class="my-box">内容</view>
	</view>
</template>

自定义主题色 ​

CSS 变量（运行时） ​

在页面或容器上覆盖变量即可，作用范围随所在节点：

scss
.my-brand {
	--mu-color-primary: #8B5CF6;
}

SCSS 变量（编译期，全局品牌色） ​

在 uni.scss 中、引入组件变量文件之前重定义 $colors 或 $mu-color-*：

scss
$colors: (
	primary: #8B5CF6
);

@import "@/uni_modules/mural-plus/libs/css/variables.scss";

内置变量一览 ​

变量说明
--mu-color-primary / -success / -warning / -error / -danger / -info语义色
--mu-color-white / --mu-color-black亮暗两态的基础前景/背景色（暗色下自动互换）
--mu-text-main-color / -base-color / -secondary-color / -extra-color文本层级颜色
--mu-border-color边框色
--mu-bg-color / --mu-bg-default-color页面与控件背景色
--mu-active-color激活 / hover 背景色
--mu-placeholder-color / --mu-placeholder-base-color占位底色

注意事项 ​

  • 平台差异：小程序、App、Web 均支持。App 端手动切换会通过 uni.setAppTheme 同步原生容器，建议同时在 theme.json 配置明暗两套原生配色；小程序端需在 manifest.json 开启 darkmode 才会响应系统深色。
  • 使用注意：手动切换依赖 mu-page 自动挂载的 theme-dark 类，页面内容需处于 mu-page 内（或自行给根节点绑定该类）。
  • 使用注意：initTheme() 应在 App.uvue 的 onLaunch 中调用一次，用于恢复上次保存的主题。
  • 使用注意：业务页面请使用 --mu-* 变量而非写死颜色，才能随主题自动适配。