工具函数

导入

通过如下方式导入工具函数api

import util from "svr-api/utils";

方法

/**
 * 工具函数
 */

import { File } from "./fs";

/**
 * 进行md5算法加密，不可逆
 * 
 * @param obj 待加密对象，支持String|File|Blob|InputStream等类型，注意：内部会自动关闭流，使用者无须再做处理
 * @returns 返回16进制的字符串
 */
export function md5(obj: any): string;

/**
 * 进行sha1算法加密，不可逆
 * 
 * @param obj 待加密对象，支持String|File|Blob|InputStream等类型，注意：内部会自动关闭流，使用者无须再做处理
 * @returns 返回16进制的字符串
 */
export function sha1(obj: any): string;

/**
 * 进行sha256算法加密，不可逆
 * 
 * @param obj 待加密对象，支持String|File|Blob|InputStream等类型，注意：内部会自动关闭流，使用者无须再做处理
 * @returns 返回16进制的字符串
 */
export function sha256(obj: any): string;

/**
 * 生成一段随机字符串，字符串有字幕和数字构成。
 * 
 * @param len 指定随机字符串长度，默认8
 */
export function randomString(len?: number): string;

/**
 * 生成一段纯数字的随机字符串。
 * 
 * @param len 指定随机字符串长度，默认8
 */
export function randomNumberString(len?: number): string;

/**
 * 生成一段uuid，生成一段uuid，为base64编码，仅含有数字和字母的字符串
 */
export function uuid(): string;

/**
 * 获取汉字的拼音。
 * 
 * @param str 汉字字符串
 * @param initial 是否只返回首字母，默认为true
 * @returns 返回拼音，首字母大写，其它字母小写
 */
export function pinyin(str: string, initial?: boolean): string;

/**
 * 确保字符串str以字符串suffix结尾，返回处理之后的字符串。
 * 
 * @example
 *  appendIfMissing(null, null) = null
 *  appendIfMissing("abc", null) = "abc"
 *  appendIfMissing("", "xyz") = "xyz"
 *  appendIfMissing("abcxyz", "xyz") = "abcxyz"
 *  appendIfMissing("abcXYZ", "xyz") = "abcXYZxyz"
 *  appendIfMissing("abc", "xyz", false, "mno") = "abcxyz"
 *  appendIfMissing("abcxyz", "xyz", true, "mno") = "abcxyz"
 *  appendIfMissing("abcmno", "xyz", true, "mno") = "abcmno"
 *  appendIfMissing("abcXYZ", "xyz", true, "mno") = "abcXYZxyz"
 * 
 * @param str 用于验证的字符串
 * @param suffix 匹配结尾的字符串
 * @param ignoreCase [可选] 是否忽略大小写，默认大小写敏感。
 * @param suffixes [可选] 当str不以其中任意一个结尾时，确保以suffix结尾。
 */
export function appendIfMissing(str: string, suffix: string, ignoreCase?: boolean, ...suffixes: string[]): string;

/**
 * 确保字符串str以字符串prefix开头或者以params中任意一个字符串开头，返回处理之后的字符串
 * @example
 *  prependIfMissing(null, null) = null
 *  prependIfMissing("abc", null) = "abc"
 *  prependIfMissing("", "xyz") = "xyz"
 *  prependIfMissing("abc", "xyz") = "xyzabc"
 *  prependIfMissing("abcxyz", "xyz") = "xyzabcxyz"
 *  prependIfMissing("ABCxyz", "abc") = "abcABCxyz"
 *  prependIfMissing("abc", "xyz", "") = "abc"
 *  prependIfMissing("xyzmno", "xyz", true, "mno") = "xyzmno"
 *  prependIfMissing("XYZmno", "xyz", true, "mno") = "xyzXYZmno"
 * 说明：若字符串str既不以prefix开头，也不以params中的任一项开头，优先确保字符串str以字符串prefix开头
 * @param str 用于验证的字符串
 * @param prefix 匹配开头的字符串
 * @param ignoreCase [可选] 是否忽略大小写，默认大小写敏感。
 * @param prefixes [可选] 匹配开头的字符串
 */
export function prependIfMissing(str: string, prefix: string, ignoreCase?: boolean, ...prefixes: any): string;

/**
 * 确保字符串str不以字符串prefix开头，返回处理之后的字符串
 * @example
 *  removeStart(null, null) = null
 *  removeStart("abc", null) = "abc"
 *  removeStart("", "xyz") = ""
 *  removeStart("xyz", "") = "xyz"
 *  removeStart("abcxyz", "abc") = "xyz"
 *  removeStart("ABCxyz", "abc") = "ABCxyz"
 * @param str 用于验证的字符串
 * @param prefix 匹配开头的字符串
 * @param ignoreCase [可选] 是否忽略大小写，默认大小写敏感。
 */
export function removeStart(str: string, prefix: string, ignoreCase?: boolean): string;

/**
 * 确保字符串str不以字符串suffix结尾，返回处理之后的字符串
 * @example
 *  removeEnd(null, null) = null
 *  removeEnd("abc", null) = "abc"
 *  removeEnd("", "xyz") = ""
 *  removeEnd("xyz", "") = "xyz"
 *  removeEnd("abcxyz", "xyz") = "abc"
 *  removeEnd("abcXYZ", "xyz") = "abcXYZ"
 * @param str 用于验证的字符串
 * @param suffix 匹配结尾的字符串
 * @param ignoreCase [可选] 是否忽略大小写，默认大小写敏感。
 */
export function removeEnd(str: string, suffix: string, ignoreCase?: boolean): string;

/**
 * 将传入的对象解析为boolean类型,若解析不成功，有def则返回def，没有则返回false
 * @example
 *  parseBoolean(null, true) = true
 *  parseBoolean("0", true) = false
 *  parseBoolean("1", true) = true
 *  parseBoolean("Y", true) = true
 *  parseBoolean("T", true) = true
 *  parseBoolean("yes", true) = true
 *  parseBoolean("N", true) = false
 *  parseBoolean("f", true) = false
 *  parseBoolean("no", true) = false
 *  parseBoolean("true", false) = true
 *  parseBoolean("false", true) = false
 *  parseBoolean("faLse", true) = false
 *  parseBoolean("on", false) = true
 *  parseBoolean("ON", false) = true
 *  parseBoolean("off", true) = false
 *  parseBoolean("oFf", true) = false
 *  parseBoolean("test", true) = true
 *  parseBoolean("test") = false
 * @param obj 需解析成boolean类型的对象,传入的对象不区分大小写
 * @param def 解析失败时的默认值
 */
export function parseBoolean(obj: any, def?: boolean): boolean;

/**
 * 解析xml内容，并返回xml文档对象。
 *
 * @param content xml内容，字符串或输入流
 * @param encoding 读取xml时的编码，传递null时将使用xml文件内声明的编码，没有声明编码将使用UTF-8
 * @param stripWhitespaceText 是否移除xml中的一些节点之间的空白文本，这些文本内容默认也是Node节点，默认false
 * 
 */
export function readXML(content: string | InputStream | File | Reader, encoding?: string, stripWhitespaceText?: boolean): Dom4j.Document;

/**
 * 将一个xml文档写入到指定的流中。
 *
 * @param doc 待写入的xml文档
 * @param target 目标文件或流，可传递文件对象、Writer、或输出流对象
 * @param encoding 默认将使用Document内声明的编码，没有声明编码将使用utf8。如果传递了明确的编码，但
 * 是编码和Document中声明的不一致，那么文件内容编码依然使用传递的编码，会和xml内容中声明的不一致。
 * @param pretty 是否格式化，默认false，传递true时默认使用tab缩进。
 * @param declaration 默认true，可以传递：
 *  1. true 输出默认的xml头，如：<?xml version=\"1.0\" encoding=\"UTF-8\"?>，其中的编码会替换为指定
 *     的编码。
 *  2. false 不输出xml头
 *  3. 其他字符串，输出指定的头
 */
export function writeXML(doc: Dom4j.Document, target: File | Writer, encoding?: string, pretty?: boolean, declaration?: any): void;

/**
 * 格式化XML，并返回格式化后的内容
 * 
 * @param xml 待格式化的xml，可以为string或Document
 * @return 返回格式化之后的xml字符串
 */
export function formatXML(xml: string | Dom4j.Document | File): string;

/**
 * 从指定的流或字节数组中读取字符串。
 *
 * 内部不会关闭流，调用者需要自行关闭。
 *
 * @param content 待读取的流或字节数组，支持传递
 *     `Reader|InputStream|byte[]|File|Blob|string`类型，`string`类型为文件路径，若文
 *     件不存在则抛出异常
 * @param encoding 文件内容编码，可选，默认编码`UTF-8`。
 */
export function readString(content: Reader | InputStream | number[] | File | Blob | string, encoding?: string): string;

/**
 * 将一个字符串写入到指定的流中。
 *
 * 内部不会关闭流，调用者需要自行关闭。
 *
 * @param str 待写入的字符串
 * @param target 目标流，支持传递`Writer|OutputStream|File|string`类型，`string`类
 *     型为文件路径，若文件不存在则自动创建
 * @param encoding 文件内容编码，可选，默认编码`UTF-8`
 * @param isAppend 是否追加写入，可选，默认为`false`，只对于文件类型有效
 */
export function writeString(str: string, target: Writer | OutputStream | File | string, encoding?: string, isAppend?: boolean): void;

/**
 * 从指定的流或字节数组中读取JSON。
 * 
 * 内部不会关闭流，调用者需要自行关闭。
 * 
 * @param content 待读取的流或字节数组，支持传递
 *     `Reader|InputStream|byte[]|File|Blob|string`类型，`string`类型为文件路径，若文
 *     件不存在则抛出异常
 * @param encoding 文件内容编码，可选，默认编码`UTF-8`。
 */
export function readJSON(content: Reader | InputStream | number[] | File | Blob | string, encoding?: string): JSONObject;

/**
 * 将一个JSON写入到指定的流中。
 * 
 * 内部不会关闭流，调用者需要自行关闭。
 * 
 * @param json 待写入的JSON
 * @param target 目标流，支持传递`Writer|OutputStream|File|string`类型，`string`类
 *     型为文件路径，若文件不存在则自动创建
 * @param encoding 文件内容编码，可选，默认编码`UTF-8`
 */
export function writeJSON(json: JSONObject, target: Writer | OutputStream | File | string, encoding?: string): void;

/**
 * 对传入的内容进行Base64编码，返回编码后的字符串可使用{@link decodeBase64()}函数可进行解码
 * 
 * @param obj 支持String|File|Blob|InputStream|byte[]等类型，注意：内部会自动关闭流，使用者无须再做处理
 * @return  返回base64编码的字符串
 */
export function encodeBase64(obj: any): string;

/**
 * 解码由{@link encodeBase64()}编码的字符串
 * 
 * @param str 待解码的字符串
 * @return 返回base64解码后的字符串
 */
export function decodeBase64(str: string): string;

/**
 * 对一串html的字符串内容进行转义
 * @example
 *  escapeHTML("<br/>&") = "&lt;br/&gt;&amp;"
 * @param str 要被转义或编码的字符串。
 * @return 转义之后的字符串
 */
export function escapeHTML(str: string): string;

/**
 * 对一串js的内容进行转义,将字符串转义内容再次转义
 * @example
 *  escapeJS("let test = \"test\"") = "let test = \\\"test\\\""
 * @param str 要被转义或编码的字符串。
 * @return 转义之后的字符串
 */
export function escapeJS(str: string): string;

/**
 * 执行前端指定的js模块中的指定的函数
 * 注意：
 * 1.若指定的函数中抛出了异常，则此方法也抛出异常
 * 2.支持异步函数
 * @param args 
 * @return 返回执行方法的返回值
 */
export function runNodeJs(args: {
	/**前端js模块名称，如`metadata/metadata`、`ana/dashboard/dashboard` */
	jsModule: string,
	/**要执行的函数的名称 */
	funcName: string,
	/**传递给函数的参数，参数是通过命令行传递给nodejs的，有字符限制 */
	args?: Array<string>,
	/**默认为true，支持前端代码中发起ajax请求 */
	supportAjax?: boolean,
	/**执行js模块的用户身份，可以为空，即用登录用户，在报表，仪表板，表单获取编译信息时，需要用一个有编辑权限的用户，不然在获取资源时可能会有权限异常 */
	userid?: string,
}): string;


/**
 * 加密一个密码，此函数使用的是可逆加密算法（使用{@link decryptPassword()}函数可进行解密），加密结果长度会比输入的密码长度略大。
 *
 * @param password 需要加密的明文密码字符串，null作空串处理
 */
export function encryptPassword(password: string): string;

/**
 * 解密由{@link encryptPassword()}加密的密文密码串，若该密码不是由encryptPassword加密的，则直接原样返回
 * 
 * @param password 需要解密的密文密码字符串，null作空串处理
 */
export function decryptPassword(password: string): string;

/**
 * SM3加密算法
 * @param data SM3加密的参数，可以为字符串、文件、blob、输入流
 * @returns 返回SM3加密的16进制字符串 
 */
export function encryptSM3(data: any): string;

/**
 * SM4算法加密数据
 * @param args 传递string类型的参数的时候，调用产品默认的加密参数
 * @return 返回加密之后的数据,Base64类型的字符串
 * @example
 * 1.推荐的调用方式：
 * 		// 不用指定秘钥，使用系统默认的
 * 		let strEncrypt = utils.encryptSM4(str); 
 * 2.在系统设置修改密钥之后
 * 		let strEncrypt = utils.encryptSM4({str:"TEST",mode:utils.SM4Mode.CBC,algorithmId:"**********"});
 * 3.CBC模式,key和iv不为16进制字符串的时候
 * utils.encryptSM4({
 *      str: "TEST",
 *      iv: "**************",
 *      key: "*************",
 *      mode: utils.SM4Mode.CBC,
 *      hexString: false,
 *      encoding: "utf-8"
 *	}
 * 4.ECB模式,key为16进制字符串的时候
 * utils.encryptSM4({
 *      str: "TEST",
 *      key: "***************",
 *      mode: utils.SM4Mode.ECB,
 *      hexString: true,
 *      encoding: "utf-8"
 *	}
 */
export function encryptSM4(args: {
	/**待加密数据 */
	str: any,

	/**加密模式 */
	mode: SM4Mode,

	/**算法id，在安全设置——数据加密中添加的算法的id。可以为空，默认为产品自带的秘钥id
		 说明，指定algorithmId和key二者只用指定1个
		 说明2，暂时只有mode=CBC才支持algorithmId参数。EBC模式得指定key
	*/
	algorithmId?: string,

	/**密钥 */
	key?: string,

	/**key和iv向量是否为16进制字符串，默认为false */
	hexString?: boolean,

	/**初始化向量,ECB模式可不用传递 */
	iv?: string,

	/**编码方式，默认为utf-8 */
	encoding?: string,
} | string): string;


/**
 * SM4算法加密数据
 * @param args 传递string类型的参数的时候，调用产品默认的加密参数
 * @return 返回加密之后的数据,Base64类型的字符串
 * @example
 * 1.推荐的调用方式：
 * 		// 不用指定秘钥，使用系统默认的
 * 		let strEncrypt = utils.decryptSM4(str); 
 * 2.在系统设置修改密钥之后
 * 		let strEncrypt = utils.decryptSM4({str:"TEST",mode:utils.SM4Mode.CBC,algorithmId:"**********"});
 * 3.CBC模式,key和iv不为16进制字符串的时候
 * utils.decryptSM4({
 *      str: "TEST",
 *      iv: "**************",
 *      key: "*************",
 *      mode: utils.SM4Mode.CBC,
 *      hexString: false,
 *      encoding: "utf-8"
 *	}
 * 4.ECB模式,key为16进制字符串的时候
 * utils.decryptSM4({
 *      str: "TEST",
 *      key: "***************",
 *      mode: utils.SM4Mode.ECB,
 *      hexString: true,
 *      encoding: "utf-8"
 *	}
 */
export function decryptSM4(args: {
	/**待解密数据 */
	str: any,

	/**解密模式 */
	mode: SM4Mode,

	/**算法id，在安全设置——数据加密中添加的算法的id。可以为空，默认为产品自带的秘钥id
		 说明，指定algorithmId和key二者只用指定1个
		 说明2，暂时只有mode=CBC才支持algorithmId参数。EBC模式得指定key
	*/
	algorithmId?: string,

	/**密钥 */
	key?: string,

	/**key和iv向量是否为16进制字符串，默认为false */
	hexString?: boolean,

	/**初始化向量,ECB模式可不用传递 */
	iv?: string,

	/**编码方式，默认为utf-8 */
	encoding?: string,
} | string): string;


/**SM4数据加密解密模式 */
declare const enum SM4Mode {
	/**ECB模式 */
	ECB = "ECB",
	/**CBC模式 */
	CBC = "CBC"
}

/**
 * 校验身份证号的合法性
 * @param pid 身份证号码
 * @example 
 * pidCheck("330722196501292110") = true
 * pidCheck("330722196501292112") = false	第18位数字校验失败
 * pidCheck("330722296501292110") = false	身份证生日不合法，校验失败
 * pidCheck("030722196501292110") = false	身份证区域校验失败
 * pidCheck("3307221965012921101") = false	身份证长度校验失败
 * pidCheck("330722650129211") = true
 */
export function pidCheck(pid: string): boolean;

/**
 * 校验身份证合法性，该方法返回详细信息
 * @param pid 身份证号码
 */
export function pidCheckInfo(pid: string): {

	/**身份证是否合法 */
	valid: boolean,

	/**
	 * 身份证错误信息代码
	 * err_checkcode，第十八位校验失败
	 * err_length，身份证长度不对
	 * err_city，身份证区位码不正确
	 * err_birthday，身份证生日不合法
	 */
	errorType?: string,

	/**身份证最后一位的字符 */
	checkCode?: string
}

/**
 * 将十六进制字符串转换成字符数组
 * @param hexString 16进制字符串
 */
export function hex2Bytes(hexString: string): Array<number>;

/**
 * 把一个字符串首尾和内部的非可见字符都去掉
 * @param str 
 */
export function trimAll(str: string): string;


/**
 * 对日期进行格式化，不传递date参数时，默认返回当前时间字符串
 * 
 * @param date  支持js的Date,java的Date,及long类型
 * @param pattern 格式，如yyyy-MM-dd HH:mm:ss ，默认为yyyyMMdd 
 */
export function formatDate(date: any, pattern?: string): string;

/**
 * 将日期字符串转换成java.util.Date类型
 * 
 * @param date 
 * @param pattern 如 yyyyMMdd，不传递时将尽量猜测各种可能的日期格式
 * @returns 无法解析时返回null
 */
export function parseDate(date: any, pattern?: string): any;

/**
 * 对传入的日期进行天数加len的操作
 * @param date 支持js的Date,java的Date,及String类型
 * @param len 
 * @param pattern 当传入字符串时，可指定字符串的格式，默认为yyyyMMdd 
 * @returns 传入String类型，返回String,传入jsDate或JavaDate,返回java.util.Date类型
 */
export function addDay(date: any, len: number, pattern?: string): any;

/**
 * 对传入的日期进行月份加len的操作
 * @param date 支持js的Date,java的Date,及String类型
 * @param len 
 * @param pattern 当传入字符串时，可指定字符串的格式，默认为yyyyMMdd
 * @returns 传入String类型，返回String,传入jsDate或JavaDate,返回java.util.Date类型
 */
export function addMonth(date: any, len: number, pattern?: string): any;

/**
 * 对传入的日期进行年份加len的操作
 * @param date 支持js的Date,java的Date,及String类型
 * @param len 
 * @param pattern 当传入字符串时，可指定字符串的格式，默认为yyyyMMdd
 * @returns 传入String类型，返回String,传入jsDate或JavaDate,返回java.util.Date类型
 */
export function addYear(date: any, len: number, pattern?: string): any;

/**
 * 判断指定的地点，是否在指定的区域内
 * 
 * @param lng  地点经度
 * @param lat  地点纬度
 * @param geometrys 表示一个地理几何结构区域，如：
 *	1.方圆500米`AROUND(117.195907,39.118327, 500)`
 *	2.矩形`rectangle(117.195907,39.118327, 116.925304,38.935671)`
 *	3.多边形`polygon(117.195907,39.118327, 116.925304,38.935671, 117.654173,39.032846)`
 *	4.也可以用分号分隔多个几何结构，比如要查询2个小学周边100米内的小卖部
 * @return 判断是否在指定的区域内
 */
export function geoWithIn(lng: number, lat: number, geometrys: string): boolean;

/**
 * 计算两个地点（经纬度）间的距离
 * 
 * @param lng1 地点1经度
 * @param lat1 地点1纬度
 * @param lng2 地点2经度
 * @param lat2 地点2纬度
 * @return  返回两个地点之间的距离，返回单位：米
 */
export function geoDistance(lng1: number, lat1: number, lng2: number, lat2: number): number;

/**
 * 将连续的dot变量分解为独立的变量。
 *
 * 变量中的字段名可能有特殊字符，会用中括号扩起来，转换时保留中括号。
 *
 * 使用场景:
 *
 * 1. 解析雪花模型的字段，比如`XSDW.XZQH.DQ.$LEVEL0`
 * 2. 模型的完整表名“qualified name”，需要注意的是返回值是倒序的数组。
 *    比如：`catalog1.schema1.table1` 返回：`["table1","schema1","catalog1"]`
 *
 * 例子：
 * 'XSDW.DLWZ.[CD.M]' -> ['XSDW','DLWZ','[CD.M]']
 * 'XSDW.DLWZ.[[CD]].M]' -> 不支持字段名中有[]的情况，因为会用中括号判断字段开始/结束位置。
 *
 * @param dotVarName
 * @param asc 是否顺序，false表示倒序，对于模型的“qualified name”需要返回倒序的数组。
 * @return 如果dotVarName为null，返回null，否则返回一个数组。
 */
export function splitVarName(dotVarName: string, asc: boolean): string[];

/**
 *将一组变量拼接为一个dot变量。
 *
 * 是{@link splitVarName(String, boolean)}的还原方法。
 *
 * 使用场景：
 *
 * 1.将“qualified name”还原，比如：["table", "scharm", "catalog"] 还原为："catalog.schema.table"
 *
 * @param varNames
 * @param asc 是否顺序，false表示倒序，对于模型的“qualified name”需要返回倒序的数组。
 * @return 如果varNames为null，返回null。
 */
export function concatVarName(varNames: string[], asc: boolean): string;

/**
 * 转换为 java.match.BigDecimal 对象。
 */
export function toDecimal(value: any): any;

/**
 * 转换为 java.lang.String 对象。
 */
export function toString(value: any): string;

/**
 * 转换为 java.match.BigInteger 对象。
 */
export function toBigInteger(value: any): any;

/**
 * 转换为 java.util.Integer或java.util.Long
 */
export function toInteger(value: any): number;

/**
 * 转换为 java.util.Double
 */
export function toDouble(value: any): number;

/**
 * 转换为 java.util.Date 对象。
 */
export function toDate(value: any): any;

/**
 * 转换为 java.sql.Date 对象。
 */
export function toSqlDate(value: any): any;

/**
 * 转换为 java.sql.Timestamp 对象。
 */
export function toTimestamp(value: any): any;

/**
 * 转换为 boolean。
 */
export function toBoolean(value: any): boolean;