支付宝小程序插件 插件使用
插件使用有两种方式：静态声明方式 和 动态加载方式。
前提条件
- 使用插件前请完成 订购插件
- 如果主体小程序使用了 分包，支付宝 10.1.85 版本及以上支持使用插件
- 不支持一个小程序关联 10 个及以上插件
- 不支持较早版本的 APPID 为 8 位数字的小程序
静态声明
插件使用声明
使用插件前，使用者需要在 app.json 中声明需要使用的插件，示例代码如下：
{
"plugins": {
"myPlugin": {
"version": "*", // 目前只支持设置 * 拉取当前上架最新版本
"provider": "2019235609092837"
},
//如需声明多个插件，重复添加自定义字段即可
"yourPlugin": {
"version": "*", // 目前只支持设置 * 拉取当前上架最新版本
"provider": "2019235609090000"
}
}
}- plugins：可以声明多个插件，每个插件声明以使用者自定义的插件引用名作为唯一标识；
- version：指定插件版本号；
- provider：指定所引用的插件 ID（插件 ID 可咨询插件提供方）。
说明：provider 属性值建议使用 {{currentPluginId}} 动态 APPID。
注意：
- 插件引用名（如以上示例中的 myPlugin）由插件使用者自定义，无需和插件开发者的命名保持一致。在后续的插件使用中，该引用名将被用于表示该插件。
- version 目前只支持设置
*****拉取当前上架最新版本。 - 同一个插件 ID 不能多次声明使用。
使用插件
版本兼容
使用插件的小程序项目需要 0.60 或以上版本的 IDE 才能编译构建。
插件的运行要求小程序基础库为 1.22.4 及以上版本，支付宝客户端 10.1.85 及以上的版本，小程序在使用插件的时候，需要按照如下方式兼容：
// app.js
if (!my.canIUse('plugin') && !my.isIDE) {
my.ap && my.ap.updateAlipayClient && my.ap.updateAlipayClient();
}
App({
onLaunch() {},
onShow() {},
})注意：兼容代码一定要放到 app.js 文件的开头处，不能放到生命周期方法中，如果不做上述兼容处理，在基础库版本低于 1.18.0 的时候可能会导致页面白屏。
组件
可使用 基础组件、扩展组件 和 自定义组件，插件的自定义组件和普通的自定义组件使用方法类似。在 json 文件中定义需要引用的插件自定义组件时，通过 plugin:// 协议指明需要引用的插件自定义组件，如下所示：
{
"usingComponents": {
"hello": "plugin://myPlugin/hello"
}
}出于对插件的保护，插件提供的自定义组件在使用上有一定的限制：默认情况下 ref 接口无法获得插件的自定义组件实例对象。可以通过给插件自定义组件定义 ref 定义段的方式 指定被 ref 引用时的返回值。
页面
跳转到插件页面时， URL 使用 plugin:// 前缀，格式为 plugin://PLUGIN_NAME/PLUGIN_PAGE，如下所示：
<navigator url="plugin://myPlugin/hello">
Go to pages/hello page!
</navigator>也可以使用 API 进行跳转
my.navigateTo({
url: 'plugin://myPlugin/hello',
})js 接口
使用插件的 js 接口时，可以使用 requirePlugin 方法。
该示例先通过 requirePlugin 引用插件 API，然后访问插件暴露的 helloApi 函数以及 world 变量。
const myPlugin = requirePlugin('myPlugin');
myPlugin.helloApi();
const word = myPlugin.world;动态加载
为了给开发者提供更好的体验，我们提供了动态加载插件的方式，不用在 app.json 中声明插件依赖，而是使用 my.loadPlugin 动态加载插件。这样小程序不用启动阶段就下载插件包，而是等到使用时，再下载插件包，可以有更好的性能体验。
动态加载插件使用声明
使用动态加载插件前，需要在 app.json 中做如下声明
{
"useDynamicPlugins": true
}注意：只有加了以上声明，才可以使用动态加载插件的方式。
使用插件
版本兼容
使用动态加载插件的小程序项目需要 1.0 或以上版本的 IDE 才能编译构建。
插件的运行要求小程序基础库为 1.21.0 及以上版本，小程序在动态加载插件的时候，需要按照如下方式兼容：
// app.js
if (!my.canIUse('plugin.dynamic') && !my.isIDE) {
my.ap && my.ap.updateAlipayClient && my.ap.updateAlipayClient();
}
App({
onLaunch() {},
onShow() {},
})使用 my.loadPlugin 动态加载插件
在使用插件的组件、页面或 API 之前，需要使用 my.loadPlugin 动态加载插件，如下所示
Page({
data: {
isReady: false,
},
onLoad() {
my.loadPlugin({
plugin: '2019235609092837@*', // 指定要加载的插件id和版本号，为*则每次拉取最新版本
success: () => {
const plugin = requirePlugin('dynamic-plugin://2019235609092837');
plugin.helloApi(); // 调用插件api
this.setData({ isReady: true }); // 插件已加载，可以渲染插件组件了
},
});
},
navToPluginPage() {
// 跳转到插件页面，hello为插件plugin.json中对外暴露的页面
my.navigateTo({
url: 'dynamic-plugin://2019235609092837/hello'
})
}
})<!-- 使用 component 组件 渲染插件组件 hello。hello为插件plugin.json中对外暴露的组件 -->
<component is="dynamic-plugin://2019235609092837/hello" a:if="{{isReady}}">
<view>hello</view>
</component>
<navigator url="dynamic-plugin://2019235609092837/hello">使用navigator组件跳转到插件页面</navigator>
<button onTap="navToPluginPage">跳转到插件页面</button> 自定义组件
动态渲染自定义组件，需要使用 component 组件。
属性
| 属性名 | 类型 | 描述 |
|---|---|---|
| is | String | 要渲染的插件组件。需要使用dynamic-plugin: 前缀 |
注意:
- 需要使用 dynamic-plugin: 指定要渲染的插件组件，格式为 dynamic-plugin:/PLUGIN_ID/PLUGIN_COMPONENT。PLUGIN_COMPONENT 为插件 plugin.json 中对外暴露的组件。
- 必须使用 a:if 控制 component 组件是否可以渲染。否则可能导致白屏。
- 可以像使用自定义组件一样使用 component 组件，component 组件会将其props都传递给所要渲染的插件组件。
- 默认情况下 ref 接口无法获得插件的自定义组件实例对象。可以通过给插件自定义组件定义 ref 定义段的方式 指定被 ref 引用时的返回值。
示例代码
<component
is="dynamic-plugin://2019235609092837/hello"
onComMount="onComMount"
name="xiaoming"
ref="saveRef"
a:if="{{isReady}}"
>
<view>hello</view>
</component>Page({
data: {
isReady: false,
},
onLoad() {
my.loadPlugin({
plugin: '2019235609092837@*',
success() {
this.setData({ isReady: true });
},
})
},
onComMount() {
console.log('dynamic-plugin://2019235609092837/hello is mounted')
},
saveRef(ref) {
console.log(ref);
},
})页面
跳转到插件页面，需要使用 dynamic-plugin: 前缀。格式为 dynamic-plugin:/PLUGIN_ID/PLUGIN_PAGE，其中PLUGIN_PAGE 为插件 plugin.json 中暴露的页面。如下所示
<navigator url="dynamic-plugin://2019235609092837/hello">
Go to pages/hello page!
</navigator>也可以使用 API 进行跳转
my.loadPlugin({
plugin: '2019235609092837@1.2.3',
success() {
my.navigateTo({
url: 'dynamic-plugin://2019235609092837/hello',
});
},
});注意：跳转页面前需要确保插件已加载。
js 接口
使用插件的 js 接口时，可以使用 requirePlugin 方法，但需要使用 dynamic-plugin: 前缀。格式为: dynamic-plugin://PLUGIN_ID，如下所示
Page({
onLoad() {
my.loadPlugin({
plugin: '2019235609092837@*',
success() {
const myPlugin = requirePlugin('myPlugin');
myPlugin.helloApi();
const word = myPlugin.world;
},
})
},
})