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

插件使用有兩種方式：靜態(tài)聲明方式 和 動態(tài)加載方式。

前提條件

• 使用插件前請完成 訂購插件
• 如果主體小程序使用了 分包，支付寶 10.1.85 版本及以上支持使用插件
• 不支持一個小程序關(guān)聯(lián) 10 個及以上插件
• 不支持較早版本的 APPID 為 8 位數(shù)字的小程序

靜態(tài)聲明

插件使用聲明

使用插件前，使用者需要在 app.json 中聲明需要使用的插件，示例代碼如下：

{
  "plugins": {
    "myPlugin": {
      "version": "*", // 目前只支持設(shè)置 * 拉取當(dāng)前上架最新版本
      "provider": "2019235609092837"
},
    //如需聲明多個插件，重復(fù)添加自定義字段即可
    "yourPlugin": {
      "version": "*", // 目前只支持設(shè)置 * 拉取當(dāng)前上架最新版本
      "provider": "2019235609090000"  
    }
  }
}

• plugins：可以聲明多個插件，每個插件聲明以使用者自定義的插件引用名作為唯一標(biāo)識；

• version：指定插件版本號；

• provider：指定所引用的插件 ID（插件 ID 可咨詢插件提供方）。

說明：provider 屬性值建議使用 {{currentPluginId}} 動態(tài) APPID。

注意：

• 插件引用名（如以上示例中的 myPlugin）由插件使用者自定義，無需和插件開發(fā)者的命名保持一致。在后續(xù)的插件使用中，該引用名將被用于表示該插件。
• version 目前只支持設(shè)置 ***** 拉取當(dāng)前上架最新版本。
• 同一個插件 ID 不能多次聲明使用。

使用插件

版本兼容

使用插件的小程序項目需要 0.60 或以上版本的 IDE 才能編譯構(gòu)建。

插件的運行要求小程序基礎(chǔ)庫為 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 文件的開頭處，不能放到生命周期方法中，如果不做上述兼容處理，在基礎(chǔ)庫版本低于 1.18.0 的時候可能會導(dǎo)致頁面白屏。

組件

可使用 基礎(chǔ)組件、擴展組件 和 自定義組件，插件的自定義組件和普通的自定義組件使用方法類似。在 json 文件中定義需要引用的插件自定義組件時，通過 plugin:// 協(xié)議指明需要引用的插件自定義組件，如下所示：

{
  "usingComponents": {
    "hello": "plugin://myPlugin/hello"
  }
}

出于對插件的保護，插件提供的自定義組件在使用上有一定的限制：默認(rèn)情況下 ref 接口無法獲得插件的自定義組件實例對象。可以通過給插件自定義組件定義 ref 定義段的方式 指定被 ref 引用時的返回值。

頁面

跳轉(zhuǎn)到插件頁面時， URL 使用 plugin:// 前綴，格式為 plugin://PLUGIN_NAME/PLUGIN_PAGE，如下所示：

<navigator url="plugin://myPlugin/hello">
  Go to pages/hello page!
</navigator>

也可以使用 API 進行跳轉(zhuǎn)

my.navigateTo({
  url: 'plugin://myPlugin/hello',
})

js 接口

使用插件的 js 接口時，可以使用 requirePlugin 方法。

該示例先通過 requirePlugin 引用插件 API，然后訪問插件暴露的 helloApi 函數(shù)以及 world 變量。

const myPlugin = requirePlugin('myPlugin');


myPlugin.helloApi();
const word = myPlugin.world;

動態(tài)加載

為了給開發(fā)者提供更好的體驗，我們提供了動態(tài)加載插件的方式，不用在 app.json 中聲明插件依賴，而是使用 my.loadPlugin 動態(tài)加載插件。這樣小程序不用啟動階段就下載插件包，而是等到使用時，再下載插件包，可以有更好的性能體驗。

動態(tài)加載插件使用聲明

使用動態(tài)加載插件前，需要在 app.json 中做如下聲明

{
  "useDynamicPlugins": true
}

注意：只有加了以上聲明，才可以使用動態(tài)加載插件的方式。

使用插件

版本兼容

使用動態(tài)加載插件的小程序項目需要 1.0 或以上版本的 IDE 才能編譯構(gòu)建。

插件的運行要求小程序基礎(chǔ)庫為 1.21.0 及以上版本，小程序在動態(tài)加載插件的時候，需要按照如下方式兼容：

// app.js
if (!my.canIUse('plugin.dynamic') && !my.isIDE) {
  my.ap && my.ap.updateAlipayClient && my.ap.updateAlipayClient();
}
App({
  onLaunch() {},
  onShow() {},
})

使用 my.loadPlugin 動態(tài)加載插件

在使用插件的組件、頁面或 API 之前，需要使用 my.loadPlugin 動態(tài)加載插件，如下所示

Page({
  data: {
    isReady: false,
  },
  onLoad() {
    my.loadPlugin({
      plugin: '2019235609092837@*', // 指定要加載的插件id和版本號，為*則每次拉取最新版本
      success: () => {
        const plugin = requirePlugin('dynamic-plugin://2019235609092837');
        plugin.helloApi(); // 調(diào)用插件api


        this.setData({ isReady: true }); // 插件已加載，可以渲染插件組件了
      },
    });
  },
  navToPluginPage() {
    // 跳轉(zhuǎn)到插件頁面，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組件跳轉(zhuǎn)到插件頁面</navigator>
<button onTap="navToPluginPage">跳轉(zhuǎn)到插件頁面</button>    

自定義組件

動態(tài)渲染自定義組件，需要使用 component 組件。

屬性

注意:

1. 需要使用 dynamic-plugin: 指定要渲染的插件組件，格式為 dynamic-plugin:/PLUGIN_ID/PLUGIN_COMPONENT。PLUGIN_COMPONENT 為插件 plugin.json 中對外暴露的組件。
2. 必須使用 a:if 控制 component 組件是否可以渲染。否則可能導(dǎo)致白屏。
3. 可以像使用自定義組件一樣使用 component 組件，component 組件會將其props都傳遞給所要渲染的插件組件。
4. 默認(rèn)情況下 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);
  },
})

頁面

跳轉(zhuǎn)到插件頁面，需要使用 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 進行跳轉(zhuǎn)

my.loadPlugin({
  plugin: '2019235609092837@1.2.3',
  success() {
    my.navigateTo({
        url: 'dynamic-plugin://2019235609092837/hello',
        });
  },
});

注意：跳轉(zhuǎn)頁面前需要確保插件已加載。

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;
      },
    })
  },
})