mp-html

mp-html — 小程序富文本组件#

资源概述#

mp-html 是小程序生态中最流行的富文本解析与渲染组件，由 jin-yufeng 个人开发者维护。它解决了微信原生 rich-text 组件功能有限、不支持事件交互、不支持视频播放等痛点。

核心能力：

全标签支持：支持 table、video、audio、svg 等复杂标签
图片智能处理：自动预览、懒加载、占位图、错误处理
事件交互：链接点击、图片点击、内容加载完成等事件回调
锚点跳转：支持 HTML 内部锚点导航
内容编辑：编辑模式支持内容的增删改
关键词搜索：高亮搜索内容
代码高亮：配合 prismjs 实现代码语法高亮
LaTeX 公式：支持 LaTeX 数学公式渲染
轻量：≈25KB（9KB gzipped），不显著增加包体积
跨端：微信/支付宝/百度/抖音/QQ 小程序 + uni-app + H5

适用场景：

文章详情页（CMS 内容渲染）
商品描述（电商商品详情）
用户协议/帮助文档
邮件/消息预览
富文本编辑器（配合编辑模式）

设计规范#

支持平台#

平台	支持	说明
微信小程序	✅	原生支持，npm 安装
支付宝小程序	✅	源码方式引入
百度小程序	✅	源码方式引入
抖音小程序	✅	源码方式引入
QQ 小程序	✅	源码方式引入
uni-app	✅	插件市场或源码引入
H5	✅	uni-app H5 端

包体积分析#

项目	大小
核心代码	≈25KB
Gzipped	≈9KB
插件（按需引入）	各 2-5KB

性能优化#

虚拟列表：长文档自动分页渲染，避免一次性渲染过多节点
懒加载：图片懒加载（lazy-load 属性），可视区域内才加载
资源预加载：支持 preload-img 属性预加载图片
事件委托：事件系统采用委托模式，减少事件监听器数量

审核规范#

内容安全#

mp-html 内置 XSS 过滤机制，默认过滤 script、style、iframe 等危险标签
可通过 tag-style 和 domain 属性进一步控制渲染内容
建议：对于用户生成内容（UGC），必须配合服务端内容安全检测（微信 msgSecCheck）使用

注意事项#

富文本内容中的外部图片需要配置域名白名单（小程序后台 request 域名）
video 标签需要配合视频域名白名单
表格（table）在小程序中的渲染性能较差，建议控制行数

开发指南#

快速上手#

1. 安装

code

npm install mp-html

2. 页面配置（json）

code

{
  "usingComponents": {
    "mp-html": "mp-html"
  }
}

3. 基本使用（wxml）

code

<mp-html content="{{html}}" />

code

Page({
  data: {
    html: '<div><h1>标题</h1><p>这是一段<strong>富文本</strong>内容</p><img src="https://example.com/image.jpg"></div>'
  }
});

4. 高级用法

code

<!-- 图片预览 + 懒加载 + 长按复制 -->
<mp-html
  content="{{html}}"
  selectable="{{true}}"
  preview-img="{{true}}"
  lazy-load="{{true}}"
  domain="https://example.com"
  tag-style="{{{
    table: 'border: 1px solid #ccc; width: 100%;',
    th: 'background: #f5f5f5;'
  }}}"
  bind:link="onLink"
  bind:imgtap="onImgTap"
  bind:load="onLoad"
/>

插件系统#

mp-html 提供丰富的插件机制：

插件	说明	安装
keyword-search	关键词搜索高亮	npm install mp-html/plugins/keyword-search
content-edit	内容编辑模式	内置
latex	LaTeX 数学公式	npm install mp-html/plugins/latex
prism	代码语法高亮	npm install mp-html/plugins/prism

常见陷阱#

HTML 实体编码：mp-html 支持大部分 HTML 实体，但建议使用标准 UTF-8 编码
base64 图片：大量 base64 图片会导致渲染卡顿，建议使用 URL 引用
长文档性能：超过 5 万字符的文档建议开启分页渲染或截断
嵌套 table：深层嵌套的 table 可能渲染异常，建议扁平化处理
uni-app 条件编译：不同平台的 WXML 编译有差异，注意条件编译指令

生态资源#

与其他方案对比#

方案	stars	优势	劣势
mp-html	3732⭐	功能全面、跨端、插件丰富	维护频率一般
wxParse	7727⭐	老牌方案、知名度高	已停更（2020），不推荐新项目使用
rich-text（原生）	—	官方组件、零依赖	功能极其有限，不支持事件
owxome/wx-parser	454⭐	轻量	功能少，更新慢

版本更新#

v2.5.2（2025-12-14，latest）#

修复表格渲染相关问题
优化图片懒加载性能
TypeScript 类型定义增强

v2.5.0（2025-06）#

新增虚拟列表长文档渲染
锚点跳转功能增强
修复多个平台兼容性问题

v2.4.x（2024）#

LaTeX 插件支持
代码高亮插件（prism）集成
编辑模式功能完善

历史版本#

v1.x：基础功能阶段，支持基本 HTML 渲染
v2.0+：全面重写，插件系统，跨端支持

详细文档

mp-html — 小程序富文本组件#

资源概述#

设计规范#

支持平台#

包体积分析#

性能优化#

审核规范#

内容安全#

注意事项#

开发指南#

快速上手#

插件系统#

常见陷阱#

生态资源#

与其他方案对比#

推荐搭配#

版本更新#

v2.5.2（2025-12-14，latest）#

v2.5.0（2025-06）#

v2.4.x（2024）#

历史版本#