插件使用 -凯发app官方网站

开始使用

ampe

多端开发

鸿蒙

插件

插件获取与使用

插件开发

插件发布

插件管理

插件技术知识汇总

安全

openid 开发指南

扩展能力

更新时间：2025-07-17 14:38:32

订阅更新

我的文档

设置

简介

插件使用有静态声明和动态加载两种方式，推荐使用静态声明的懒加载方式。

使用限制

●

使用插件前请完成

插件获取

。

●

支付宝 10.1.85 及以上版本支持已使用分包的主体小程序应用插件。

●

静态加载仅支持一个小程序最多关联 10 个插件，动态加载无限制。

●

本地开发接入插件时，如果需要更新插件版本，需要到开放平台控制台进行操作才会生效，详情可查看

插件版本升级

。

●

小程序插件只支持在小程序中使用，不支持在小程序插件中使用小程序插件。

静态声明

使用插件前，使用者需要在 app.json 中声明需要使用的插件。开发者可选择使用普通静态声明，或者使用推荐的基于

静态声明

优化的

静态懒加载

方式。

普通静态声明

●

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

○

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

■

version：指定插件版本号。

自动选择最新版本，版本以小程序详情页 >

开发

插件服务

插件管理

为准。

■

provider：指定所引用的插件 id（插件 id 可咨询插件提供方）。同一个插件 id 不能多次声明使用。

{

"plugins": {

"myplugin": {

"version": "*", // 自动选择最新版本

"provider": "2019235609092837"

//如需声明多个插件，重复添加自定义字段即可

"yourplugin": {

"version": "*", // 自动选择最新版本

"provider": "2019235609090000"

}

使用插件

版本兼容

使用插件的小程序项目需要

0.60

或以上版本的 ide 才能编译构建。

插件的运行要求小程序基础库为

1.22.4

及以上版本，支付宝客户端 10.1.85 及以上的版本，小程序在使用插件的时候，需要按照如下方式兼容：

注意：

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

组件

可使用

基础组件

、

扩展组件

和

自定义组件

，插件的自定义组件和普通的自定义组件使用方法类似。在 json 文件中定义需要引用的插件自定义组件时，通过

plugin://

协议指明需要引用的插件自定义组件。

出于对插件的保护，默认情况下

ref

接口无法获得插件的自定义组件实例对象，可以通过给插件自定义组件定义 ref 定义段的方式

指定被 ref 引用时的返回值

来实现。

页面

跳转到插件页面时， url 使用

plugin://

前缀，格式为

plugin://plugin_name/plugin_page

，如下所示：

也可以使用 api 进行跳转：

js 接口

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

该示例先通过

requireplugin

引用插件 api，然后访问插件暴露的

xxx_api

函数以及

world

变量。

懒加载模式

静态懒加载方式可提高小程序的首屏性能和接入开发体验。开启静态懒加载的方式只需要在现有静态声明基础上，新增

lazy

标识即可。同时提供

预加载

功能，可以通过配置 preloadrule 灵活控制页面进行插件包预加载，即提前下载后续页面所需的插件包，提升后续页面打开性能。

●

lazyplugin：插件引用名，无需和插件开发者的命名保持一致。在后续的插件使用中，该引用名将被用于表示该插件。

○

lazy：声明插件运行模式，默认为非懒加载（false）。

●

preloadrule：开发者可以通过配置 preloadrule，在进入小程序某个页面时，由框架自动下载可能需要的插件，以提升实际使用插件时的性能。

使用插件

版本兼容

使用懒加载模式的小程序项目支持 ide 3.0.0 及以上版本编译构建。懒加载模式插件的运行小程序支持基础库 2.7.18 及以上版本，如不符合建议请

设置最低基础库版本进行兼容

。

组件

懒加载模式会在实际渲染到插件组件时，自动去触发插件加载，所以在未下载或注入之前，插件组件处于不可用的状态，通过为插件的自定义组件设置

占位组件

，可以先渲染占位组件作为替代，在插件下载完成后再进行替换。

页面

跳转到插件页面时， url 使用

plugin://

前缀，格式为

plugin://plugin_name/plugin_page

，如下所示：

也可以使用 api 进行跳转：

js 接口

引用懒加载模式的插件提供的 js 接口时，为了不让下载插件的操作阻塞代码运行，需要异步获取 js 导出的内容

导出到插件

从基础库

2.7.7

起，宿主小程序可以导出一些内容，供插件获取。具体来说，即在声明使用插件时，可以通过

export

字段来指定一个文件，如：

则该文件导出的内容可以被插件用全局函数

requireminiprogram

获得。例如，在以上示例文件中，宿主小程序做了以下导出：

那么插件就可以获得上面导出的内容：

具体导出内容，可以阅读

插件开发

文档，和插件的开发者做好约定。

注意：

●

使用的多个插件的导出互不影响，两个插件可以导出同一个文件，也可以是不同的文件。但导出同一个文件时，如果一个插件对导出内容做了修改，那么另一个插件也会被影响。

●

请谨慎导出 my 对象或某个具体的 api，这将使插件可以以宿主小程序的身份调用 api。

●

导出到插件功能仅在静态声明插件的情况下使用，无法在动态加载插件的情况下使用。

为插件提供自定义组件

有时，插件可能会在页面或者自定义组件中，将一部分区域交给使用的宿主小程序来渲染，因此需要使用的宿主小程序提供一个自定义组件。但由于插件中不能直接指定宿主小程序的自定义组件路径，因此需要通过为插件指定

抽象节点

的方式来提供。

如果是插件的自定义组件需要指定抽象节点实现，可以在引用时指定：

从基础库

2.8.9

、

ide 3.7.1

起，可以通过 app.json 的配置项为插件页面指定抽象组件实现。例如，要给插件名为

plugin-index

的页面中的抽象节点

mp-view

指定宿主小程序的自定义组件

/components/comp-from-miniprogram

作为实现的话：

另外也可以参考

插件开发的相关文档

。

动态加载

除了静态声明的方式，支付宝还提供了动态加载插件的方式，不用在 app.json 中提前声明插件依赖，而是使用 my.loadplugin 动态加载插件，这样小程序不用在启动阶段就下载插件包，而是等到实际使用时，再下载插件包。

基于静态声明的懒加载模式

可以做到同样的效果，并且使用更加直观简单，更推荐使用！

动态加载插件使用声明

使用动态加载插件前，需要在 app.json 中做以下声明

注意：

只有添加以上声明，才可以使用动态加载插件的方式。此时 js 代码 my.caniuse('plugin.dynamic') 会返回 true。

使用插件

版本兼容

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

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

使用 my.loadplugin 动态加载插件

在使用插件的组件、页面或 api 之前，需要使用 my.loadplugin 动态加载插件。

自定义组件

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

属性

属性名	类型	描述
is	string	要渲染的插件组件。需要使用 dynamic-plugin: 前缀

注意:

●

需要使用 dynamic-plugin: 指定要渲染的插件组件，格式为 dynamic-plugin:/plugin_id/plugin_component。plugin_component 为插件 plugin.json 中对外暴露的组件。

●

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

●

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

●

默认情况下

ref

接口无法获得插件的自定义组件实例对象，可以通过给插件自定义组件定义 ref 定义段的方式

指定被 ref 引用时的返回值

。

示例代码

页面

跳转到插件页面，需要使用 dynamic-plugin: 前缀。格式为 dynamic-plugin:/plugin_id/plugin_page，其中 plugin_page 为插件 plugin.json 中暴露的页面。

也可以使用 api 进行跳转

注意：

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

js 接口

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

导出到插件

动态插件不支持此功能，建议使用

基于静态声明的懒加载模式

。

相关问题