在微信生态开发中，你是否曾遇到过这样的困扰：精心设计的网页在微信内置浏览器中打开时，总感觉“格格不入”——按钮风格不一致、弹窗动画不协调、页面滚动体验生硬。这不是你的设计能力问题，而是因为微信客户端有着自己独特的视觉语言和交互规范。
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 的设计可以概括为以下几个核心原则：
1.一致性
WeUI 严格遵循微信客户端的视觉规范，从颜色、字体、间距到圆角、阴影，都力求与微信原生界面保持高度一致。这意味着使用 WeUI 构建的应用，用户在微信内打开时会感到“熟悉”和“亲切”，不会有割裂感。
2.轻量性
WeUI 本质上是一个 CSS 样式库，不依赖任何 JavaScript 框架。这种“纯样式”的设计使得 WeUI 可以无缝集成到任何技术栈中——无论是原生 HTML/JS 项目，还是 Vue、React 等现代框架，甚至微信小程序。
3.移动优先
WeUI 专门为移动端触摸交互优化，所有组件的点击区域、间距、字体大小都符合移动端设计规范。按钮最小点击区域为 44x44pt，确保手指触控的准确性。
4.可扩展性
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://oplhc.cn
