淘宝开放平台

登录
文档中心 > 店铺动态卡片-开发指引

店铺动态卡片-开发指引

插件使用

更新时间：2024/07/31 访问次数：9145

一、前言

在使用插件之前，首页在【能力中心】申请获得插件或者在【淘宝开放平台】-【插件管理】引用自己自研插件；插件有两种方式：【静态声明方式】 和 【动态加载方式】。

前提条件

1）使用插件前请完成【插件订购】，注：加载插件体验版在联调可以不需要绑定，但是在小程序上线前要完成【插件订购】

2）手淘小程序暂时还开放分包功能；在静态引用插件时最多可以关联8个插件；

注：目前不支持插件直接引用插件；

二、静态声明

1. 插件使用声明

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "pages": [
    "pages/todos/todos",   
    "pages/add-todo/add-todo"
  ],
  "window": {
    "defaultTitle": "Todo App"
  },
  "plugins": { //----插件节点
    "myPlugin": {
      "version": "*", // 目前只支持设置 * 拉取当前上架最新版本
      "provider": "30192356090xxxxx"
    },
    //如需声明多个插件，重复添加自定义字段即可
    "yourPlugin": {
      "version": "*", // 目前只支持设置 * 拉取当前上架最新版本
      "provider": "3019235609xxxxxx" 
    },
    "threePlugin": {
      "version": "0.1.2", // 指定特定小程序版本
      "provider": "3019235609xxxxxx" 
    }
  }
}

1）plugins：可以声明多个插件，每个插件声明以使用者自定义的插件引用名作为唯一标识；

2）version：指定插件版本号；

3）provider：指定所引用的插件 ID（插件 ID 可咨询插件提供方）。说明：provider 属性值建议使用{{currentPluginId}} 动态 APPID。

注意：

1）插件引用名（如以上示例中的 myPlugin）由插件使用者自定义，无需和插件开发者的命名保持一致。在后续的插件使用中，该引用名将被用于表示该插件。

2）version 目前设置 *?拉取当前上架线上版本，如小程序在淘宝上加载插件在淘宝端的线上版本、小程序在天猫上加载插件在天猫端的线上版本。

3）同一个插件 ID 不能多次声明使用。

2. 使用插件

1）版本兼容

使用插件的小程序项目需要?0.60 或以上版本的 IDE 才能编译构建。

插件的运行要求小程序基础库为1.22.4 及以上版本，小程序在使用插件的时候，需要按照如下方式兼容：

1
2
3
4
// app.js
if (!my.canIUse('plugin')) {
   //检测插件能力
}
1
2
3
4
App({
  onLaunch() {},
  onShow() {},
})

注意：兼容代码一定要放到 app.js 文件的开头处，不能放到生命周期方法中，如果不做上述兼容处理，在基础库版本低于 1.18.0 的时候可能会导致页面白屏。

2）组件

可使用 基础组件、扩展组件 和 自定义组件，插件的自定义组件和普通的自定义组件使用方法类似。在 json 文件中定义需要引用的插件自定义组件时，通过 plugin:// 协议指明需要引用的插件自定义组件，如下所示：

1
2
3
4
5
{
  "usingComponents": {
    "hello": "plugin://myPlugin/hello"
  }
}

出于对插件的保护，插件提供的自定义组件在使用上有一定的限制：默认情况下ref 接口无法获得插件的自定义组件实例对象。可以通过给插件自定义组件定义 ref 定义段的方式指定被 ref引用时的返回值。

3）页面

跳转到插件页面时， URL 使用 plugin:// 前缀，格式为plugin://PLUGIN_NAME/PLUGIN_PAGE，如下所示：

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

也可以使用 API 进行跳转。

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

4）js 接口

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

该示例先通过requirePlugin 引用插件 API，然后访问插件暴露的 helloApi 函数以及 world变量。

1
2
3
const myPlugin = requirePlugin('myPlugin');
myPlugin.helloApi();
const word = myPlugin.world;

3. 动态加载

为了给开发者提供更好的体验，我们提供了动态加载插件的方式，不用在 app.json 中声明插件依赖，而是使用 my.loadPlugin 动态加载插件。这样小程序不用启动阶段就下载插件包，而是等到使用时，再下载插件包，可以有更好的性能体验。

1）动态插件使用声明

使用动态加载插件前，需要在app.json 中做如下声明，注意：只有加了以上声明，才可使用动态加载插件的方式。

1
2
3
{
  "useDynamicPlugins": true
}

2）使用插件

① 版本兼容

使用动态加载插件的小程序项目需要 1.0 或以上版本的 IDE 才能编译构建。

插件的运行要求小程序基础库为 1.21.0 及以上版本，小程序在动态加载插件的时候，需要按照如下方式兼容：

1
2
3
4
5
6
7
8
// app.js
if (!my.canIUse('plugin.dynamic')) {
    //检测是否可以动态插件
}
App({
  onLaunch() {},
  onShow() {},
})

② 动态加载插件

在使用插件的组件、页面或 API 之前，需要使用 my.loadPlugin 动态加载插件，如下所示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
Page({
  data: {
    isReady: false,
  },
  onLoad() {
    my.loadPlugin({
      plugin: '301923560xxxxxx@*', // 指定要加载的插件id和版本号，为*则每次拉取最新版本
      success: () => {
        const plugin = requirePlugin('dynamic-plugin://301923560xxxxxx');
        plugin.helloApi(); // 调用插件api
        this.setData({ isReady: true }); // 插件已加载，可以渲染插件组件了
      },
    });
  },
   
  navToPluginPage() {
    // 跳转到插件页面，hello为插件plugin.json中对外暴露的页面
    my.navigateTo({
      url: 'dynamic-plugin://301923560xxxxxx/hello'
    })
  }
})


1
2
3
4
5
6
7
8
<!-- 使用 component 组件 渲染插件组件 hello。hello为插件plugin.json中对外暴露的组件 -->
<component is="dynamic-plugin://301923560xxxxxx/hello" a:if="{{isReady}}">
  <view>hello</view>
</component>
<!--使用navigator组件跳转到插件页面-->
<navigator url="dynamic-plugin://301923560xxxxxx/hello">
</navigator>
<button onTap="navToPluginPage">跳转到插件页面</button>

③ 自定义组件

动态渲染自定义组件，需要使用 component 组件。

属性

属性名

类型

描述

is

String

要渲染的插件组件。需要使用dynamic-plugin: 前缀。

注意:

i）需要使用 dynamic-plugin: 指定要渲染的插件组件，格式为 dynamic-plugin:/{{PLUGIN_ID}}/PLUGIN_COMPONENT。PLUGIN_COMPONENT 为插件 plugin.json 中对外暴露的组件。

ii）必须使用 a:if控制 component 组件是否可以渲染。否则可能导致白屏。

iii）可以像使用自定义组件一样使用 component 组件，component 组件会将其props都传递给所要渲染的插件组件。

iv）默认情况下 ref 接口无法获得插件的自定义组件实例对象。可以通过给插件自定义组件定义 ref 定义段的方式 指定被 ref 引用时的返回值。

示例代码

1
2
3
4
5
6
7
8
9
<component
  is="dynamic-plugin://2019235609092837/hello"
  onComMount="onComMount"
  name="xiaoming"
  ref="saveRef"
  a:if="{{isReady}}"
>
    <view>hello</view>
</component>


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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);
  },
})

3）页面

跳转到插件页面，需要使用 dynamic-plugin: 前缀。格式为 dynamic-plugin:/{{PLUGIN_ID}}/PLUGIN_PAGE，其中PLUGIN_PAGE 为插件 plugin.json 中暴露的页面。如下所示：

1
2
3
4
5
6
7
8
9
10
11
12
<navigator url="dynamic-plugin://2019235609092837/hello">
  Go to pages/hello page!
</navigator>
也可以使用 API 进行跳转
my.loadPlugin({
  plugin: '3019235609092837@1.2.3',
  success() {
    my.navigateTo({
    url: 'dynamic-plugin://3019235609092837/hello',
    });
  },
});

注意：跳转页面前需要确保插件已加载。

4）js接口

使用插件的 js 接口时，可以使用 requirePlugin 方法，但需要使用 dynamic-plugin: 前缀。格式为：dynamic-plugin://{{PLUGIN_ID}}，如下所示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Page({
  onLoad() {
    my.loadPlugin({
      plugin: '3019235609092837@*',
      success: () => {
        const myPlugin = requirePlugin('myPlugin');
       
        myPlugin.helloApi();
         
        const word = myPlugin.world;
      },
    })
  },
})

三、相关问题

1.小程序申请插件订购后，是否需要再申请额外权限包？

答： 小程序成功订购插件之后， 在调用插件能力，已在插件内部做验证了，小程序不需要额外权限包； 如调用调用插件API出现“无权调用”、“户未授权的问题”可以检查以下点：

1）小程序是否完成插件订购；

2）插件本身没有申请权限包，可联系插件提供者二次确认一下。

2. 通过“*”引用插件规则？

若通过“*”引用插件，则IDE模拟器最新线上版本，如插件在淘宝端上线0.0.1版本、千牛端上线0.0.2版本，*号引用加载到0.0.2版本。



FAQ

关于此文档暂时还没有FAQ
有用(0) 我要提问
返回
顶部