yymini-pop-html

一款轻量级、无额外依赖、开箱即用的抖音小程序底部富文本弹出框自定义组件，专注于富文本内容的展示，支持富文本内部链接跳转事件透传，适用于富文本公告、带格式说明、含链接的详情展示等底部弹出场景。

特性

• 专属适配：专为抖音小程序设计，无需额外适配，兼容性更优
• 富文本支持：原生支持富文本内容渲染，可展示带格式的文本、图片、链接等内容
• 轻量无依赖：零外部依赖，引入即可使用，不增加项目体积负担
• 核心交互可控：支持遮罩点击关闭、自定义弹窗高度、标题显示/隐藏
• 链接事件透传：富文本内部链接点击事件精准透传，便于业务层处理跳转逻辑
• 状态同步流畅：通过属性监听实现显示状态同步，避免异步延迟问题
• 防穿透设计：内置点击穿透阻止机制，避免内容区点击触发遮罩事件

安装

1. 执行 npm 安装

npm install yymini-pop-html --save
or
yarn add yymini-pop-html

2. 抖音小程序构建 npm 打开抖音小程序开发者工具 → 工具 → 构建 npm

快速使用

1. 配置组件

在需要使用弹窗的页面或组件的 json 文件中声明组件引用：

{
  "usingComponents": {
    "pop-html": "/miniprogram_npm/yymini-pop-html/pop-html"
  }
}

2. 页面中使用

在 ttml 中添加组件标签，绑定属性与事件：

<!-- 页面 ttml -->
<pop-html
  visible="{{isVisible}}"
  title="富文本公告"
  content='<div>这是一条带格式的公告：<br/>1. 活动时间：2025.4.1-2025.4.30<br/>2. 点击<a href="activity/detail">查看活动详情</a><br/>3. 最终解释权归平台所有</div>'
  height="{{80}}"
  bgSrc="/images/bg-notice.png"
  maskCloseable="{{false}}"
  bind:close="onClose"
  bind:linktap="onLinkTap"
>
</pop-html>

在 js 中控制弹窗显示与事件处理：

Page({
  data: {
    isVisible: false
  },
  // 打开弹窗
  openPopup() {
    this.setData({ isVisible: true });
  },
  // 弹窗关闭事件（遮罩/关闭按钮触发）
  onClose() {
    this.setData({ isVisible: false });
  },
  // 富文本内部链接点击事件
  onLinkTap(e) {
    console.log("富文本链接点击，透传参数：", e.detail);
    // 执行业务跳转逻辑（如跳转到活动详情页） 
  }
})

组件属性

| 属性名 | 类型 | 默认值 | 说明 | |----------------|---------|--------------|----------------------------------------------------------------------| | visible | Boolean | false | 【必填】控制弹窗的显示/隐藏 | | zindex | Number | 999 | 弹窗及遮罩层层级，默认999，可根据页面元素层级调整，避免被遮挡 | | content | String | '' | 【核心】富文本内容，支持标准HTML标签（如div、br、a、img等，需符合抖音小程序富文本渲染规范） | | height | Number | 85 | 弹窗高度，单位为百分比（%），默认占屏幕高度的85% | | title | String | null | 弹窗顶部标题，为null时不显示标题区域 | | bgSrc | String | "bgSrc.png" | 弹窗背景图片地址，默认值为"bgSrc.png"，需确保项目中存在该图片或自定义替换 | | maskCloseable | Boolean | false | 点击遮罩层是否关闭弹窗，默认不关闭，需手动点击关闭按钮关闭 |

组件事件

| 事件名 | 触发时机 | 事件参数 | 说明 | |----------------|--------------------------------------------|---------------------------|----------------------------------------------------------------------| | bind:close | 点击遮罩层或关闭按钮时触发 | 无 | 弹窗关闭事件，用于关闭弹窗并重置状态 | | bind:linktap | 点击富文本内部的链接（标签）时触发 | { ...event.detail } | 透传富文本链接点击的原生事件参数（含href等信息），便于业务层处理跳转 |

效果预览

效果预览地址

注意事项

1. 平台适配说明：组件专为抖音小程序
2. 无依赖特性：组件无需额外引入其他库或资源，安装后直接使用，降低项目依赖风险
3. 富文本兼容性：content属性支持的HTML标签需符合抖音小程序富文本渲染规范
4. 背景图配置：默认背景图地址为“bgSrc.png”，若项目中无该图片，需通过bgSrc属性自定义替换，否则可能显示空白背景
5. 尺寸单位说明：height属性值为百分比，无需手动添加“%”符号，组件内部自动拼接处理
6. 状态同步机制：组件通过observer监听visible属性变化，自动同步内部show状态，无需手动控制内部状态
7. 事件穿透防护：弹窗内容区点击不会穿透到遮罩层，已通过stopPropagation方法阻止事件冒泡
8. 层级调整建议：若弹窗被其他页面元素遮挡，可增大zindex属性值
9. 富文本图片规则：富文本中的图片支持本地图片和网络图片，使用网络图片时，需在抖音小程序后台配置对应的域名白名单
10. 链接事件绑定：若富文本中包含链接，需绑定bind:linktap事件才能处理跳转逻辑，否则点击链接无响应