---
title: 插件声明及使用
summary: "介绍小程序插件机制的声明和使用方法，支持通过 requirePlugin 引入 echarts、three.js 等官方插件模块。"
questions:
  - 涂鸦小程序插件机制解决了什么问题？
  - 如何在 app.json 中声明需要使用的插件？
  - requirePlugin 函数支持哪些导入形式？
  - 使用插件功能的基础库和开发者工具版本要求分别是什么？
  - 官方提供的 echarts、three.js 和 @antv/f2 插件分别用于什么场景？
  - 如果 usingPlugins 未声明对应插件，调用 requirePlugin 会有什么结果？
  - 插件模块使用 export default 导出时，如何正确获取模块对象？
  - 在 Ray 开发模式中如何声明和使用插件？
  - 插件的路径格式 rjs:// 前缀代表什么含义？
---

# 简介

由于执行环境的因素，[Render Script](../api/render) 无法直接使用三方图表库、3D 库等功能模块，推出插件机制。由官方提供适配支持。

通过插件的形式提供一些开发常用图表库模块，声明插件配置后，可通过 `requirePlugin` 方法引入对应插件模块。

环境要求：

- 基础库版本 `>= 2.18.0`
- 开发者工具 `>= 0.6.3` [Download](../../../../devtools/tools/download)

## 声明插件

在 `app.json` 文件中通过 `usingPlugins` 字段声明插件名称，具体名称由官方提供，具体请查看以下列表。

例如：

```json
{
  "usingPlugins": ["rjs://echarts"]
}
```

## 使用插件

可通过全局函数 `requirePlugin` 引入插件导出的模块，支持单个导入和多个导入形式。

```ts
// 单一插件模块导入
type requirePlugin = (plugin: string) => Promise<Module>

// 多个插件模块导入
type requirePlugin = (plugins: string[]) => Promise<Module[]>
```

例如：

```js
// pages/index/index.rjs
export default Render({
    async init() {
        const echarts = await requirePlugin('rjs://echarts');
    }
})
```

```js
// pages/index/index.rjs
export default Render({
    async init() {
        const [echarts, charts] = await requirePlugin(['rjs://echarts/core', 'rjs://echarts/charts']);
        const { BarChart } = charts;
    }
})
```

如 usingPlugins 未声明对应插件，则会报错。

```js
// pages/index/index.rjs
export default Render({
    async init() {
        const echarts = await requirePlugin('rjs://echarts/core').catch((err) => {
          console.log(err); // The plugin rjs://echarts/core is not in usingPlugins.
        });
    }
})
```

## 官方插件列表

由官方提供的插件模块，可通过 `requirePlugin` 方法引入。不在列表中的插件模块，如有需求，可移步论坛提交说明。

**可使用的插件模块有：**

### [echarts](https://echarts.apache.org/zh/index.html) 插件

用于在 Render _\*.rjs_ 中绘制 echarts 图表。

使用前请安装对应 npm 包：

```bash
npm install echarts
```

**插件路径格式**

- `rjs://echarts` 等同于模块 `import * as echarts from 'echarts'`
- `rjs://echarts/core` 等同于模块 `import * as echarts from 'echarts/core';`
- `rjs://echarts/charts` 等同于模块 `import { BarChart } from 'echarts/charts';`

> 依次类推，可引入 `echarts` 的所有文件模块。

### [three.js](https://threejs.org/) 插件

用于在 Render _\*.rjs_ 中绘制 three.js 3D 图形。

使用前请安装对应 npm 包：

```bash
npm install three
```

**插件路径格式**

- `rjs://three` 等同于模块 `import * as THREE from 'three';`
- `rjs://three/addons/loaders/GLTFLoader` 等同于模块 `import { GLTFLoader } from 'three/addons/loaders/GLTFLoader';`

> 依次类推，可引入 `three.js` 的所有文件模块。

### [@antv/f2](https://f2.antv.antgroup.com/) 插件

用于在 Render _\*.rjs_ 中绘制 F2 图表。

使用前请安装对应 npm 包：

```bash
npm install @antv/f2
```

**插件路径格式**

- `rjs://@antv/f2` 等同于模块 `import F2 from '@antv/f2';`

> 依次类推，可引入 `@antv/f2` 的所有文件模块。

## DEMO 演示

- [rjs-plugin](https://github.com/Tuya-Community/tuya-miniapp-demo/tree/rjs-plugin) 原生小程序开发示例项目
- [ray-rjs-plugin](https://github.com/Tuya-Community/tuya-miniapp-demo/tree/master/rayRjsPlugin) Ray 开发示例项目

## 注意事项

### 模块的导出

插件模块返回的对象由具体的文件写法决定，请开发者自行鉴别。

模块写法

```js
export default {}
```

对应导出，需要使用 `module.default` 获取模块对象。

```js
const module = await requirePlugin('rjs://module');

module.default;
```

### 在 Ray 开发里使用插件

推荐使用原生小程序语法编写[组件](../component/intro)后，在 Ray 开发模式中通过混合开发的方式引入自定义组件，详见[混合开发](../../../ray/framework/mixed-development)。

其中对于 `usingPlugins` 的声明，对应在 `src/global.config.js` 中配置。详见[应用配置](../../../ray/framework/app)。

```js
export const tuya = {
  // other config
  usingPlugins: ['rjs://echarts']
}
```