一.静态函数定义示例
@FunctionClass
public class UdcBasicFunction {
@Function(category = FormulaFunctionCategoryEnum.Constants.TEXT, displayName = ENDSWITH_DISPLAYNAME,
description = ENDSWITH_DESCRIPTION , sort = 3)
@Parameters(value = {@Parameter(displayName = ENDSWITH_PARAM0_DISPLAYNAME, description = ENDSWITH_PARAM0_DESCRIPTION) ,
@Parameter(displayName = ENDSWITH_PARAM1_DISPLAYNAME, description = ENDSWITH_PARAM1_DESCRIPTION)})
@ReturnValue(dataType = FormulaDataTypeEnum.Constants.BOOLEAN, description = ENDSWITH_RESULT_DESCRIPTION)
public static Boolean endsWith(String str, String suffix) {
return StringUtils.endsWith(str, suffix);
}
}
二、注解含义
| @FunctionClass | 表示一个自定义函数类，添加此注解的 class会被扫描和注册到表达引擎 | ||
|---|---|---|---|
| @Function | 表示一个自定义函数，被该注解标记的静态方法，将会注册到引擎，并可以在组件的函数列表被使用。注意：一定是静态方法 | ||
| category | 函数分类，如果需要将自定义函数加入到预制函数分类，请使FormulaFunctionCategoryEnum.Constants提供的分类常量，常量说明见下文中的函数分类列表 | ||
| displayName | 函数的显示名称： 比如描述一个函数名称 为"以文本结尾" | ||
| description | 描述函数的用法，比如：判断文本是否以指定字符结尾，是则返回true,否则返回false | ||
| terminalSupport | 函数支持的终端：ALL 前端后都支持的函数需要同时实现前端函数和后端函数 FRONTEND 仅前端函数支持，需要实现前端函数，后端仅定义函数即可BACKEND 仅后端函数支持，需要后端定义并实现函数，前端无需实现也无法执行`` |
||
| sort | 函数在表达式组件中分类下的排序，按从小到大的顺序 | ||
| @Parameters | 标注在静态方法上，描述自定义函数的入参，注解其value为一个数组属性，数组的数量和顺序一定要保持和静态方法的实际参数个数、顺序一致 | ||
| value | 参数数组 | ||
| @Parameter | 单个参数定义注解 | ||
| displayName | 参数名称，国际化规范见下文 | ||
| description | 参数描述 | ||
| @ReturnValue | 标注在静态方法上，对返回值进行描述 | ||
| dataType | 返回值的数据类型， 使用FormulaDataTypeEnum.Constants下的常量 | ||
| description | 返回值描述，国际化规范见下文 |
三、V8平台数据类型和java数据类型映射
在V8的体系中，函数定义、校验（见: 《表达式自定义函数自定义语法校验规则》） 以及字段的数据类型元数据描述都是使用： com.seeyon.boot.enums.DataType 这个枚举类。其枚举类型和java的数据类型有如下映射关系
| V8数据类型 | V8数据类型描述 | java数据类型 |
|---|---|---|
| ATTACHMENT | 附件 | java.lang.String |
| BIGINTEGER | 长整数 | java.lang.Long |
| BOOLEAN | 布尔 | java.lang.Boolean |
| CTPENUM | 单选枚举(注意仅单选，多选对应String类型) | java.lang.Long |
| CURRENCY | 货币 | java.math.BigDecimal |
| DATE | 日期 | java.util.Date |
| DATETIME | 日期时间 | java.util.Date |
| DECIMAL | 小数 | java.math.BigDecimal |
| ENTITY | 单选实体(注意仅单选，多选对应String类型) | java.lang.Long |
| INTEGER | 整数 | java.lang.Integer |
| MULTILINESTRING | 多行文本 | java.lang.String |
| STRING | 文本 | java.lang.String |
| TIME | 时间 | java.lang.String |
| OBJECT | 对象 | java.lang.Object |
四、国际化规范
1.函数分类国际化规范
在定义函数的注解@Function中 ， category属性用来描述函数的分类， 该属性是一个整数code , 所以需要自定义国际化词条。目前预置的函数分类提供了以下几种:
| 分类编码 | 分类名称 |
|---|---|
| 0 | 基础函数 |
| 1 | 系统函数(目前仅用于系统变量，函数列表中无法选择) |
| 2 | 日期函数 |
| 3 | 数学函数 |
| 4 | 文本函数 |
| 6 | 条件函数 |
| 8 | 聚合函数 |
| 9 | 变化函数 |
| 10 | 枚举函数 |
但是以编码可能不满用户自定义的函数分类，所以可以单独指定一个整数编码，并提取为自定义的常量(建议自定编码从100开始，避免和预制函数分类编码冲突)。同时需要在项目的 resources/i18n 目录下， 增加国际化词条， 规则如下： formula.function.category. + 自定义的函数分类编码。
formula.function.category.100=自定义函数分类
2.函数参数、返回值描述国际化规范
函数入参和返回值的国际化规范适用于 **@Function.displayName 、@Function. description、 @Parameter.displayName 、@Parameter.description、@ReturnValue.description **
比如, 静态函数定义示例中的以上属性可以抽取为国际化词条:
formula.function.endsWith.displayName=以指定文本结尾
formula.function.endsWith.description=判断一个文本是否已指定文本结果
formula.function.endsWith.param0.displayName=当前文本
formula.function.endsWith.param0.description=需要判断的文本
formula.function.endsWith.param1.displayName=结尾文本
formula.function.endsWith.param1.description=是否已该文本结尾
formula.function.endsWith.result.description=如果结尾文本结尾，则返回truy，否则返回false
词条同样需要放到 **resources/i18n 目录下 , **如果不定义国际化词条，也可以直接在注解中定义上述属性的值，表达式引擎会直接将该属性的值不经过国际化处理显示到页面。
3.函数用法描述
函数用法的定义主要是针对如图所示的场景，用于描述函数的一个具体使用案例
定义用法如下：
在手写工程的resources根目录下添加一个名为: formula-functions.xml 的文件
xml文件内容示例:
注意函数用法并没有做国际化处理，指定定义一套语言环境下的用法描述。后续版本会根据 formula-functions_en.xml 、formula-functions_zh_CN.xml 等文件后缀的方式区分国际化内容。
| 配置名称 | 含义 |
|---|---|
<function></function> |
定义一个函数用法示例 |
<name>myFunction </name> |
对应静态函数的方法名，注意不能重复 |
<args></args> |
多个参数，没有参数可以不定义 |
<arg></arg> |
定义单个参数的具体含义 |
<tips></tips> |
整个函数在示例中的含义 |
<functions>
<!-- 函数示例配置 -->
<function>
<name>round</name>
<args>
<arg>3.14159</arg>
<arg>3</arg>
</args>
<tips>返回3.142</tips>
<link>可以忽略</link>
</function>
<functions>