weui-miniprogram：微信官方小程序 UI 组件库安装与使用指南

一、项目官方信息

weui-miniprogram 是一套基于样式库 weui-wxss 开发的小程序扩展组件库。README 中的定位是：与微信原生视觉体验一致的扩展组件库，由微信官方设计团队和小程序团队为微信小程序量身设计，让用户的使用感知更加统一。

换句话说，它把微信小程序原生界面里那些常见的控件——按钮、列表单元、对话框、轻提示、表单、图标、导航栏、动作面板等——封装成可直接在小程序里引用的自定义组件，开发者无需自己从头写样式，就能得到与微信官方一致的视觉与交互。

二、官方图片

上图为该仓库在 GitHub 上的社交预览图。组件的完整清单、每个组件的属性与示例，都在官方文档站（见跳转链接）中以在线 demo 形式呈现。

三、环境要求

• 已安装 Node.js 与 npm。
• 最新版微信开发者工具。
• 一个已有或新建的小程序项目。
• 基础库版本建议较新（以支持较新的组件特性）。

四、安装与接入步骤

1. 在小程序项目根目录初始化 npm

如果项目根目录还没有 package.json，先初始化：

npm init -y

2. 安装 weui-miniprogram

npm install weui-miniprogram

3. 在开发者工具中构建 npm

1. 打开微信开发者工具，进入项目。
2. 菜单：「详情 → 本地设置」，勾选「使用 npm 模块」。
3. 菜单：「工具 → 构建 npm」。等待构建完成，项目根目录会生成 miniprogram_npm/ 目录，里面包含 weui-miniprogram。

这一步是小程序使用 npm 包的关键：源码里的 node_modules 不会被直接打包，必须经过「构建 npm」生成 miniprogram_npm 后才能在 usingComponents 中引用。

4. 在页面 json 中注册组件

在需要使用组件的页面 .json（如 pages/index/index.json）的 usingComponents 中注册要用的 WeUI 组件：

{
  "usingComponents": {
    "mp-button": "weui-miniprogram/button/button",
    "mp-cell": "weui-miniprogram/cell/cell",
    "mp-dialog": "weui-miniprogram/dialog/dialog",
    "mp-toptips": "weui-miniprogram/toptips/toptips"
  }
}

组件路径规则是 weui-miniprogram/<组件名>/<组件名>。全部组件清单见官方文档站。

5. 在 WXML 中使用

<view class="page">
  <mp-button type="primary" bind:tap="onTap">主要按钮</mp-button>
  <mp-cell title="单行内容" value="说明"></mp-cell>
</view>

保存后编译，即可在模拟器中看到与微信原生一致的按钮、列表单元样式。

6. 切换 DarkMode

README 给出的暗色模式用法：在根节点（或组件外层节点）增加属性 data-weui-theme="dark"，即可把 WeUI 组件切换到深色表现：

<view data-weui-theme="dark">
  <mp-button type="primary">暗色下的按钮</mp-button>
</view>

五、使用方法

• 常用组件：按钮 mp-button、列表单元 mp-cell、图标 mp-icon、面板 mp-panel、对话框 mp-dialog、顶部轻提示 mp-toptips、动作面板 mp-action-sheet、半屏对话框 mp-half-screen-dialog、表单 mp-form、输入框 mp-input、导航栏 mp-navbar 等。
• 组件属性：每个组件都有丰富的属性（如按钮的 type、size、plain）和事件（bind:tap），具体可配置项以官方文档站为准。
• 全局注册：如果多个页面都用到，可在 app.json 的 usingComponents 中全局注册，避免每个页面重复写。
• 样式定制：WeUI 组件基于 weui-wxss 样式，可通过外层类名覆盖少量样式；但建议优先使用官方提供的属性，保持视觉一致。
• 参与组件库开发：README 给出的开发命令为 npm run init（初始化）、npm run dev（开发监听）、npm run build（构建组件库）。

六、常见问题 FAQ

1. usingComponents 里写了 weui-miniprogram/... 却报“未找到组件”？ 几乎都是没有执行「工具 → 构建 npm」，或没勾选「使用 npm 模块」。请确认 miniprogram_npm/weui-miniprogram 目录已生成。

2. npm install weui-miniprogram 成功了但工具里看不到？ 小程序不会直接读 node_modules。必须在开发者工具里点「构建 npm」，把包构建到 miniprogram_npm 后才能引用。

3. 组件名为什么是 mp-button 而不是 button？ WeUI 组件统一以 mp- 前缀命名并在 usingComponents 中注册别名，避免与小程序原生组件（如原生 button）重名冲突。别名可自取，但路径要指向 weui-miniprogram/...。

4. 怎么开启深色模式？ 按 README：在根节点或组件外层加 data-weui-theme="dark" 属性，组件即切换到暗色表现，无需额外配置主题文件。

5. 完整组件列表在哪查？ 官方文档站 https://wechat-miniprogram.github.io/weui/docs/ 提供了每个组件的属性说明与在线示例，是最权威的参考。

6. 想自己改组件库源码怎么跑起来？ 克隆仓库后依次执行 npm run init、npm run dev（开发监听），开发完成后 npm run build 构建组件库，这是 README 给出的开发流程。

七、跳转链接

• GitHub 仓库：https://github.com/wechat-miniprogram/weui-miniprogram
• 官方组件文档：https://wechat-miniprogram.github.io/weui/docs/
• npm 包：https://www.npmjs.com/package/weui-miniprogram
• 样式库 weui-wxss：https://github.com/Tencent/weui-wxss/