开发插件前,请阅读了解《小程序插件接入指南》了解开通流程及开放范围,并开通插件功能。如果未开通插件功能,将无法上传插件。
插件类型的项目可以在开发者工具中直接创建。
新建插件类型的项目后,如果创建示例项目,则项目中将包含三个目录:
miniprogram 目录内容可以当成普通小程序来编写,用于插件调试、预览和审核。下面的内容主要介绍 plugin 中的插件代码及 doc 中的插件开发文档。
我们提供了一个可以直接在微信开发者工具中查看的完整插件示例,开发者可以和本文互相对照以便理解。请注意:
一个插件可以包含若干个自定义组件、页面,和一组 js 接口。插件的目录内容如下:
plugin
├── components
│ ├── hello-component.js // 插件提供的自定义组件(可以有多个)
│ ├── hello-component.json
│ ├── hello-component.wxml
│ └── hello-component.wxss
├── pages
│ ├── hello-page.js // 插件提供的页面(可以有多个,自小程序基础库版本 2.1.0 开始支持)
│ ├── hello-page.json
│ ├── hello-page.wxml
│ └── hello-page.wxss
├── index.js // 插件的 js 接口
└── plugin.json // 插件配置文件
向使用者小程序开放的所有自定义组件、页面和 js 接口都必须在插件配置文件 plugin.json 列出,格式如下:
代码示例:
{
"publicComponents": {
"hello-component": "components/hello-component"
},
"pages": {
"hello-page": "pages/hello-page"
},
"main": "index.js"
}
这个配置文件将向使用者小程序开放一个自定义组件 hello-component,一个页面 hello-page 和 index.js 下导出的所有 js 接口。
请注意:在插件开发中,只有部分接口可以直接调用;另外还有部分能力(如 获取用户信息 和 发起支付 等)可以通过插件功能页的方式使用。
插件可以定义若干个自定义组件,这些自定义组件都可以在插件内相互引用。但提供给使用者小程序使用的自定义组件必须在配置文件的 publicComponents 段中列出(参考上文)。
除去接口限制以外,自定义组件的编写和组织方式与一般的自定义组件相同,每个自定义组件由 wxml, wxss, js 和 json 四个文件组成。具体可以参考自定义组件的文档。
插件从小程序基础库版本 2.1.0 开始支持页面。插件可以定义若干个插件页面,可以从本插件的自定义组件、其他页面中跳转,或从使用者小程序中跳转。所有页面必须在配置文件的 pages 段中列出(参考上文)。
除去接口限制以外,插件的页面编写和组织方式与一般的页面相同,每个页面由 wxml, wxss, js 和 json 四个文件组成。具体可以参考其他关于页面的文档。
插件执行页面跳转的时候,可以使用 navigator 组件。当插件跳转到自身页面时, url 应设置为这样的形式:plugin-private://PLUGIN_APPID/PATH/TO/PAGE 。需要跳转到其他插件时,也可以这样设置 url 。
代码示例:
<navigator url="plugin-private://wxidxxxxxxxxxxxxxx/pages/hello-page">
Go to pages/hello-page!
</navigator>
自基础库版本 2.2.2 开始,在插件自身的页面中,插件还可以调用 wx.navigateTo 来进行页面跳转, url 格式与使用 navigator 组件时相仿。
插件可以在接口文件(在配置文件中指定,详情见上文)中 export 一些 js 接口,供插件的使用者调用,如:
代码示例:
module.exports = {
hello: function() {
console.log("Hello plugin!")
}
}
从基础库 2.11.1 起,在插件中有全局函数 requireMiniProgram,可以获取由使用者小程序导出的内容。
例如,使用者小程序做了如下导出:
// 使用者小程序
module.exports = {
greeting() {
return "Greetings from Wechat MiniProgram!";
}
}
那么在插件中,可以这样获得内容:
// 插件
const miniProgramExports = requireMiniProgram();
miniProgramExports.greeting(); // "Greetings from Wechat MiniProgram!"
插件可以像小程序一样预览和上传,但插件没有体验版。
插件会同时有多个线上版本,由使用插件的小程序决定具体使用的版本号。
手机预览和提审插件时,会使用一个特殊的小程序来套用项目中 miniprogram 文件夹下的小程序,从而预览插件。
通常情况下,可以将 miniprogram 下的代码当做使用插件的小程序代码,来进行插件的调试和测试。
但有时,需要将插件的代码放在实际运行的小程序中进行调试、测试。此时,可以使用开发版的小程序直接引用开发版插件。方法如下:
如果开发版小程序引用了开发版插件,此时这个小程序就不能上传发布了。必须要将插件版本设为正式版本之后,小程序才可以正常上传、发布。
在使用者小程序使用插件时,插件代码并不可见。因此,除了插件代码,我们还支持插件开发者上传一份插件开发文档。这份开发文档将展示在插件详情页,供其他开发者在浏览插件和使用插件时进行阅读和参考。插件开发者应在插件开发文档中对插件提供的自定义组件、页面、接口等进行必要的描述和解释,方便使用者小程序正确使用插件。
插件开发文档必须放置在插件项目根目录中的 doc 目录下,目录结构如下:
doc
├── README.md // 插件文档,应为 markdown 格式
└── picture.jpg // 其他资源文件,仅支持图片
其中,README.md 的编写有一定的 限制条件,具体来说:
编辑 README.md 之后,可以在开发者工具左侧资源管理器的文件栏中右键单击 README.md,并选择上传文档。发布上传文档后,文档不会立刻发布。此时可以使用帐号和密码登录 管理后台 ,在 小程序插件 > 基本设置 中预览、发布插件文档。
插件不能直接引用其他插件。但如果小程序引用了多个插件,插件之间是可以互相调用的。
一个插件调用另一个插件的方法,与插件调用自身的方法类似。可以使用 plugin-private://APPID 访问插件的自定义组件、页面(暂不能使用 plugin:// )。
对于 js 接口,可使用 requirePlugin ,但目前尚不能在文件一开头就使用 requirePlugin ,因为被依赖的插件可能还没有初始化,请考虑在更晚的时机调用 requirePlugin ,如接口被实际调用时、组件 attached 时。(未来会修复这个问题。)
插件在使用 wx.request 等 API 发送网络请求时,将会额外携带一个签名 HostSign ,用于验证请求来源于小程序插件。这个签名位于请求头中,形如:
X-WECHAT-HOSTSIGN: {"noncestr":"NONCESTR", "timestamp":"TIMESTAMP", "signature":"SIGNATURE"}
其中, NONCESTR 是一个随机字符串, TIMESTAMP 是生成这个随机字符串和 SIGNATURE 的 UNIX 时间戳。它们是用于计算签名 SIGNATRUE 的参数,签名算法为:
SIGNATURE = sha1([APPID, NONCESTR, TIMESTAMP, TOKEN].sort().join(""))
其中,APPID 是 所在小程序 的 AppId (可以从请求头的 referrer 中获得);TOKEN 是插件 Token,可以在小程序插件基本设置中找到。
网络请求的 referer 格式固定为 https://servicewechat.com/{appid}/{version}/page-frame.html,其中 {appid} 为小程序的 appid,{version} 为小程序的版本号,版本号为 0 表示为开发版、体验版以及审核版本,版本号为 devtools 表示为开发者工具,其余为正式版本。
插件开发者可以在服务器上按以下步骤校验签名:
自基础库版本 2.0.7 开始,在小程序运行期间,若网络状况正常, NONCESTR 和 TIMESTAMP 会每 10 分钟变更一次。如有必要,可以通过判断 TIMESTAMP 来确定当前签名是否依旧有效。
绘图接口和方法wx.canvasToTempFilePath(OBJECT)把当前画布指定区域的内容导出生成指定大小的图片,并返回文件路径。OBJECT参数...
绘图接口和方法canvasContext.save定义保存当前的绘图上下文。restore定义恢复之前保存的绘图上下文。例子const ctx = wx.create...
CREATE PUBLICATION — 定义一个新的发布大纲CREATE PUBLICATION name[ FOR TABLE [ ONLY ] table_name [ * ] [, ...]| FOR ALL ...
CREATE USER — 定义一个新的数据库角色大纲CREATE USER name [ [ WITH ] option [ ... ] ]这里 option 可以是:SUPERUSER | NOS...
DROP ACCESS METHOD — 移除一种访问方法大纲DROP ACCESS METHOD [ IF EXISTS ] name [ CASCADE | RESTRICT ]简介 DROP ACCESS M...
XSL-FO list-block 对象XSL-FO 参考手册定义和用法 fo:list-block 对象用于格式化整个列表。 下面列举了四个用于创建列表的 XSL-...
XSD 仅含文本 在XMLSchema复合元素的类型中,包括仅含文本的复合元素。仅含文本的复合元素可包含文本和属性。仅含文本的复合元素...
XSLT xsl:choose 元素本节将为你介绍 xsl:choose 元素的使用。xsl:choose 元素用于结合 xsl:when 和 xsl:otherwise 来表达多重条...
XSLT xsl:decimal-format 元素本节是对 XSLTxsl:decimal-format元素使用的介绍。 完整的 XSLT 元素参考手册定义和用法 xsl:decim...