---
order: 3
navTitle: package.json
---
# package.json

`package.json`文件包含两部分信息：

- 扩展的基本信息，包含扩展名称、描述文字、作者、组件的npm依赖等。npm配置参考[npm package.json](https://docs.npmjs.com/cli/v6/configuring-npm/package-json)。
- 组件扩展点的配置，包括组件的类名、分组、模板等。

组件扩展点中包含[通用扩展点配置](../../references/extension-contributor.md)的所有属性，并额外增加了下面的属性，可以配置一个或若干个表达式函数的信息。

```json
{
	"contributes": {
		"expressionFunction": [{
			"name": "<function name>",
            "description": "<函数的简短描述>",
			"manURL": "<帮助文档，指向一个当前扩展目录下的md文件，如`GENDER.md`>",
			"group": "<函数在函数列表中所在的分组，如string, math, others...>"
			"arguments": [{
				"name": "<参数名>",
				"desc": "<参数描述>",
				"type": "<参数类型，如C, N...>",
				"optional": <参数是否可选>,
				"repeatable": <参数是否可重复>
			}],
			"argumentsCount": <参数个数>,
			"returnType" : "<返回类型，如C, N...>",
			"returnArgType": <以第几个参数作为返回值类型，0开始>,
			"expTemplate": "<表达式模板>",
			"sqlTemplate": [{
				"MySQL":"<在特定数据库使用的对应的SQL模板>"
			}],
			"jsScript": "<指定一个相对于当前扩展目录的前端脚本文件>",
			"serverScript": "<指定一个相对于当前扩展目录的后端脚本文件>",
			"scriptFunc": "<指定表达式在前端浏览器和后端运算时使用的脚本函数的函数名>",
			"checkArgsFunc": "<指定一个js函数，用于检查函数参数的正确性>",
			"renderSQLFunc": "<用于将表达式函数转换为可以执行的SQL表达式>",
			"javaClass": "<指定一个java的实现类>"
		},
		{
			...
		}]
	}
}
```

## 表达式函数扩展点配置选项{#expressionfunction}

下面是`expressionFunction`扩展点的配置选项。

### name

函数名，通常大写，用于唯一标识一个函数，不能和其他扩展函数或系统函数重名。

### description

函数的一句话简短描述，用于在表达式编辑器的函数列表中简要的提示函数的功能，如：`SM3加密函数`。

### manURL

帮助文档，指向一个当前扩展目录下的md文件，如`FUNC1.md`，用于在表达式编辑器的函数列表中现实函数的帮助信息，md文件的章节必须符合下面示例的规范（以函数名为`FUNC1`为示例）：

```markdown
# **<FUNC1>**

<函数的一段简短的描述，用于快速了解函数的功能>

## 语法

<函数的一个简单的语法表述如`FUNC1(**str**, **start_index**, [**num**])`。>

<下面介绍参数列表：>

* **param1**：参数1的说明
* **param2**：参数2的说明

## 示例

<此处列出一些使用示例>

1. `FUNC1(...)` 示例1说明...
2. `FUNC1(...)` 示例2说明...
3. ...
```

### group

函数所在分组，用于在表达式编辑器的函数列表中把函数显示在合适的分组中，已有的分组包括：

1. analysis - 分析函数
2. aggregate - 聚集函数
3. string - 字符串函数
4. math - 数学函数
5. date - 日期函数
6. logic - 逻辑函数
7. transform - 转换函数
8. others - 其他函数

如有需要可输入任意分组。

### arguments

函数的参数列表，表示函数可以接受哪些参数，如果没有此定义，那么函数可以接受任意参数，参数列表是一个json数组，可以定义如下属性：

1. name 参数名
2. description 参数描述
3. type 参数的类型，可选项类似[returnType](#returntype)。
4. optional 为true表示参数是可选参数，如`find('test','es',1)`，第三个参数就可以不传，`find('test','es')`，表示从0开始查找。
5. repeatable 为true表示参数可以重复，如`caoncat`函数，其参数可以重复输入多个，如`caoncat('a')`、`caoncat('a','b','c')`、`caoncat('a','b')`……。

### argumentsCount

函数的参数个数，-1表示是不限个数但至少有一个，0表示无参数。不定义时根据[arguments](#arguments)中的信息自动判断参数个数。

### returnType

函数的返回值类型。函数的返回类型可以通过此属性明确定义，也可以来自某个参数的类型，见[returnArgType](#returnargtype)，也可以是动态判断的，见[checkArgsFunc](#checkargsfunc)。

如果要明确指定，那么可以配置此参数为下列值之一：

1. 'C' - 字符型
2. 'N' - 浮点型
3. 'I' - 整形
4. 'D' - 日期型
5. 'L' - 布尔型
6. 'R' - 数组
7. '\*' - 变体，匹配任意类型

### returnArgType

函数的返回值类型与某个参数的类型一致。只有当[returnType](#returntype)没有定义时，此参数才有效。

将此属性设置为对应参数在参数列表中的序号，从0开始。

### expTemplate

表示使用系统其他标准的函数来组装这个自定义函数。系统虽然提供了很多函数，在某些特定场景下也可以满足需要，但是写法可能不是那么业务化，此时可以利用系统已有的函数定义一些比较常用的、业务化的、场景化的函数，方便用户使用。

如果能使用函数组合完成扩展函数需求，那么可以直接配置`expTemplate`，这样就不需要做其他的函数脚本开发了，系统会自动适配各种运行环境。

示例：

1. 从文本中解析身份证号码，参数是S，函数模版：
   ```
   REGEXP_EXTRACT(S,'([1-9]\\d{5}(18|19|([23]\\d))\\d{2}((0[1-9])|(10|11|12))(([0-2][1-9])|10|20|30|31)\\d{3}[0-9Xx])|[1-9]\\d{5}\\d{2}((0[1-9])|(10|11|12))(([0-2][1-9])|10|20|30|31)\\d{2}')
   ```
2. 从文本中解析电话号码，参数是S，函数模版：
   ```
   REGEXP_EXTRACT(S,'(0\\d{2}-\\d{8}(-\\d{1,4})?)|(0\\d{3}-\\d{7,8}(-\\d{1,4})?)|((13[0-9])|(14[5|7])|(15([0-3]|[5-9]))|(1[7-8][0,5-9]))\\d{8}')
   ```
3. 15位身份证号码升级为18位，参数是P，函数模版：
   ```
   IF(LEN(P)=15,CONCAT(MID(P,0,6),'19',MID(P,6,9),MID('10X98765432',((MID(P,0,1)*7+MID(P,1,1)*9+MID(P,2,1)*10+MID(P,3,1)*5+MID(P,4,1)*8+MID(P,5,1)*4+1*2+9*1+MID(P,6,1)*6+MID(P,7,1)*3+MID(P,8,1)*7+MID(P,9,1)*9+MID(P,10,1)*10+MID(P,11,1)*5+MID(P,12,1)*8+MID(P,13,1)*4+MID(P,14,1)*2)%11),1)),P)
   ```

说明：

1. 模版中可以通过引用[arguments](#arguments)中定义的参数的`name`来引用函数的参数。

### sqlTemplate

定义此函数"翻译"为数据库查询语言时使用的模版。

如果函数需要转换到SQL查询语言中在数据库中执行，那么需要配置此参数。此属性是一个JSON对象，key是数据库扩展的名字，见[数据库连接器扩展](../dbConnector/package-json.md#name)，如`MySQL`, `Oracle`, `OceanBase`, `OpenGauss`...。SQL模版的格式类似数据库连接器扩展中函数模版的格式，见[数据库扩展点配置选项](../dbConnector/capabilities-json.md#functiontemplates)。

说明：

1. 由于不同的数据库执行的SQL会有不同，所以需要针对不同的连接器分别定义，可以考虑按需定义。
2. 如果自定义函数不需要在DB中执行，那么不需要定义此属性。
3. 如果是通过[expTemplate](#exptemplate)配置的函数，那么不需要定义此属性，系统会自动根据模版引用的系统函数翻译SQL。

### jsScript

指定一个相对于当前扩展目录的前端脚本文件，用于提供[scriptFunc](#scriptfunc)指定的脚本函数。见[脚本开发](./script.md#frondend-script)。

默认`main.js`。

### serverScript

指定一个相对于当前扩展目录的后端脚本文件，用于提供[scriptFunc](#scriptfunc)指定的脚本函数。见[脚本开发](./script.md#backend-script)。

默认`main.action`。

### scriptFunc

指定表达式在前端浏览器和后端运算时使用的脚本函数的函数名。见[脚本开发](./script.md#frondend-script)。

### checkArgsFunc

指定一个js函数，用于检查函数参数的正确性。见[脚本开发](./script.md#frondend-script)。

### renderSQLFunc

指定一个js函数，用于将表达式函数转换为可以执行的SQL表达式。见[脚本开发](./script.md#frondend-script)。

### javaClass

指定一个java实现类。脚本在后端运行时，除了使用脚本开发，也可以选择使用java开发，脚本和java只需要选择一种。提供的java类需要实现`com.succez.commons.exp.ExtExpressionFuncContributor`接口。