在微信生态开发中，你是否曾遇到过这样的困扰：精心设计的网页在微信内置浏览器中打开时，总感觉“格格不入”——按钮风格不一致、弹窗动画不协调、页面滚动体验生硬。这不是你的设计能力问题，而是因为微信客户端有着自己独特的视觉语言和交互规范。
WeUI正是为解决这一问题而生的官方解决方案。它是由微信官方设计团队量身定制的一套基础样式库，其核心目标是让第三方Web应用能够获得与微信客户端原生界面完全一致的视觉和交互体验。从微信安全中心、微信意见反馈到各类公众号应用，WeUI已经在无数微信内部和外部的Web应用中得到了广泛验证。
本文将系统全面地梳理WeUI的核心知识点，从其设计哲学到组件体系，从微信小程序集成到现代Vue/React项目使用，从暗色模式适配到性能优化，帮助读者全面掌握这一微信生态开发的必备工具。
特别说明：WeUI主要有两个技术分支——WeUI（基础CSS库，适用于普通网页）和WeUI.js（基于jQuery的交互组件库，现已较少使用）。此外，微信小程序有专门的weui-miniprogram版本。本文将以WeUI基础样式库为核心，同时涵盖各分支的关键知识点。
一、WeUI概述
1.1 什么是WeUI
WeUI是一套由微信官方设计团队开发的、与微信原生视觉体验一致的基础样式库。它不是一个重型的JavaScript框架，而是一套轻量级的CSS样式规范，开发者只需在HTML中引用样式文件，并使用约定的class名称，即可快速构建出与微信客户端风格统一的界面。
WeUI的核心价值可以概括为：
1.2 WeUI的诞生背景
在2015年初，微信开放了JS-SDK，开发者可以借助微信的账号体系、JS-SDK功能以及公众号接口，开发出功能强大的Web应用。然而，一个普遍的问题是：功能齐全但界面体验却不佳，缺乏专业的交互/视觉设计。
微信团队注意到这一痛点，于是将内部沉淀多年的基础组件库重新梳理，于2015年10月在GitHub正式开源，取名WeUI。开发者可以使用这套UI库，快速构建出美观、易用的Web界面，让第三方应用也能获得与微信官方应用一致的视觉体验。
1.3 WeUI的组件体系
WeUI的组件按照功能可以分为以下几大类：
每个组件都有明确定义的CSS类名和HTML结构，开发者可以直接复制使用。
1.4 WeUI的设计哲学
WeUI的设计可以概括为以下几个核心原则：
- 一致性
WeUI严格遵循微信客户端的视觉规范，从颜色、字体、间距到圆角、阴影，都力求与微信原生界面保持高度一致。这意味着使用WeUI构建的应用，用户在微信内打开时会感到“熟悉”和“亲切”，不会有割裂感。
- 轻量性
WeUI本质上是一个CSS样式库，不依赖任何JavaScript框架。这种“纯样式”的设计使得WeUI可以无缝集成到任何技术栈中——无论是原生HTML/JS项目，还是Vue、React等现代框架，甚至微信小程序。
- 移动优先
WeUI专门为移动端触摸交互优化，所有组件的点击区域、间距、字体大小都符合移动端设计规范。按钮最小点击区域为44x44pt，确保手指触控的准确性。
- 可扩展性
WeUI的样式基于Less预处理器编写，提供了丰富的变量系统，开发者可以轻松定制主题色、圆角大小、间距等，以满足品牌定制需求。
二、安装与集成
2.1 在普通网页中使用
方式一：CDN引入（最快速）
这是最简单的方式，适合快速原型开发或简单页面：
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width,initial-scale=1,user-scalable=0">
<title>WeUI Demo</title>
<!-- 引入WeUI样式 -->
<link rel="stylesheet" href="https://res.wx.qq.com/open/libs/weui/2.4.4/weui.min.css">
</head>
<body>
<!-- 页面内容 -->
<div class="weui-btn weui-btn_primary">主要按钮</div>
</body>
</html>
关键点：必须添加viewport meta标签，确保移动端适配正常。user-scalable=0可以防止用户缩放页面，保持设计精度。
方式二：npm安装
对于使用构建工具的项目，推荐使用npm安装：
npm install weui
在项目中引入样式：
// 在入口文件中
import 'weui';
// 或直接引入CSS文件
import 'weui/dist/style/weui.min.css';
2.2 在Vue项目中使用
WeUI可以轻松集成到Vue项目中，有以下几种方式：
方式一：全局引入样式
// main.js
import { createApp } from 'vue';
import App from './App.vue';
import 'weui'; // 引入WeUI样式
createApp(App).mount('#app');
在Vue组件中使用WeUI样式：
<template>
<div>
<button class="weui-btn weui-btn_primary">主要按钮</button>
<button class="weui-btn weui-btn_default">默认按钮</button>
</div>
</template>
方式二：自定义WeUI Vue组件
为了更好的复用性和类型提示，可以将WeUI组件封装为Vue组件：
<!-- components/WeButton.vue -->
<template>
<button :class="buttonClass" :disabled="disabled">
<slot />
</button>
</template>
<script setup>
import { computed } from 'vue';
const props = defineProps({
type: { type: String, default: 'default' }, // primary, default, warn
disabled: { type: Boolean, default: false },
size: { type: String, default: 'normal' } // normal, small
});
const buttonClass = computed(() => {
return [
'weui-btn',
props.type === 'primary' && 'weui-btn_primary',
props.type === 'warn' && 'weui-btn_warn',
props.size === 'small' && 'weui-btn_mini',
props.disabled && 'weui-btn_disabled'
].filter(Boolean).join(' ');
});
</script>
方式三：自定义样式覆盖
如果需要定制WeUI样式，可以创建自定义CSS文件覆盖：
/* custom.css */
.custom-btn {
background-color: #ff0000;
color: #ffffff;
}
<template>
<button class="weui-btn custom-btn">自定义按钮</button>
</template>
2.3 在微信小程序中使用
微信小程序有专门的weui-miniprogram版本。
步骤一：初始化npm
在小程序项目根目录下执行：
npm init -y
npm install --save weui-miniprogram
步骤二：构建npm
在微信开发者工具中：工具 → 构建npm。构建成功后，项目根目录会出现miniprogram_npm目录。
步骤三：引入WeUI样式
在应用的全局样式文件（如app.wxss）中引入：
@import './miniprogram_npm/weui-miniprogram/weui-wxss/dist/style/weui.wxss';
步骤四：使用WeUI组件
现在可以在小程序的wxml文件中使用WeUI的样式类：
<view class="weui-btn weui-btn_primary">主要按钮</view>
2.4 在小程序中使用useExtendedLib（推荐）
对于小程序项目，更推荐使用微信官方提供的扩展库方式，这种方式无需下载npm包，直接在小程序后台配置即可：
// app.json
{
"useExtendedLib": {
"weui": true
}
}
这种方式下，WeUI的样式会自动注入，无需手动引入，也不会占用小程序的包体积。微信官方会持续更新这个扩展库，确保与最新微信版本兼容。
来源：
http://lemci.cn/
