---
navTitle: 扩展开发
indexTitle: 概述
---
# 扩展开发介绍

扩展是一种插件，安装一个扩展可以提供 SuccApp 默认不具备的功能，可以改变产品的默认功能和行为。

扩展的开发是面向开发者的，需要开发者具备基础的 Web 开发技能，详见[开始前先判断](../README.md#before-you-start)。本章节介绍如何开发 SuccApp 扩展，包括新建扩展、开发、调试、运行等，包括以下内容：

- [扩展开发介绍](#扩展开发介绍)
  - [扩展的原理](#expansion-principle)
  - [扩展点](#extension-point)
  - [开发环境准备](#preparation)
  - [创建新的扩展](#new-extension)
  - [开发语言](#language)
  - [运行和调试扩展](#debug-extensions)
  - [发布扩展](#publish-extension)
  - [代码规范](#code-specification)
    - [引用产品提供的前端API](#front-end-api)
    - [引用扩展内的ts文件](#refer-ts-extension)
    - [引用第三方开源js文件](#refer-ts-third)
    - [支持国际化](#i18n)

## 扩展的原理{#expansion-principle}

SuccApp 是 B/S 架构的系统，支持扩展前端和后端的逻辑。当需要开发扩展时，需要先了解系统提供了哪些[扩展点](./extension-points/README.md)，只有通过系统提供的[扩展点](./extension-points/README.md)才能扩展希望的个性化逻辑，扩展点有前端和后端之分。

扩展开发有前端和后端之分，开始前先根据运行位置和影响范围判断扩展类型，详见[开始前先判断](../README.md#before-you-start)。

## 扩展点{#extension-point}

扩展点是系统提供的允许第三方开发者进行“扩展的的切入点”，详细信息参考[这里](./extension-points/README.md)。

支持的扩展点：

!!! children (./extension-points) !!!

## 开发环境准备{#preparation}

1. 扩展的开发需要用到 SuccApp for VS Code 或 SuccApp CLI，参见 [AI 低代码开发](../ai-building/README.md)。
2. 扩展的调试运行需要 SuccApp 产品环境，需要[下载](../../whatsnew/README.md)并启动 SuccApp（可以用已有的环境，但不要是生产环境）。

## 创建新的扩展{#new-extension}

创建新的扩展前，需要了解 SuccApp 提供了哪些[扩展点](./extension-points/README.md)，并根据具体需求选择要扩展的扩展点，一个扩展可以实现多个扩展点。SuccApp 提供了不同类型的扩展模板，模板包含必要的配置、目录结构和文件内容，基于模板可以加快扩展开发。

TODO 补充一个截图。

## 开发语言{#language}

扩展开发支持 JavaScript 或 TypeScript。前后端运行位置和影响范围的判断见[开始前先判断](../README.md#before-you-start)。

## 运行和调试扩展{#debug-extensions}

连接测试服务器进行调试（前端代码使用浏览器调试功能调试，后端使用日志调试）和测试

## 发布扩展{#publish-extension}

如果要分享给其他人使用，可发布到[产品社区](https://bbs.succbi.com/)中，审批通过后即可查看使用。

## 代码规范{#code-specification}

在开发一个扩展的时候，如果使用到了脚本，那么需要遵循一些规则，才能够让扩展最终在平台中正确运行。

### 引用产品提供的前端API{#front-end-api}

产品提供了一些api，这些api是产品提供的对外接口，在开发扩展脚本的过程中可以直接进行调用。

```ts
import { assign } from 'sys/sys';
```

### 引用扩展内的ts文件{#refer-ts-extension}

扩展内部可能会有多个脚本互相调用，假设扩展内部存在如下的两个脚本：

- main.ts
- impl
  - template.ts

在`main.ts`中引用`template.ts`的方式是这样的，

```ts
import {Template} from './impl/template'
```

始终应该通过相对路径进行引用。

### 引用第三方开源js文件{#refer-ts-third}

在通过typescript或者javascript es6 编写代码的时候，会引用一些第三方的开源js/ts文件。

1. 第三方ts文件，无需做特殊处理，和扩展开发者自己写的的ts文件可以等同看待。
2. 第三方js文件，如jquery，与我们编写扩展的要求不同，这些文件一般是es5编写的，不能使用一般的处理方式，这里重点进行介绍。其进行引用的方式有如下两种。

**直接在扩展中加入第三方js文件：**

如果是通过模板创建的扩展，在扩展下一般都有lib目录，在扩展开发环境中的目录结构如下：

![lib](./images/lib.png)

第三方的js文件应该都放在这个lib文件夹下。同时约定，在一个扩展下的任何地方建立的lib文件夹，均会被识别为第三方库。在扩展开发环境中，lib目录下的文件不会被编译，因此请确保添加的第三方文件是已经编译为能在浏览器中直接运行的版本。一般不建议定义额外的lib文件夹。

在扩展代码中引用第三方文件的时候，有两种情况，一种情况是第三方文件是按照模块组织的，另一种情况是文件未按照模块进行组织，对于没有按照模块组织的，如在lib目录下添加了`jquery-3.1.1.js`，它定义了全局变量而不是模块，在扩展主脚本main.ts中请这样进行引用：

```ts
import "./lib/jquery-3.1.1";
declare var $: any;
```

这样声明以后就可以在代码中使用jquery的`$`对象了。为了在ts代码中直接使用js对象而不报编译错误，需要进行`declare var $: any`这样的声明。需要注意的是，这里declare的的变量名必须与第三方文件提供的全局变量的名称保持一致，在这里的例子就是`$`。

对于按照模块组织的库，如有一个demo模块`demo.js`，在扩展主脚本main.ts中请这样进行引用：

```ts
import demo from "./lib/demo";
```

这样引用的demo的类型也是any，使用者可以自行查阅api使用它导出的内容。

**引用平台提供的第三方js文件：**

在平台中已经集成了一些常用点第三方文件，它们包括这些：

- `jquery`
- `TODO` 补充一些

这些第三方文件比如jquery在平台中均做了处理，不需要自己去再将文件放在lib目录下就可以使用，同时直接通过我们上面列出的名称就可以进行引用，不需要额外的路径或者版本后缀，如引用jquery可以像这样写：

```ts
import "jquery";
declare var $: any;
```

除了这里import的方式之外，对于不同js文件的使用要求同[直接加入第三方js库](#直接在扩展中加入第三方js文件)一致。

### 支持国际化{#i18n}

在实现扩展的时候，有时会提供一些在界面上显示的ui组件，这些组件在显示给用户时需要考虑国际化。

在扩展中实现国际化有下面几点需要注意：

- 扩展文件的存储。
  - 扩展的国际化信息直接存储在每一个扩展的`package.json`的属性`i18n`中。
- 扩展文件内容格式。
  - 国际化目前仅支持中文和英文两种，分别为`zh_CN`,代表中文环境的国际化和`en`代表英文环境。其中国际化的每个条目需要以当前的扩展的扩展名开头。
- 在代码中获取国际化信息。
  - 在扩展中实现国际化，需要使用系统提供的`sys`模块的`message`函数，该模块的定义文件`sys.d.ts`可以在扩展开发环境下的`/api/sys`文件夹下找到，在扩展代码中可以按照上文中的[引用平台提供的前端API](#引用平台提供的前端API)直接使用。

例子1：假如想要给登录页面扩展增加一条版权信息的国际化，可以采取下面的方式。

首先在pacakge.json中增加如下的的信息：

```json
{
    "i18n": {
    "zh_CN": {
    "succ-loginPage-default.copyright": "版权",
    },
    "en": {
        "succ-loginPage-default.copyright": "copyright"
    }
    }
}
```

然后在代码中这样调用，在中文环境获取到的就是上面设置的`版权`,而在英文环境调用获取到的就是`copyright`：

```ts
message("succ-loginPage-default.copyright");
```

例子2: 假如想要设置带参数的中文国际化信息，如`正在加载，资源a、资源b`这样的信息显示给用户的时候。可以这样实现。

1. 首先在pacakge.json中增加如下的的信息。

```json
  {
  	"i18n": {
    "zh_CN": {
      "succ-portalTemplate-pagedark.load.resources": "正在加载，资源{0}、资源{1}",
    }
  	}
  }
```

2. 然后在代码中这样调用，在中文环境获取到的就是将参数设置好的`正在加载，资源a、资源b`。

```ts
message("succ-portalTemplate-pagedark.load.resources", "a", "b");
```

更详细的`message`函数的使用请参考扩展开发环境中`sys.d.ts`的接口文档.