本文档意在介绍如何把uni-app项目编译为小程序插件，如果想了解如何在uni-app中引用和使用小程序插件，另见文档：使用小程序插件
小程序插件规范由小程序厂商定义，插件是对一组 js 接口、自定义组件或页面的封装，用于嵌入到小程序中使用。
uni-app 不仅仅可以开发完整的小程序，也可以编译为小程序插件。
平台差异说明

微信小程序 支付宝小程序 百度小程序 字节跳动小程序、飞书小程序 QQ 小程序 快手小程序
√ √ ( 3.2.9+ ) x x x x

注意

  1. 开发 微信小程序插件 时，基础库版本 1.9.6 开始支持。（如果插件包含页面，则需要基础库版本 2.1.0 。）
  2. 开发 支付宝小程序插件 时，支付宝 IDE 版本要求在 0.60 及以上

    插件目录结构

    编译到微信小程序插件结果
    1. plugin
    2. ├── components               // 插件提供的自定义组件（可以有多个）
    3. │   ├── hello-component.js
    4. │   ├── hello-component.json
    5. │   ├── hello-component.wxml
    6. │   └── hello-component.wxss
    7. ├── pages
    8. │   ├── hello-page.js        // 插件提供的页面（可以有多个）
    9. │   ├── hello-page.json
    10. │   ├── hello-page.wxml
    11. │   └── hello-page.wxss
    12. ├── index.js                 // 插件的 js 接口
    13. └── plugin.json              // 插件配置文件

    插件配置文件

    plugin.json 在 uni-app 项目中和 pages.json 同级。向第三方小程序开放的所有组件、页面和 js 接口都必须在 plugin.json 中声明

  • mp-weixin

    1. {
    2.   "publicComponents": {
    3.       "hello-component": "components/hello-component"
    4.   },
    5.   "pages": {
    6.       "hello-page": "pages/hello-page"
    7.   },
    8.   "main": "index.js"
    9. }

  • 每个配置的含义如下：

    • publicComponents：列出所有向小程序开放的自定义组件。
    • pages：列出所有向小程序开放的页面。
    • main：插件面向第三方小程序的 js 接口。

  • mp-alipay

    1. {
    2.  "publicComponents": {
    3.    "hello-component": "components/hello-component"
    4.  },
    5.  "publicPages": {
    6.    "hello-pages": "pages/hello-page"
    7.  },
    8.  "pages": [
    9.    "pages/hello-page"
    10.    "pages/index"
    11.  ],
    12.  "main": "index.js"
    13. }

  • 每个配置的含义如下：

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

注意

  1. mp-weixin 中的 pages 项与 mp-alipay 中的 publicPages 项作用一致
  2. mp-alipay 中供外部使用的页面，需要在 pages 中声明，数组类型
  3. 由于两端的格式不一致，可以在 plugin.json 中使用条件编译处理

    编译步骤

  • 安装 cli 最新的 alpha 版或最新的稳定版。截止文章发布时最新版本为：2.0.0-alpha-32120210809004。
  • 执行命令行：yarn dev:mp-weixin — —plugin test-plugin。
  • 其中 test-plugin 为编译出插件包的名字。 项目根目录\dist\dev\mp-weixin\test-plugin 中即是可执行小程序插件代码。
  • mp-alipay 平台插件编译后续发布，请留意更新日志。

    如何在项目中使用插件

  1. 宿主小程序是 uni-app项目，在 manifest.json 中配置相关信息即可，详情

  2. 宿主为原生小程序，在项目的 app.json 中配置即可：

  3. 自定义条件编译（详情），在package.json中添加如以下配置：

    1. "uni-app": {
    2. "scripts": {
    3.  "mp-wx-plugin": {
    4.    "title": "微信小程序插件",
    5.    "env": {
    6.      "UNI_PLATFORM": "mp-weixin"
    7.    },
    8.    "define": {
    9.      "MP-WX-PLUGIN": true
    10.    }
    11.  },
    12.  "mp-ali-plugin": {
    13.    "title": "阿里小程序插件",
    14.    "env": {
    15.      "UNI_PLATFORM": "mp-alipay"
    16.    },
    17.    "define": {
    18.      "MP-ALI-PLUGIN": true
    19.    }
    20.  },
    21. }
    22. }

    使用条件编译：

    1. // #ifdef MP-WX-PLUGIN
    2. /**
    3. * CODE
    4. */
    5. // #endif

    编译时执行命令：yarn dev:custom mp-wx-plugin —plugin test-plugin 即可，可将脚本写入script中，每次执行更加简化。

    1. {
    2.  "dev:mp-wx-plugin": "yarn dev:custom mp-wx-plugin --plugin",
    3.  "dev:mp-ali-plugin": "yarn dev:custom mp-ali-plugin --plugin"
    4. }

    注意

  4. 组件在插件内部未使用，需要在宿主小程序中使用时，要在 main.js 中引入使用一下，否则编译后会丢失未使用插件。例如：

    1. import helloList from '.../helloList';
    2. Vue.component('hello-list', helloList);

  5. 插件中所编写的页面需要在 pages.json 中填写。

  6. 如果有多个 uni-app 编译的 插件 需要运行在同一个小程序中，不要重名。
  7. 名称不要有特殊字符，比如 \。会用到这个名字来挂载一个方法。
    • 已经手动替换为 _ ，其他的特殊字符不要写。
  9. 各家小程序插件对各 api 的支持情况不同，具体请查看小程序官方文档的相关描述