21 KiB
📌 插件 :id=plugin
可以在这里选择需要的插件以实现更加丰富的功能
使用插件 :id=use
!> 直接将插件文件夹拷贝到组件包中无法生效，请通过以下方式生成包含扩展的组件包
小程序方式
?> 该方式适合不熟悉 npm 的用户
npm 方式
- 获取完整的组件包
通过 npm 或 git 等方式获取 包含完整项目 的组件包（注意从 uni-app 的插件市场中导入的包中仅包含构建后的组件，不包含 构建工具和插件） - 选择需要的插件
参考下方插件使用说明，确定要使用的插件，将其名称填入 tools/config.js 中的 plugins 中
如果想仅在部分平台使用该插件，可以在该插件目录下的 build.js 的 platform 字段中填入需要的平台名称 - 生成组件包
设置完成后，可通过项目提供的命令行工具生成新的组件包，具体见 生成组件包 - 按照源码或 npm 方式引入构建后的组件包进行使用即可，详见 引入方式
audio
功能：音乐播放器
大小：≈4KB
支持平台：
| 微信小程序 | QQ 小程序 | 百度小程序 | 支付宝小程序 | 头条小程序 | uni-app |
|---|---|---|---|---|---|
| √ | √ | √ | √ | √ | √(nvue 不支持) |
!> 百度小程序原生包在此 问题 未解决前无法使用
说明：
在大多数小程序平台，audio 标签已被废弃或无法使用，本插件可以代替 audio 标签播放音乐，并实现以下优化：
- pause-video 属性也可以应用于音频，即播放一个音视频时可以自动暂停其他正在播放的音视频
- 增加了一个可以拖动的进度条
- 组件大小可以根据页面宽度自动调整
- 支持 autoplay 属性
- 播放被后台打断时，页面显示后自动继续播放
基础库要求：
支付宝 1.23.4+ ，其余平台满足 最低要求 即可
第 5 条仅微信 2.2.3+ 、QQ、百度支持
?> 如果希望页面上使用本组件，组件的路径为 path/to/mp-html/audio/audio
属性和事件基本同 audio 组件，组件实例上提供了 setSrc、play、seek、pause、stop 方法可供控制播放状态
editable
功能：富文本编辑
下表列出了本插件与原生 editor 组件的功能差异，可按需选用
| 组件 | 优点 | 缺点 |
|---|---|---|
| 原生 editor | 底层通过 contenteditable 实现，编辑流畅 | 支持标签少（不支持音视频、表格以及 section 等常用标签）、部分小程序平台不支持或低版本不兼容 |
| 本插件 | 支持标签全面、支持平台全面 | 编辑灵活性不够强 |
大小：≈17.5KB
支持平台：
| 微信小程序 | QQ 小程序 | 百度小程序 | 支付宝小程序 | 头条小程序 | uni-app |
|---|---|---|---|---|---|
| √ | √ | √ | √ | √ | √(nvue 不支持) |
说明：
引入本插件后，会给组件添加以下属性：
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| editable | Boolean | false | 是否开启内容编辑 |
| placeholder | String | 请输入 | 输入框为空时占位符（2.1.0+） |
添加以下事件：
| 事件名 | 触发时机 | 用途 |
|---|---|---|
| remove（2.2.0+） | 删除图片/视频/音频标签时 | 删除已上传的线上文件 |
支持以下操作：
| 类型 | 操作 |
|---|---|
| 文本 | 修改 |
| 图片 | 更换链接、调整宽度、设置成超链接（2.0.4+）、设置预览图链接、禁用预览、删除 |
| 链接 | 更换链接、删除 |
| 音视频 | 设置封面、设置循环播放、设置自动播放（2.2.0+）、删除 |
| 普通标签 | 设置字体大小、颜色（2.4.2+）、斜体、粗体、下划线（2.0.4+）、居中、缩进、删除 |
?> 2.2.1 版本起所有标签支持上下移动操作，但仅限同级标签间移动，即在有同级标签且非第一个（或最后一个）时可以上移（或下移）
?> 在支付宝小程序中使用时需要在页面样式中添加 page { position: relative; } 避免 tooltip 错位
?> 菜单项可以通过编辑 plugins/editable/config.js 进行修改，仅可以删减或调整顺序，添加或更名无效（颜色设置除外）
组件实例 上提供了以下方法（editable 属性为 true 时才可以调用）：
| 名称 | 功能 |
|---|---|
| undo | 撤销一个操作 |
| redo | 重做一个操作 |
| insertHtml | 在光标处插入指定 html 内容（2.1.0+） |
| insertImg | 在光标处插入一张图片 |
| insertTable(rows, cols) | 在光标处插入一个 rows 行 cols 列的表格（2.1.3+） |
| insertVideo | 在光标处插入一个视频 |
| insertAudio | 在光标处插入一个音频 |
| insertLink | 在光标处插入一个链接 |
| insertText | 在光标处插入一段文本 |
| clear | 清空内容 |
| getContent | 获取编辑后的 html 内容 |
?> 考虑到不同场景下希望获取链接的方法不同，需要在初始时给组件设置一个 getSrc 方法（否则插入图片、音视频、链接或修改链接等操作无法使用），每次组件内需要链接时会调用此方法，开发者可在此方法中自行决定如何获取链接，返回 线上地址 即可（具体用法见下方示例）
2.2.0 版本起设置了 domain 属性时，返回的地址可以缺省主域名
编辑完成后，通过 getContent 方法获取编辑后的 html，最后将 editable 属性设置为 false 即可正常渲染
!> 点击保存按钮时，部分平台 tap 事件早于 blur 事件触发，直接获取内容可能导致无法获取当前编辑的文本内容，因此建议设置一个小的延时后获取（可参考下方示例，详细）
示例：
Page({
onLoad () {
// ctx 为组件实例，获取方法见上
/**
* @description 设置获取链接的方法
* @param {String} type 链接的类型（img/video/audio/link）
* @param {String} value 修改链接时，这里会传入旧值
* @returns {Promise} 返回线上地址（2.2.0 版本起设置了 domain 属性时，可以缺省主域名）
* type 为 audio/video 时，可以返回一个源地址数组
* 2.1.3 版本起 type 为 audio 时，可以返回一个 object，包含 src、name、author、poster 等字段
* 2.2.0 版本起 type 为 img 时，可以返回一个源地址数组，表示插入多张图片（修改链接时仅限一张）
*/
this.ctx.getSrc = (type, value) => {
return new Promise((resolve, reject) => {
// 以图片为例
if (type == 'img') {
wx.chooseImage({
count: value === undefined ? 9 : 1, // 2.2.0 版本起插入图片时支持多张（修改图片链接时仅限一张）
success: res => {
wx.showLoading({
title: '上传中'
});
(async ()=>{
const arr = []
for (let item of res.tempFilePaths) {
// 依次上传
const src = await upload(item)
arr.push(src)
}
return arr
})().then(res => {
wx.hideLoading()
resolve(res)
})
},
fail: reject
})
}
})
}
},
finishEdit () {
setTimeout(() => {
var html = ctx.getContent() // 获取编辑好的 html
// 上传 html
wx.request({
url: 'xxx',
data: {
html
},
success: () => {
this.setData({
editable: false // 结束编辑
})
}
})
}, 50)
}
})
示例项目 :id=editable_demo
微信小程序点击 代码片段 即可在微信开发者工具中导入；uni-app 下载 示例项目 在 HBuilder X 中打开即可体验；注意示例项目中不一定包含最新版本，仅供参考使用方法
?> 也可以参考示例小程序 源代码
注意事项：
不要在 editable 属性被设置为 true 前通过 setContent 方法（用 content 属性）设置内容，否则在切换为 true 后会变成空白
emoji
功能：解析 emoji
大小：≈3KB
支持平台：
| 微信小程序 | QQ 小程序 | 百度小程序 | 支付宝小程序 | 头条小程序 | uni-app |
|---|---|---|---|---|---|
| √ | √ | √ | √ | √ | √ |
说明：
将形如 [笑脸] 的文本替换为 emoji 字符 😄
匹配模式可以通过修改 reg 变量实现
默认配置了 177 个常用的 emoji 小表情，可以自行按照需要修改 data 变量
?> 与 editable 插件共用时，导出编辑好的 html 内容，会将 emoji 字符编码为文本形式，便于存储
highlight
功能：代码块高亮显示
大小：≈16KB
支持平台：
| 微信小程序 | QQ 小程序 | 百度小程序 | 支付宝小程序 | 头条小程序 | uni-app |
|---|---|---|---|---|---|
| √ | √ | √ | √ | √ | √ |
说明：
编辑 plugins/highlight/config.js ，可以选择是否需要以下功能：
- copyByLongPress 是否需要长按代码块时显示复制代码内容菜单（uni-app nvue 暂不支持）
- showLanguageName 是否在代码块右上角显示语言的名称
- showLineNumber 是否在左侧显示行号
!> 修改该配置后需要重新 生成组件包，在构建后的组件包中修改配置无法生效
引入本插件后，html 中符合以下格式的 pre 将被高亮处理：
<!-- pre 中内含一个 code，并在 pre 或 code 的 class 中设置 language- -->
<pre><code class="language-css">p { color: red }</code></pre>
?> 与 editable 插件共用时，编辑状态下，不会进行高亮，可以直接修改代码文本
?> 本插件的高亮功能依赖于 prismjs，默认配置中仅支持 html、css、c-like、javascript 语言和 Tomorrow Night 主题，如果需要更多语言或更换主题请前往 官网 下载对应的 prism.min.js 和 prism.css 并替换 plugins/highlight/ 目录下的文件（prismjs 的插件大多涉及 dom 操作，基本不可用，请勿选择）
markdown
功能：渲染 markdown
大小：≈37KB
支持平台：
| 微信小程序 | QQ 小程序 | 百度小程序 | 支付宝小程序 | 头条小程序 | uni-app |
|---|---|---|---|---|---|
| √ | √ | √ | √ | √ | √ |
说明：
引入本插件后，会给组件添加一个 markdown 属性，将该属性设置为 true 后，即可通过 content 属性或 setContent 方法设置 markdown 内容即可
?> 若开启 use-anchor 属性，所有标题 # xxx 都会被设置为锚点，通过链接 [xxx](#xxx) 可以直接跳转
?> 本插件通过 marked 解析 markdown 文本，部分 css 摘选自 github-markdown-css
?> 本插件可以和 highlight 插件共用，实现 markdown 中代码块的高亮效果
search
功能：关键词搜索
大小：≈1.5KB
支持平台：
| 微信小程序 | QQ 小程序 | 百度小程序 | 支付宝小程序 | 头条小程序 | uni-app |
|---|---|---|---|---|---|
| √ | √ | √ | √ | √ | √(nvue 不支持) |
说明：
引入后会在 组件实例 上挂载一个 search 方法，用于关键词搜索
输入值
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| key | String 或 RegExp | - | 要搜索的关键词，支持字符串和正则 |
| anchor | Boolean | false | 是否将搜索结果设置为锚点 |
| style | String | background-color:yellow | 标记搜索结果的样式 |
返回值：Promise
| 属性 | 类型 | 说明 |
|---|---|---|
| num | Number | 搜索结果数量 |
| highlight | Function(i, style='background-color:#FF9632') | 高亮第 i（1 ~ num）个结果，将其样式设置为 style |
| jump | Function(i, offset) | 跳转到第 i（1 ~ num）个结果，偏移量为 offset，anchor 为 true 才可用 |
示例：
function search (key) {
// ctx 为组件实例
ctx.search(key, true).then(res => {
res.highlight(1)
res.jump(1, -50) // 高亮第 1 个结果并跳转到该位置，偏移量 -50
})
}
?> 具体用法可以参考示例小程序 源代码
附加说明：
- 不传入 key（或为空）时即可取消搜索，取消所有的高亮，还原到原来的效果
- 进行新的搜索时旧的搜索结果将被还原，旧的结果中的 highlight 等方法不再可用
- 调用 highlight 方法高亮一个结果时，之前被高亮的结果会被还原，即始终只有一个结果被高亮
- key 传入字符串时大小写敏感，如果要忽略大小写可以用正则的 i（字符串搜索效率高于正则）
- 设置 anchor 为 true 会一定程度上降低效率，非必要不要开启
- 暂不支持跨标签搜索，即只有一个文本节点内包含整个关键词才能被搜索到
style
功能：解析和匹配 style 标签中的样式
?> 这里的 style 标签指的是传入 content 属性中的 html 里包含的 style 标签，且 style 标签要放在其他标签前面才能生效
大小：≈3.5KB
支持平台：
| 微信小程序 | QQ 小程序 | 百度小程序 | 支付宝小程序 | 头条小程序 | uni-app |
|---|---|---|---|---|---|
| √ | √ | √ | √ | √ | √ (nvue 直接支持) |
说明：
支持以下选择器：
| 名称 | 示例 |
|---|---|
| 标签名选择器 | p {} |
| class 选择器 | .class {} |
| id 选择器 | #id {} |
| 多选择器交集 | p.class {} |
| 多选择器并集 | p, .class {} |
| 后代选择器 | .class1 .class2 {} |
| 子选择器 | .class1 > .class2 {} |
| 伪类 | .class::before {} |
伪类仅支持 before 和 after，支持 attr 方法
不支持的选择器（属性选择器等）将被忽略
!> 由于小程序中无法动态写入 css，本插件的实现原理是通过解析，将匹配的样式添加到各标签的行内 style 中去，请慎用宽泛的选择器，以免大大增加解析结果大小，减慢渲染速度
txv-video
功能：使用腾讯视频
大小：≈1KB
支持平台：
| 微信小程序 | QQ 小程序 | 百度小程序 | 支付宝小程序 | 头条小程序 | uni-app |
|---|---|---|---|---|---|
| √ | √ | √ (h5 和 app 直接支持) |
说明：
引入本插件后，html 中符合下方格式的 iframe 标签（src 中含有 vid）将被转为通过腾讯视频播放：
<iframe src="https://v.qq.com/txp/iframe/player.html?vid=xxxxxx" allowFullScreen="true"></iframe>
同时，其可以被 pause-video 属性控制
!> 本插件仅用于将官方 腾讯视频插件 应用于本组件，使用前请确认已经成功申请使用该插件并按要求在小程序 app.json 中配置完成（uni-app 中的配置方法可以参考 #103），否则可能报错 This application has not registered any plugins yet 且无法生效
?> 腾讯视频插件 v2 默认自动播放，v1 不会，可按需选择
img-cache
功能：图片本地缓存
大小：≈4KB
作者：@PentaTea
支持平台：
| 微信小程序 | QQ 小程序 | 百度小程序 | 支付宝小程序 | 头条小程序 | uni-app |
|---|---|---|---|---|---|
| √(仅支持 app 的 vue 页面) |
说明：
引入本插件后，会给组件添加一个 img-cache 属性，将该属性设置为 true 后，将自动下载引用的图片并将 src 属性更换为本地地址
同时在 组件实例 上挂载了 imgCache 对象，扩充缓存控制能力
imgCache 对象属性和方法：
| 属性 | 功能 |
|---|---|
| list | 当前缓存的 url 列表 |
| get(url) | 传入 url 获得本地地址 |
| delete(url) | 传入 url 删除缓存记录 |
| add(url) | 传入 url 并下载目标为缓存 |
| clear() | 清空所有缓存 |
!> 请尽量确保 src 中含有文件后缀名，不以后缀结尾也没关系，插件会从路径中推测合理的图片后缀，如果完全不包含后缀信息可能会无法保存到相册
latex
功能：渲染 latex 公式
大小：≈300KB
作者：@Zeng-J
支持平台：
| 微信小程序 | QQ 小程序 | 百度小程序 | 支付宝小程序 | 头条小程序 | uni-app |
|---|---|---|---|---|---|
| √ | √ | √ | √ | √ | √ |
说明：
引入本插件后，会将 $xxx$ 的文本内容按照 latex 规则进行解析和渲染
?> 与 editable 插件共用时，编辑状态下，公式不会渲染，可以直接修改公式文本
?> 本插件通过 katex-mini 解析 latex 文本，字体文件 建议自行转存
开发插件 :id=develop
一个插件大致需要以下文件（plugin/template 中提供了一个模板）
-
build.js
构建文件，需要导出一个 object，可以内含以下项：名称 类型 默认值 功能 main string index.js 入口文件路径 platform string[] ['mp-weixin', 'mp-qq', 'mp-baidu', 'mp-alipay', 'mp-toutiao', 'uni-app'] 支持使用的平台 template string - 要被添加到模板文件中的标签 (nvue 不可用) methods object {} 用于处理模板中事件的方法 (nvue 不可用) style string - 用于模板文件的 css 样式 import string|string[] - 用于模板文件的 css 文件路径 usingComponents object {} 用于模板的组件或插件列表 (nvue 不可用) handler function - 自定义文件处理方法 -
index.js
入口文件，导出一个 function，每个组件在被创建时，会依次实例化各个插件，并传入组件实例可供调用
插件实例上可以挂载以下钩子方法，将在对应时机被调用名称 触发时机 参数 返回值 onUpdate 更新 html 内容时触发 更新的 html 内容和解析配置 如果对输入值进行了修改，则返回修改后的内容 onParse 解析到一个标签时触发 标签和解析器实例 返回 false 将移除该标签 onLoad dom 树加载完成时触发 - - onDetached 组件被移除时触发 - - -
README.md
使用说明 -
其他依赖文件
插件目录下，除了 .md 的文件、build.js 和 import 字段中的 css 文件，其他的都会被拷贝到生成的组件包中，因此请不要放置无关文件
对于仅在原生平台中使用的内容可放在 miniprogram 目录下，仅在 uni-app 中使用的内容可放在 uni-app 目录下，两个目录下可以分别放置 build.js
如果在插件中需要用到解析器（将 html 字符串解析为 nodes 数组），可以引入 src/parser.js 使用，方法如下：
const Parser = require('../parser.js')
var instance = new Parser(vm) // 实例化解析器，传入组件实例将自动获取相关配置
var nodes = instance.parse(content) // 解析完成
!> 如果编写了插件，在升级组件包时请注意备份，避免丢失
?> 欢迎提交实用的插件 pull requests 到 plugins 文件夹