快速上手

本文带你从零开始引入 mural-plus，并在页面中跑通第一个组件。

环境准备

• HBuilderX 4.31 及以上。
• 新建「uni-app x」项目（Vue3）。

引入组件库

mural-plus 以 uni_modules 形式发布，二选一：

• 在 HBuilderX 中通过插件市场导入到项目 uni_modules 目录；
• 或直接把 mural-plus 目录复制到项目的 uni_modules 下。

引入后，组件会作为 easycom 组件全局自动注册，无需手动 import。

引入样式

引入样式变量

在项目根目录 uni.scss 中引入变量文件：

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

引入全局样式

在 App.uvue 中引入全局样式（生成 CSS 变量、主题与工具类）：

<style lang="scss">
	@import "@/uni_modules/mural-plus/index.scss";
</style>

使用组件

在任意页面中直接使用 mu- 前缀标签：

<template>
	<mu-button type="primary">主要按钮</mu-button>
</template>

常见用法

页面骨架

使用 mu-page 作为页面容器，配合 mu-navbar 头部：

<template>
	<mu-page bg-color="var(--mu-bg-color)">
		<template #header>
			<mu-navbar title="页面标题"></mu-navbar>
		</template>

		<view class="content">
			<text>页面内容</text>
		</view>
	</mu-page>
</template>

列表

mu-cell-group 与 mu-cell 组合展示设置项：

<template>
	<mu-cell-group :inset="true" title="账号与安全">
		<mu-cell title="昵称" value="Mural" is-link></mu-cell>
		<mu-cell title="消息通知">
			<mu-switch :size="36"></mu-switch>
		</mu-cell>
	</mu-cell-group>
</template>

表单

mu-form 与 mu-form-item 组合，配合 model 与 rules 校验：

<template>
	<mu-form ref="formRef" :model="form" :rules="rules">
		<mu-form-item prop="name" label="用户名">
			<mu-field v-model="form.name" placeholder="请输入用户名"></mu-field>
		</mu-form-item>
	</mu-form>
	<mu-button type="primary" @click="onSubmit">提交</mu-button>
</template>

<script setup lang="uts">
	import { reactive, ref } from 'vue'

	const form = reactive({ name: '' })
	const rules = { name: [{ required: true, message: '请输入用户名' }] }
	const formRef = ref(null)

	const onSubmit = () => {
		formRef.value?.validate?.((valid : boolean) => {
			if (valid) {
				uni.showToast({ title: '校验通过', icon: 'none' })
			}
		})
	}
</script>

弹层与提示

弹层类组件通过 show 受控，消息类组件通过 ref 调用方法：

<template>
	<mu-button type="primary" @click="show = true">打开弹窗</mu-button>
	<mu-popup :show="show" position="center" @close="show = false">
		<view class="popup-body">
			<text>弹层内容</text>
		</view>
	</mu-popup>
</template>

<script setup lang="uts">
	import { ref } from 'vue'
	const show = ref(false)
</script>

主题

mural-plus 内置亮色 / 暗黑主题，可通过系统或手动切换。详见暗黑模式。

运行

在 HBuilderX 中通过「运行」菜单选择目标平台：

• 运行到浏览器（Web）
• 运行到小程序模拟器
• 运行到手机或模拟器（App）

常见问题

• 组件样式不生效：确认已在 uni.scss 与 App.uvue 中引入样式文件。
• 暗黑模式不切换：确认已完成暗黑模式中的配置，且页面内容位于 mu-page 内。
• 方法不生效：validate、open、close 等需通过 ref 获取组件实例后调用。