Initial commit

2025-12-08 14:39:07 +08:00
commit 9d4f78656b
782 changed files with 66418 additions and 0 deletions
--- a/wechat-mini-program/components/mp-html/docs/basic/event.md
+++ b/wechat-mini-program/components/mp-html/docs/basic/event.md
@@ -0,0 +1,173 @@
+# 📫 事件 :id=event
+
+## 获取方式 :id=method
+- *uni-app*  
+  *@* + 事件名 或 *v-on:* + 事件名  
+  事件信息从 *event* 中获取  
+  ```vue
+  <template>
+    <view>
+      <mp-html @ready="ready" />
+    </view>
+  </template>
+  <script>
+    export default {
+      methods: {
+        ready (e) {
+          console.log(e)
+        }
+      }
+    }
+  </script>
+  ```
+
+- 支付宝小程序  
+  *on* + 事件名（首字母大写）  
+  事件信息从 *event* 中获取  
+  ```axml
+  <mp-html onReady="ready">
+  ```
+  ```javascript
+  Page({
+    ready (e) {
+      console.log(e)
+    }
+  })
+  ```
+
+- 其他小程序平台  
+  *bind* + 事件名  
+  事件信息从 *event.detail* 中获取  
+  ```wxml
+  <mp-html bindready="ready" />
+  ```
+  ```javascript
+  Page({
+    ready (e) {
+      console.log(e.detail)
+    }
+  })
+  ```
+
+## load
+触发时机：*dom* 树加载完毕时  
+返回值：无  
+用途：可以调用 [api](advanced/api) 函数  
+
+## ready
+触发时机：图片加载完毕时（不包含懒加载的图片）  
+
+?> 判断方式是 *350ms* 总高度无变化就认为加载完毕，部分情况下可能不准确；[2.4.0](changelog/changelog#v240) 版本起 [lazy-load](basic/prop#lazy-load) 属性为 *false* 时根据图片的 *load* 事件判断，可以基本准确触发
+
+返回值：富文本区域的 *boundingClientRect* 结构体，包含大小位置信息  
+用途：此时进行 [锚点跳转](advanced/api#navigateTo) 可以基本保证跳转位置正确  
+
+?> 如果设置了 [懒加载](basic/prop#lazy-load)，此时返回的大小不一定是最终大小，如果需要实时的大小，可以调用 [getRect](advanced/api#getRect) 方法  
+
+## error
+触发时机：发生渲染错误时  
+返回值：一个 *object*，其中 *source* 为错误来源（包括 *img*、*video*、*audio*），*attrs* 为该标签的属性列表（包含 *src* 等信息），*errMsg* 是错误信息  
+用途：收集错误信息，减少使用出错率高的链接  
+
+## imgtap
+触发时机：图片被点击时  
+返回值：该 *img* 标签的属性列表  
+用途：  
+默认情况下图片被点击时将自动预览（具体处理可见 [图片效果](overview/feature#img)），如果不希望如此，可将 [preview-img](basic/prop#preview-img) 属性设置为 *false* 并在这里自定义处理  
+如果需要用到富文本中所有图片的数组，可以通过 [imgList](advanced/api#imgList) 的 *api* 获取  
+示例：  
+```javascript
+Page({
+  imgtap (e) {
+    // 对做了某种标记的图片进行预览
+    if (e.detail['data-flag']) {
+      wx.previewImage({
+        urls: [e.detail.src] // 仅预览单张图片
+      })
+    }
+  }
+})
+```
+
+## linktap
+触发时机：链接被点击时  
+返回值：该 *a* 标签的属性列表  
+
+?> [2.0.5](changelog/changelog#v205) 版本起增加返回该标签内部文本 *innerText*
+
+用途：  
+默认情况下链接被点击时，对于外部链接，将被拷贝到剪贴板，如果不希望如此，可以将 [copy-link](basic/prop#copy-link) 属性的值设置为 *false* 后在这里自定义处理，可参考以下方案：  
+
+1. 跳转 *web-view*  
+   跳转到一个新的页面，该页面放置一个 [web-view](https://developers.weixin.qq.com/miniprogram/dev/component/web-view.html) 用于显示外部网页（需要注意 *web-view* 的使用限制）  
+2. 跳转其他小程序  
+   对于其他小程序的链接（可通过自行设置的 *data-* 属性判断），通过 [navigateToMiniProgram](https://developers.weixin.qq.com/miniprogram/dev/api/open-api/miniprogram-navigate/wx.navigateToMiniProgram.html) 接口跳转（需要注意跳转限制）  
+3. 下载文档  
+   对于文档类的链接（可通过后缀名或自行设置的 *data-* 属性判断），可以通过 [downloadFile](https://developers.weixin.qq.com/miniprogram/dev/api/network/download/wx.downloadFile.html) 接口下载文件后通过 [openDocument](https://developers.weixin.qq.com/miniprogram/dev/api/file/wx.openDocument.html) 接口打开文档（需要注意下载域名限制）  
+4. 下载压缩包  
+   对于压缩包类的链接（可通过后缀名或自行设置的 *data-* 属性判断），可以通过 [downloadFile](https://developers.weixin.qq.com/miniprogram/dev/api/network/download/wx.downloadFile.html) 接口下载文件后通过 [FileSystemManager.unzip](https://developers.weixin.qq.com/miniprogram/dev/api/file/FileSystemManager.unzip.html) 接口解压，然后进行打开文档等操作（需要注意下载域名限制）  
+   对于大文件（可通过 *data-* 属性标注），还可以在下载前进行询问，下载过程中通过 [DownloadTask](https://developers.weixin.qq.com/miniprogram/dev/api/network/download/DownloadTask.html) 提示下载进度等  
+
+示例：  
+```javascript
+Page({
+  linktap (e) {
+    if (e.detail.href.includes('.doc')) {
+      // 下载 doc 文件
+      wx.downloadFile({
+        url: e.detail.href,
+        success (res) {
+          wx.hideLoading()
+          wx.openDocument({
+            filePath: res.tempFilePath
+          })
+        },
+        fail (err) {
+          wx.hideLoading()
+          wx.showModal({
+            title: '失败',
+            content: err.errMsg,
+            showCancel: false
+          })
+        }
+      })
+    } else if (e.detail.href.includes('xxx.com')) {
+      // 跳转到 webview
+      wx.navigateTo({
+        url: 'pages/webview/webview?url=' + e.detail.href,
+      })
+    } else if (e.detail['data-appid']) {
+      // 跳转其他小程序
+      wx.navigateToMiniProgram({
+        appId: e.detail['data-appid']
+      })
+    }
+  }
+})
+```
+
+## play
+
+?> [2.3.0](changelog/changelog#v230) 版本起支持  
+
+触发时机：音视频播放时  
+返回值：无  
+
+?> [2.5.0](changelog/changelog#v250) 版本起返回值变更为一个 *object*，其中 *source* 为播放来源（包括 *video*、*audio*），*attrs* 为该标签的属性列表（包含 *src* 等信息），可以统计播放量等信息
+
+用途：和 [pauseMedia](advanced/api#pauseMedia) 的 `api` 配合可以实现与页面中其他音视频进行互斥播放  
+示例：  
+```javascript
+Page({
+  // 页面中的音视频播放事件
+  pagePlay() {
+    // ctx 为组件实例
+    ctx.pauseMedia() // 暂停组件内的音视频播放
+  },
+  // 组件的 play 事件
+  componentPlay() {
+    // media 为页面中的音视频实例
+    media.pause() // 暂停页面中的音视频播放
+  }
+})
+```
--- a/wechat-mini-program/components/mp-html/docs/basic/prop.md
+++ b/wechat-mini-program/components/mp-html/docs/basic/prop.md
@@ -0,0 +1,141 @@
+# 🔨 属性 :id=prop
+
+!> 需要将某个属性设置为 *false* 时，应写作 *attr="{{false}}"*  
+
+## container-style
+
+?> [2.1.0](changelog/changelog#v210) 版本起支持  
+
+功能：设置容器的样式  
+类型：*String*  
+示例：  
+```css
+padding: 5px; /* 设置内边距 */
+font-size: 18px; /* 设置默认的字体大小 */
+overflow: hidden; /* 禁用横向滚动 */
+display: inline; /* 行内显示 */
+white-space: pre-wrap; /* 保留空格和换行符 */
+white-space: pre-line; /* 保留换行符 */
+```
+
+## content
+功能：用于渲染的 *html* 字符串  
+类型：*String*  
+
+## copy-link
+功能：是否允许外部链接被点击时自动复制  
+类型：*Boolean*  
+默认值：*true*  
+
+?> 对于 *uni-app* 的 *h5* 和 *app* 平台，外链是能够直接跳转的，这种情况下如果该属性为 *true* 则直接跳转外链（而不是复制链接），为 *false* 则不跳转  
+
+## domain
+功能：主域名（用于链接拼接）  
+类型：*String*  
+示例：  
+```html
+<!-- 假设 domain 属性被设置为 https://example.com
+     以下链接均会被拼接为 https://example.com/path -->
+<img src="//example.com/path" />
+<img src="/path" />
+<div style="background-image:url('path')"></div>
+```
+
+?> 通过 *base* 标签也可以设置主域名，但优先级低于此属性  
+
+!> 该属性必须填写 协议名://域名 的完整链接  
+暂不支持拼接含有 *../* 的相对路径链接  
+*a* 标签的 *href* 属性可能需要跳转到小程序内路径，因此不进行 *domain* 拼接  
+设置该属性后将无法使用本地图片  
+
+## error-img
+功能：图片出错时的占位图链接  
+类型：*String*  
+
+!> 该属性不会进行拼接 [domain](#domain)，需传入完整路径（可以使用本地路径）  
+
+## lazy-load
+功能：是否开启图片懒加载  
+类型：*Boolean*  
+默认值：*false*  
+
+?> 不同平台懒加载的时机不同，具体参考各平台 *image* 组件懒加载的时机  
+
+## loading-img
+功能：图片加载过程中的占位图链接  
+类型：*String*  
+
+!> 该属性不会进行拼接 [domain](#domain)，需传入完整路径（可以使用本地路径）  
+
+## pause-video
+功能：是否在播放一个视频时自动暂停其他视频  
+类型：*Boolean*  
+默认值：*true*  
+
+?> 如果需要多个视频同时播放的，请将此属性设置为 *false*  
+
+## preview-img
+功能：是否允许图片被点击时自动预览  
+类型：*Boolean*  
+默认值：*true*  
+
+?> 自动预览允许左右滑动查看所有图片，如果不希望如此可以禁用自动预览并在 [imgtap](basic/event#imgtap) 事件中自行处理  
+
+!> 默认情况下 *base64* 图片无法点击预览，[2.5.0](changelog/changelog#v250) 版本起支持将本属性设置为 *"all"* 开启 *base64* 图片的预览，但需要注意各平台 *previewImage* 的 *api* 对 *base64* 图片支持度不高，需充分测试后使用，如果无法预览，可参考 [imgList](advanced/api#imgList) 中的方法进行转存
+
+## scroll-table
+功能：是否给每个表格添加一个滚动层使其能单独横向滚动  
+类型：*Boolean*  
+默认值：*false*  
+
+!> 如果表格设置了 *inline* 布局，该属性将不会生效以免破坏行内布局  
+
+## selectable
+功能：是否开启文本长按复制  
+类型：*Boolean* / *String*  
+默认值：*false*  
+
+!> 将本属性的值设置为 *true* 在微信 *iOS* 端可能失效，[2.0.5](changelog/changelog#v205) 版本起支持将本属性设置为 "*force*" 来支持，但会带来以下影响：  
+1、所有文本块会显示为 *inline-block*（通过 [text](https://developers.weixin.qq.com/miniprogram/dev/component/text.html) 标签的 *user-select* 属性实现），需要自行适配  
+2、文字下划线、删除线等效果将失效（[详细](https://github.com/jin-yufeng/mp-html/issues/382)）  
+3、所有文本块都无法被 *rich-text* 包含，一定程度上增加标签数，减慢渲染速度  
+从 [2.3.1](changelog/changelog#v231) 版本起对此问题进行优化（通过 [rich-text](https://developers.weixin.qq.com/miniprogram/dev/component/rich-text.html) 标签的 *user-select* 属性实现，基础库 *2.24.0* 及以上生效），第 *3* 个问题已解决，第 *1*、*2* 个问题部分情况下还会存在
+
+## set-title
+功能：是否将 *title* 标签的内容设置到页面标题  
+类型：*Boolean*  
+默认值：*true*  
+
+## show-img-menu
+
+?> [2.3.0](changelog/changelog#v230) 版本起支持控制预览时是否长按显示菜单（仅微信、百度小程序有效）
+
+功能：是否允许图片被长按时显示菜单  
+类型：*Boolean*  
+默认值：*true*  
+
+!> 该属性目前仅微信、百度和 *uni-app* 的 *app* 平台有效  
+
+## tag-style
+功能：设置标签的默认样式  
+类型：*Object*  
+示例：  
+```javascript
+// 格式为 标签名: 样式
+{
+  a: 'color:red' // a 标签默认为红色
+}
+```
+
+?> 该属性非响应式，需要在设置 [content](#content) 属性前设置才能生效，动态修改不能实时生效
+
+!> 该属性的原理是解析到各标签的内联 *style* 属性中去，如果对特别常用的标签设置默认样式，将大大加大解析结果大小，减慢渲染速度，这种情况下建议通过 [外部样式](overview/quickstart#setting) 引入  
+
+## use-anchor
+功能：是否使用锚点链接  
+类型：*Boolean* / *Number*  
+默认值：*false*  
+
+?> 传入一个数字时表示跳转锚点的偏移量（单位 *px*）  
+
+?> 开启该属性会将所有设置了 *id* 属性的标签都暴露出来，一定程度上减慢渲染速度，非必要不要开启