支付宝小程序插件 插件使用

插件使用有两种方式：静态声明方式 和 动态加载方式。

前提条件

• 使用插件前请完成 订购插件
• 如果主体小程序使用了 分包，支付宝 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 组件。

属性

注意:

1. 需要使用 dynamic-plugin: 指定要渲染的插件组件，格式为 dynamic-plugin:/PLUGIN_ID/PLUGIN_COMPONENT。PLUGIN_COMPONENT 为插件 plugin.json 中对外暴露的组件。
2. 必须使用 a:if 控制 component 组件是否可以渲染。否则可能导致白屏。
3. 可以像使用自定义组件一样使用 component 组件，component 组件会将其props都传递给所要渲染的插件组件。
4. 默认情况下 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;
      },
    })
  },
})