mp-html 组件 API 详解与实战指南

原创于 2025-06-11 09:13:36 发布

· 379 阅读

9 ·

版权

mp-html 组件 API 详解与实战指南

mp-html mp-html是一个微信小程序HTML组件库，适合用于快速搭建微信小程序界面。特点：组件丰富、易于使用、支持自定义样式。项目地址: https://gitcode.com/gh_mirrors/mp/mp-html

前言

mp-html 是一个功能强大的富文本渲染组件，除了提供丰富的属性和事件外，还通过组件实例暴露了一系列实用的 API 方法。本文将全面解析这些 API 的使用方法和应用场景，帮助开发者更好地控制富文本内容的展示与交互。

获取组件实例

在使用 API 前，首先需要获取组件实例。不同平台获取方式略有差异：

uni-app 环境

<template>
  <view>
    <mp-html ref="article" />
  </view>
</template>
<script>
export default {
  onLoad() {
    const ctx = this.$refs.article
    // 现在可以使用 ctx 调用各种 API
  }
}
</script>

小程序平台

Page({
  onLoad() {
    // 微信/QQ/百度小程序
    const ctx = this.selectComponent('#article')
    
    // 头条小程序
    this.selectComponent('#article', ctx => {
      // 回调方式获取
    })
  }
})

核心 API 详解

1. in 方法 - 限定锚点跳转范围

功能：将锚点跳转限定在指定 scroll-view 容器内

参数说明：

page: 页面实例（通常传入 this）
selector: scroll-view 的选择器
scrollTop: 绑定的 scrollTop 变量名

使用场景：当富文本内容较长且需要局部滚动时，使用此方法可以确保锚点跳转只在指定区域内生效。

Page({
  onLoad() {
    ctx.in(this, '#scroll', 'top')
  }
})

注意事项：

确保 scroll-view 开启了纵向滚动
视频组件需要确认平台是否支持同层渲染

2. navigateTo 方法 - 精准锚点跳转

功能：跳转到指定锚点位置

使用前提：

需设置 use-anchor 属性为 true
建议在 ready 事件后调用确保准确性

参数说明：

id: 目标锚点 ID（可选，默认跳转开头）
offset: 跳转位置偏移量（可选）

ctx.navigateTo('section1', 20)
  .then(() => console.log('跳转成功'))
  .catch(err => console.error('跳转失败', err))

3. getText 方法 - 获取纯文本内容

功能：提取富文本中的纯文字内容

典型应用：

生成内容摘要
实现全文搜索功能
计算阅读时长

const plainText = ctx.getText()
console.log('文本长度:', plainText.length)

4. getRect 方法 - 获取内容区域信息

功能：获取富文本的尺寸和位置信息

特别说明：在启用懒加载时，ready 事件返回的尺寸可能不准确，此时应使用此方法获取实时数据。

ctx.getRect()
  .then(rect => {
    console.log('内容高度:', rect.height)
  })
  .catch(console.error)

5. setContent 方法 - 动态设置内容

功能：灵活设置或追加富文本内容

优势：

直接操作逻辑层，不经过视图层，性能更优
支持增量追加内容

参数说明：

content: 要设置的 HTML 字符串
append: 是否追加内容（默认替换）

// 追加内容
ctx.setContent('<p>新增内容</p>', true)

重要提示：避免在 load 或 ready 事件处理函数中调用，否则可能导致无限循环。

实用属性与媒体控制

imgList 属性 - 图片管理

功能：获取所有图片的数组，可用于：

实现自定义图片预览逻辑
替换为高清图链接
处理 base64 图片

// 替换首图为高清图
ctx.imgList[0] = ctx.imgList[0].replace('thumbnail', 'original')

// 获取首图作为分享封面
const shareCover = ctx.imgList[0]

pauseMedia 方法 - 媒体控制

功能：暂停所有正在播放的音视频

典型场景：

页面跳转时暂停播放
实现音视频互斥播放

Page({
  onHide() {
    ctx.pauseMedia()
  }
})

setPlaybackRate 方法 - 播放速率控制

功能：调整音视频播放速度

参数说明：

rate: 播放速率（通常支持 0.5-2.0）

// 设置1.5倍速播放
ctx.setPlaybackRate(1.5)

最佳实践建议

性能优化：
- 对于动态内容，优先使用 setContent 而非重新渲染组件
- 合理使用 append 参数实现增量更新
错误处理：
- 对 getRect 和 navigateTo 等返回 Promise 的 API 做好错误捕获
用户体验：
- 结合 pauseMedia 实现页面切换时的媒体管理
- 使用 imgList 优化图片预览体验
兼容性考虑：
- 不同小程序平台的 API 调用方式可能有差异
- 注意视频组件的平台支持情况

通过合理运用这些 API，开发者可以实现更加丰富和高效的富文本交互体验，满足各种复杂的业务场景需求。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考