插件开发

更新时间：2023/07/07 访问次数：3437

插件创建成功后，可下载IDE开始开发插件。

注意：

插件 acss 文件中，基本选择器只支持 ID 与 class 选择器，不支持标签、属性、通配符选择器；
如需获取宿主 appId，可以通过 my.getParentAppIdSync() 进行调用；
不支持使用【getApp】方法获取当前 app 实例；
不支持通过【getCurrentPages】方法获取小程序的页面信息；
不支持在插件内使用 web-view 组件;

1.插件目录

新建插件类型的示例项目中包含如下目录, 小程序代码目录可以当成普通小程序来编写

plugin目录: 插件代码目录，用于编写小程序插件代码；
client目录：插件本身不能独立运行，client目录做为测试小程序插件Demo，用于插件开发调试、插件版本上传做为版本审批依据；
client.app.json：在研发插件时，version默认dev

{
  "plugins": {
    "myPlugin": {
      "version": "dev", //注：固定dev 对于插件研发默认指定dev版本
      "provider": "{{currentPluginId}}" // 建议使用"{{currentPluginId}}"，研发插件则为插件ID 
    }
  }
}

mini.project.json文件：

{
  "miniprogramRoot": "client",
  "pluginRoot": "plugin", 
  "compileType": "plugin", 
  "appid": "300000000xxxxxx"//填写当前关联插件ID
}

插件可以包含若干个自定义组件、页面和一组 js 接口。插件 plugin 文件夹中的示例目录内容如下：

plugin
  |-----components // 插件提供的自定义组件（可以有多个) 
  |----------hello-component
    | |----hello-component.acss
    | |----hello-component.axml
    | |----hello-component.j
    | |----hello-component.json
  |-----pages // 插件提供的页面（可以有多个)
    |----------hello-page
    | |----hello-page.acss
    | |----hello-page.axml
    | |----hello-page.js
    | |----hello-page.json
    |----------index
    | |----index.acss
    | |----index.axml
    | |----index.js
    | |----index.json
  |-----index.js // 插件的 js 接口
  |-----plugin.json // 插件配置文件

2.插件配置

向第三方小程序开放的所有组件、页面和 js 接口都必须在 plugin.json 中声明，格式如下：

{
  "publicComponents": {
    "hello-component": "components/hello-component"
  },
  "publicPages": {
    "hello-pages": "pages/hello-page"
  },
  "pages": [
    "pages/hello-page",
    "pages/index"
  ],
  "main": "index.js"
}

每个配置的含义如下:

publicComponents**：**列出所有向小程序开放的自定义组件。
publicPages**：**列出所有向小程序开放的页面。
Pages**：**列出插件所有页面（包含向小程序开放的以及不向小程序开放的页面）。
main**：**插件面向第三方小程序的 js 接口。

3.创建插件项目

打开IDE，左侧选择【淘宝-商家应用插件】，点击 + 号新建项目，填写项目名称、项目路径后进入项目：

选择关联在控制台创建的插件

4.插件开发

4.1 自定义组件

插件可以定义若干个自定义组件，这些组件在插件内是可以互相引用的，但是如果想要第三方小程序可以使用，就必须在 plugin.json 中列出，具体见上文【插件配置】。

插件自定义组件和普通自定义组件一样，每个自定义组件由 axml、acss、js以及json四个文件组成，具体参见【自定义组件文档】

4.2 插件页面

插件也可以定义若干个自定义页面，可以从本插件的自定义组件、其他页面或者第三方小程序中跳转。其中，提供给第三方小程序跳转的页面必须在plugin.json中列出。publicPages 和 pages 都需要配置

插件页面也和普通小程序的页面一样，每个页面由 axml、acss、js以及json四个文件组成，具体参见【页面文档】

插件执行页面跳转的时候，可以使用 navigator 组件或者 my.navigateTo。使用时有如下注意事项:

不支持跳转到小程序页面；
不支持使用 my.switchTab, 其他api可以正常使用；
不支持插件作为首页；

4.3 插件接口

插件可以在接口文件中 export 一些 js 接口，供插件的使用者调用，如：

export default {
  helloApi: function () {
    console.log('helloApi!')
  }
}

5.真机预览

点击 IDE 中右上角 真机调试 或预览按钮查看效果。

6.上传插件

完成开发后点击界面右上角上传。完成插件上传后，可进入【淘宝开放平台】对插件进行管理，如插件提审、插件联调；

7.效果示例

8.注意事项

8.1 插件间互相调用

插件不支持直接使用其他插件。如果小程序引用了多个插件，插件之间可以互相调用但不可以互相跳转。

例如，第三方小程序中的 app.json ：

{
  "plugins": {
    "pluginOne": {
      "version": "1.0.0",
      "provider": "2019081209098989"
    },
    "pluginTwo": {
      "version": "1.0.0",
      "provider": "2019081209091212"
    }
  }
}

上面的示例中，第三方小程序通过 app.json 引用了两个插件，那么插件 pluginOne 可以通过以下三种方式访问 pluginTwo 的组件、页面以及 js 接口：

1.在 json 文件中配置 plugin://pluginTwo/hello 来引用插件 pluginTwo 的自定义组件。2.requirePlugin(‘pluginTwo’) 的方式来引用插件 pluginTwo 暴露的 js 接口。

8.2 getCurrentPages

getCurrentPages 用于返回当前页面栈，返回过程中存在如下限制：

插件页中调用该方法无法获取小程序页面栈信息，即对应的小程序页面在获取的页面栈中值为 null。
小程序页中调用该方法无法获取插件页面栈信息，即对应的插件页面在获取的页面栈中值为 null。

例如当前的页面栈从栈底到栈顶依次为：小程序页面 A、小程序页面 B、插件页面 C、插件页面 D

在小程序页中调用 getCurrentPages 方法返回页面栈：

// PageA/PageB 为小程序页面实例 [PageA, PageB, null, null]

在插件页中调用 getCurrentPages 方法返回页面栈：

// PageC/PageD 为插件页面实例 [null, null, PageC, PageD]

8.3 插件中如何跳转至小程序页面

出于安全性考虑，插件不支持随意跳转至小程序的页面。如有相关需求，可以将跳转方式包装成方法，通过插件暴露的 API，传递给插件，插件内部可以通过这些方法实现跳转。详情请下载插件跳转小程序页面示例压缩包；

淘宝开放平台

插件