WeUI

微信官方设计团队为微信内网页和微信小程序量身打造的基础样式库，与微信原生视觉体验保持高度一致。

技术简介说明

WeUI 由微信官方设计团队发起并持续维护，是微信生态中最具"官方血统"的 UI 基础设施。它的核心使命是让运行在微信环境中的网页（H5）和小程序，拥有与微信客户端原生界面一致的视觉体验，从而降低用户在微信内外切换时的认知成本。

WeUI 的设计哲学是极度克制——它不追求组件数量上的大而全，而是精选微信视觉体系中最常用的基础元素（Button、Cell、Dialog、Toast、ActionSheet 等），以纯 CSS 样式库的形式提供，配合轻量级 JS 交互封装，做到开箱即用、零学习成本。这种克制使得它在微信生态中具有不可替代的"正统性"。

从技术架构看，WeUI 已发展为一个多仓库、多平台的完整生态：Web/H5 端使用 weui（CSS）+ weui.js（JS 交互）；微信小程序端使用 weui-wxss（样式库）+ weui-miniprogram（扩展组件库）。此外还有 React-WeUI、Taro-WeUI 等社区适配方案，覆盖了微信生态的主要技术栈。

基本信息

• 官网：https://weui.io/
• GitHub：
  • Web/H5 样式库：https://github.com/Tencent/weui（~11k+ Stars）
  • 小程序样式库：https://github.com/Tencent/weui-wxss（~15.3k Stars）
  • JS 交互库：https://github.com/weui/weui.js（~3.2k Stars）
  • 小程序扩展组件库：https://github.com/wechat-miniprogram/weui-miniprogram（~2.4k Stars）
• License：MIT
• 最新版本：
  • weui-wxss：v2.6.26（2026 年 3 月 12 日发布）
  • weui-miniprogram：v1.0.8（GitHub Release）
• 主要维护者/公司：腾讯（Tencent）/ 微信事业群官方设计团队
• npm 包名：weui（H5）、weui-wxss（小程序样式）、weui-miniprogram（小程序组件）

快速上手

安装

方式一：微信小程序扩展库（推荐，零体积引入）

在 app.json 中声明即可，不计入小程序代码包大小：

{
  "useExtendedLib": {
    "weui": true
  }
}

方式二：NPM 安装 weui-wxss（样式库）

npm install weui-wxss --save

在 app.wxss 中引入：

@import '~weui-wxss/dist/style/weui.wxss';

方式三：NPM 安装 weui-miniprogram（扩展组件库）

npm install weui-miniprogram --save

在微信开发者工具中执行"构建 npm"，然后在页面 .json 中声明组件：

{
  "usingComponents": {
    "mp-dialog": "weui-miniprogram/dialog/dialog",
    "mp-tabs": "weui-miniprogram/tabs/tabs"
  }
}

方式四：Web/H5 引入

npm install weui --save

@import 'weui/dist/style/weui.min.css';

基础配置

微信小程序项目（app.json）：

{
  "useExtendedLib": {
    "weui": true
  },
  "window": {
    "navigationBarTitleText": "WeUI 示例",
    "navigationBarBackgroundColor": "#EDEDED"
  }
}

Web/H5 项目（搭配 weui.js）：

import WeUI from 'weui.js'
 
// 使用 JS 组件
WeUI.dialog({
  title: '提示',
  content: '这是一个 WeUI 对话框',
  buttons: [
    { label: '取消', type: 'default' },
    { label: '确定', type: 'primary' }
  ]
})

最小示例

微信小程序页面（.wxml）：

<view class="page">
  <view class="page__bd">
    <button class="weui-btn weui-btn_primary">主操作按钮</button>
    <button class="weui-btn weui-btn_default">次级按钮</button>
    <button class="weui-btn weui-btn_warn">警告按钮</button>
  </view>
</view>

核心概念与架构

WeUI 的架构按平台拆分为独立仓库，形成清晰的层次：

WeUI 生态
├── weui（Web/H5 样式库）
│   ├── 纯 CSS 样式，BEM 命名规范
│   └── 适配微信内嵌浏览器
│
├── weui.js（Web/H5 JS 交互层）
│   ├── Dialog、Toast、Picker、Slider 等交互组件
│   └── 零依赖，轻量封装
│
├── weui-wxss（小程序样式库）
│   ├── WXSS 格式，适配小程序样式系统
│   └── CSS 变量支持 DarkMode
│
├── weui-miniprogram（小程序扩展组件库）
│   ├── 自定义组件（Custom Component）格式
│   ├── 包含交互组件：Dialog、Tabs、Slideview 等
│   └── 支持 useExtendedLib 免体积引入
│
└── 社区适配
    ├── React-WeUI（React 版本）
    └── Taro-WeUI（Taro 跨端兼容）

设计原则：

1. 视觉一致性优先：所有组件严格遵循微信设计规范
2. 样式与逻辑分离：基础层是纯 CSS/WXSS 样式，交互层按需叠加
3. 渐进增强：从静态样式到动态组件，开发者可按需选择引入深度

核心特性

1. 微信原生视觉一致：与微信客户端 UI 保持高度统一，用户在微信内使用时体验无缝衔接
2. 零体积引入（小程序）：通过 useExtendedLib 声明即可使用，不占用小程序 2MB 代码包额度
3. DarkMode 支持：基于 CSS 变量系统实现深色模式适配，跟随系统主题自动切换
4. BEM 命名规范：CSS 类名采用 BEM（Block-Element-Modifier）规范，避免样式冲突，便于维护
5. CSS 变量主题定制：提供完整的颜色、字号、间距等变量体系，支持品牌色微调
6. 轻量无依赖：核心库为纯 CSS，JS 层零外部依赖，体积极小
7. 官方持续维护：微信设计团队直接维护，与微信客户端更新保持同步迭代
8. MIT 开源协议：完全开源，可自由用于商业项目
9. 多平台覆盖：一套设计规范，覆盖 H5、小程序、企业微信、React、Taro 等平台
10. 渐进式引入：从纯样式到完整组件，开发者可按需逐步深入

生态图

┌─────────────────────────────────────────────────────────┐
│                    WeUI 生态全景                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │   weui       │  │  weui-wxss   │  │  weui.js     │  │
│  │  (H5 样式)   │  │ (小程序样式) │  │  (H5 交互)   │  │
│  │  ~11k Stars  │  │  ~15.3k Stars│  │  ~3.2k Stars │  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  │
│         │                 │                  │          │
│         └────────┬────────┘                  │          │
│                  │                           │          │
│         ┌────────▼────────┐                  │          │
│         │ weui-miniprogram│◄─────────────────┘          │
│         │ (小程序组件库)  │                             │
│         │   v1.0.8       │                             │
│         └────────┬────────┘                             │
│                  │                                      │
│         ┌────────▼────────┐                             │
│         │  微信小程序平台  │                             │
│         │  (useExtendedLib│                             │
│         │   零体积引入)   │                             │
│         └─────────────────┘                             │
│                                                         │
│  ┌──────────────────────────────────────────────────┐   │
│  │              社区 / 第三方适配                     │   │
│  │  • React-WeUI    • Taro-WeUI                     │   │
│  │  • uni-app 适配  • WeUI for Work (企业微信)      │   │
│  └──────────────────────────────────────────────────┘   │
│                                                         │
│  ┌──────────────────────────────────────────────────┐   │
│  │              设计资源                              │   │
│  │  • weui.io 官方文档 & 组件预览                     │   │
│  │  • Figma 社区组件库（WeUI Kit）                    │   │
│  │  • 微信开放平台官方文档集成                        │   │
│  └──────────────────────────────────────────────────┘   │
│                                                         │
└─────────────────────────────────────────────────────────┘

适用场景

1. 微信小程序开发：追求与微信原生视觉一致的小程序项目，WeUI 是首选基础样式库，尤其适合工具类、服务类、政务类小程序

2. 微信公众号 H5 页面：在微信内置浏览器中运行的活动页、营销页、服务页，使用 WeUI 可确保页面与微信 UI 无缝融合

3. 企业微信应用开发：WeUI for Work 专为企业微信场景设计，适合 OA、审批、内部工具等企业应用

4. 微信生态 MVP / 快速原型：需要快速搭建与微信风格一致的 MVP 产品时，WeUI 的零配置特性能极大加速开发

5. 政务 / 公共服务小程序：政府、医疗、教育等公共服务类项目，使用 WeUI 天然具备"官方感"和信任感

6. 轻量级交互组件需求：仅需 Dialog、Toast、ActionSheet 等基础交互组件时，weui.js 的轻量方案远优于引入完整 UI 框架

7. 微信内嵌网页与小程序混合开发：需要 H5 页面与小程序保持视觉统一时，WeUI 同时覆盖两端，确保体验一致

开发与工程化

主题定制

WeUI 提供基于 CSS 变量的主题定制能力：

/* 自定义主题色 */
page {
  --weui-BRAND: #07C160;      /* 品牌色（微信绿） */
  --weui-LINK: #576B95;        /* 链接色 */
  --weui-FG-0: rgba(0,0,0,.9); /* 主文字色 */
  --weui-FG-1: rgba(0,0,0,.55);/* 次文字色 */
  --weui-BG-0: #EDEDED;        /* 背景色 */
}

构建工具集成

Webpack / Vite（H5）：

// 直接引入编译好的 CSS
import 'weui/dist/style/weui.min.css'
 
// 或按需引入 Less 源文件（需 Less 支持）
import 'weui/src/style/index.less'

小程序构建：

# NPM 安装后在微信开发者工具中构建
npm install weui-wxss --save
npm install weui-miniprogram --save
# → 工具 → 构建 npm

按需引入

小程序通过 useExtendedLib 实现免构建引入；H5 端可通过 CSS 选择器仅保留所需组件样式。

TypeScript 支持

weui.js 提供基础类型声明，weui-miniprogram 的自定义组件支持在 .json 中声明后直接在 .wxml 中使用，IDE 自动补全。

性能与安全

性能

安全

• MIT 协议：代码完全开源，可审计
• 零运行时依赖：不引入第三方 JS 库，攻击面极小
• 官方维护：腾讯/微信团队直接维护，安全更新及时
• 无数据收集：纯 UI 库，不涉及用户数据采集或网络请求
• XSS 防护：组件不含 v-html / dangerouslySetInnerHTML 等危险模式（原生 WXML 模板）

技术对比

选型建议：

• 做微信小程序且追求微信原生体验 → 选 WeUI
• 做功能丰富的电商/社交小程序，需要大量高级组件 → 选 Vant Weapp
• 做企业级应用，需要统一设计体系 → 选 TDesign Miniprogram
• 组合使用：WeUI 做基础样式 + Vant Weapp 做复杂组件，也是常见方案

最佳实践

1. 小程序优先使用 useExtendedLib

{
  "useExtendedLib": {
    "weui": true
  }
}

这种方式不占用小程序代码包空间，且自动跟随平台更新，是官方推荐的首选引入方式。

2. 利用 CSS 变量实现品牌适配

/* app.wxss 全局覆盖 */
page {
  --weui-BRAND: #1AAD19; /* 你的品牌色 */
}

避免直接修改 WeUI 源码样式，通过变量覆盖保持升级兼容性。

3. 样式与组件分离引入

• 使用 weui-wxss 提供基础样式类名（如 weui-btn、weui-cell）
• 使用 weui-miniprogram 提供需要交互逻辑的组件（如 Dialog、Tabs）
• 两者互补，避免功能重叠

4. 配合小程序原生能力

<!-- 使用 WeUI 样式 + 小程序原生组件 -->
<view class="weui-cells weui-cells_after-title">
  <navigator url="..." class="weui-cell weui-cell_access" hover-class="weui-cell_active">
    <view class="weui-cell__bd">列表项</view>
    <view class="weui-cell__ft"></view>
  </navigator>
</view>

5. DarkMode 适配

WeUI 内置 DarkMode 变量，确保在深色模式下自动适配：

/* 无需额外代码，WeUI 变量自动响应深色模式 */
.weui-cell {
  background: var(--weui-BG-2); /* 自动切换深浅背景 */
  color: var(--weui-FG-0);      /* 自动切换文字色 */
}

6. 组件二次封装

对于业务中重复使用的 WeUI 组合模式，建议封装为自定义组件：

<!-- components/business-card/business-card.wxml -->
<view class="weui-cell">
  <view class="weui-cell__hd">
    <image src="{{avatar}}" style="width:40px;height:40px;" />
  </view>
  <view class="weui-cell__bd">
    <text>{{name}}</text>
    <text class="weui-cell__desc">{{desc}}</text>
  </view>
</view>

技术局限与边界

局限

1. 组件数量有限：仅提供 20+ 基础组件，缺少 Calendar、Cascader、TreeSelect、Step 等复杂业务组件，无法满足中大型应用的全部需求

2. 主题定制灵活性不足：CSS 变量系统仅覆盖颜色和基础间距，不支持组件级别的深度定制（如圆角、阴影、动画时长等）

3. 更新频率较低：2025 年以来主版本迭代缓慢，weui-miniprogram GitHub Release 停留在 v1.0.8，新功能开发不活跃（但 useExtendedLib 方式会随微信客户端版本同步更新）

4. 仅限微信生态：WeUI 的设计目标是微信视觉一致性，在支付宝小程序、抖音小程序、App 等非微信平台上不具备视觉优势

5. 缺乏高级交互组件：没有内置的虚拟列表、无限滚动、手势交互、复杂表单引擎等高级组件

6. 文档体验一般：官方文档分散在 GitHub Wiki、微信开放平台、weui.io 多处，缺乏统一的交互式文档站

7. 社区生态薄弱：相比 Vant、TDesign 等活跃的社区，WeUI 的第三方插件、模板、主题资源较少

边界

• 不适合：需要大量复杂组件的中后台管理系统、跨平台（非微信）应用、高度定制化品牌风格的项目
• 适合：微信生态内的工具类/服务类/政务类小程序、公众号 H5 页面、追求微信原生感的轻量级应用
• 推荐组合：WeUI（基础样式）+ Vant Weapp / TDesign（复杂组件），兼顾原生感和开发效率

学习资源

官方资源

• WeUI 官网（weui.io） — 组件预览与样式参考
• WeUI 小程序组件库文档 — 扩展组件库完整文档
• 微信开放平台 - WeUI 组件库 — 官方使用指南
• Tencent/weui GitHub Wiki — 源码级文档与 Getting Started

教程与指南

• weui-miniprogram 完全指南 — 从零到实战的完整教程
• WeUI 使用教程（腾讯云开发者社区） — 详细图文教程
• 微信小程序 WeUI 组件库实战 — 阿里云开发者社区教程
• WeUI-WXSS 主题定制与高级功能 — 进阶主题定制

设计资源

• Figma - WeUI Kit — Figma 社区组件库

示例与模板

• weui-wxss dist/example — 官方示例小程序源码
• weui-miniprogram 示例 — 扩展组件库示例

2026 年现状

维护状态

截至 2026 年 7 月，WeUI 各仓库的维护状态如下：

关键趋势

1. 稳定优先，非积极迭代：WeUI 作为微信生态的基础设施，以稳定性为首要目标。核心组件已高度成熟，不需要频繁大版本更新。

2. useExtendedLib 成为主流引入方式：随着微信基础库对扩展库的持续优化，useExtendedLib 方式已成为小程序使用 WeUI 的标准做法，免去了 NPM 构建的复杂性。

3. 与 TDesign 形成互补定位：腾讯内部，WeUI 负责"微信原生感"的基础样式，TDesign 负责"企业级"的复杂组件生态，两者定位清晰、互不冲突。

4. AI 辅助开发的受益者：WeUI 的组件类名规范、BEM 命名、官方文档结构化程度高，非常适合作为 AI 代码生成的参考素材。

5. 微信生态不可替代：随着微信小程序的持续增长（日活超 5 亿），WeUI 作为"官方视觉标准"的地位依然稳固，在政务、医疗、教育等强调"正统感"的场景中具有不可替代的价值。

展望

WeUI 在 2026 年不太可能进行架构层面的大改版（如迁移到 CSS-in-JS 或 Web Components），其核心价值在于稳定、轻量、与微信原生一致。对于新项目，建议根据团队技术栈和组件需求，在 WeUI + Vant Weapp 或 WeUI + TDesign 的组合中选择，既保留微信原生感，又获得足够的组件丰富度。