文本函数

概述

文本函数用于拼接、截取、查找、替换和中文数字转换。本篇共 18 个函数，参数类型为字符串的函数在收到 null 时的行为各不相同，逐个函数在「说明」里给出。

判断空白的 isBlank、isNotBlank 见 逻辑与空值函数。

功能入口

• 单元格属性面板「数据」标签，内容类型为「公式」时的「内容公式」，点击「编辑」打开「表达式编辑」对话框，在右侧「函数」标签页搜索并插入。
• 条件渲染的公式条件、新值公式，以及其他能输入表达式的位置同样可用。

函数列表

函数	作用	返回类型
concat	拼接任意个值，忽略 null	String
upper / lower	转大写 / 小写	String
trim	去掉两端空白	String
substring	按起止位置截取	String
left / right	从左 / 右侧截取指定长度	String
length	字符串长度	Integer
replace	替换（旧内容按正则处理）	String
indexOf	子串位置	int
find	字符串或集合中的元素位置	int
startsWith / endsWith / contains	前缀 / 后缀 / 包含判断	Boolean
joinIfNotEmpty	用分隔符连接非空值	String
toChinese	数字转中文数字	String
toChineseAmount	数字转中文大写金额（元角分）	String
numberToRMB	数字转人民币大写（圆）	String

函数详解

concat

语法

concat(value1, value2, ...)

参数	类型	必填	说明
value1, value2, ...	Object	否	任意个值；null 被忽略，其他值按 toString() 拼接

返回值：String；不传参数时为空字符串。

示例

concat('共', 3, '条')

结果："共3条"

concat('A', null, 'B')

结果："AB"

说明

• 与 + 拼接不同：concat 不会把两个数字文本相加。
• 数值内部是 BigDecimal 时，按 toString() 拼接，个别值（如经过去除末尾 0 处理的 100）可能显示为 1E+2；需要固定格式时先用 formatNumber 转成文本。

upper

语法

upper(str)

参数	类型	必填	说明
str	String	是	源字符串

返回值：String；str 为 null 返回 null。

示例

upper('abc')

结果："ABC"

说明

• 参数类型是字符串，传入数值等其他类型请先用 ::string 转换。

lower

语法

lower(str)

参数	类型	必填	说明
str	String	是	源字符串

返回值：String；str 为 null 返回 null。

示例

lower('ABC')

结果："abc"

trim

语法

trim(str)

参数	类型	必填	说明
str	String	是	源字符串

返回值：String；str 为 null 返回 null。

示例

trim('  科室A  ')

结果："科室A"

说明

• 等同 Java 的 String.trim()：去掉首尾的空格和控制字符。

substring

语法

substring(str, start, end)

参数	类型	必填	说明
str	String	是	源字符串；null 返回 null
start	int	是	起始位置，从 0 开始，包含
end	Integer	是	结束位置，不包含；传 null 表示截到末尾

返回值：String。

示例

substring('Hello World', 0, 5)

结果："Hello"

substring('Hello World', 6, null)

结果："World"

说明

• 三个参数都要写出，不能省略第三个（函数面板的提示把它标为可选，但实现没有两参数写法），截到末尾请显式传 null。
• 位置超出字符串长度或 start 大于 end 时抛出越界错误，不会自动截断。需要「不会越界」的截取请用 left、right。

left

语法

left(str, length)

参数	类型	必填	说明
str	String	是	源字符串；null 返回 null
length	int	是	要取的字符数；超过字符串长度时取整串

返回值：String。

示例

left('Hello World', 5)

结果："Hello"

left('AB', 5)

结果："AB"

right

语法

right(str, length)

参数	类型	必填	说明
str	String	是	源字符串；null 返回 null
length	int	是	要取的字符数；超过字符串长度时取整串

返回值：String。

示例

right('Hello World', 5)

结果："World"

right('13800001234', 4)

结果："1234"

说明

• right 是全局函数，写作 right(str, n)；字符串对象上没有 .right(n) 这样的方法。

length

语法

length(str)

参数	类型	必填	说明
str	String	是	源字符串

返回值：Integer；str 为 null 时返回 0。

示例

length('科室名称')

结果：4

说明

• 按 Java 字符串长度（UTF-16 代码单元）计数，常见汉字每个计 1。

replace

语法

replace(str, oldStr, newStr)

参数	类型	必填	说明
str	String	是	源字符串
oldStr	String	是	要替换的内容，先按正则表达式处理
newStr	String	是	替换成的内容

返回值：String；str、oldStr、newStr 任一为 null 时原样返回 str。

示例

replace('2024-01-05', '-', '/')

结果："2024/01/05"

replace('a.b', '[.]', '-')

结果："a-b"

说明

• oldStr 会先当作正则表达式做全部替换（replaceAll）；只有它不是合法正则时才退回普通文本替换。所以点号、括号、加号等特殊字符要转义，或放进字符类如 [.]：replace('a.b', '.', '-') 会得到 "---"。
• newStr 中的 $、\ 也按正则替换规则解释。

indexOf

语法

indexOf(str, find)

参数	类型	必填	说明
str	String	是	源字符串
find	String	是	要查找的子串

返回值：int：首次出现的位置（从 0 开始）；未找到返回 -1；任一参数为 null 也返回 -1。

示例

indexOf('Hello World', 'World')

结果：6

find

语法

find(source, target)

参数	类型	必填	说明
source	Object	是	字符串或集合（List 等 Collection）
target	Object	是	要查找的内容

返回值：int：位置（从 0 开始）；未找到返回 -1；任一参数为 null 返回 -1。

示例

find('Hello World', 'World')

结果：6

find(['a', 'b', 'c'], 'b')

结果：1

说明

• source 是字符串时，行为等同 indexOf(source, target.toString())。
• source 是集合时按 equals 比较元素；数组、Map 等其他类型返回 -1。

startsWith

语法

startsWith(str, prefix)

参数	类型	必填	说明
str	String	是	源字符串
prefix	String	是	前缀

返回值：Boolean；任一参数为 null 返回 false。

示例

startsWith('京A12345', '京')

结果：true

endsWith

语法

endsWith(str, suffix)

参数	类型	必填	说明
str	String	是	源字符串
suffix	String	是	后缀

返回值：Boolean；任一参数为 null 返回 false。

示例

endsWith('report.xlsx', '.xlsx')

结果：true

contains

语法

contains(str, part)

参数	类型	必填	说明
str	String	是	源字符串
part	String	是	要判断是否包含的子串

返回值：Boolean；任一参数为 null 返回 false。

示例

contains('心血管内科', '内科')

结果：true

说明

• 这里的 contains 是判断字符串包含的全局函数；集合是否包含某元素请用 find(list, x) >= 0。

joinIfNotEmpty

语法

joinIfNotEmpty(separator, value1, value2, ...)

参数	类型	必填	说明
separator	String	是	分隔符；为 null 时按空字符串处理
value1, value2, ...	Object	否	要连接的值；null 和空值（空字符串、空集合等）被跳过

返回值：String；没有任何非空值时为空字符串。

示例

joinIfNotEmpty('-', '北京', '', null, '朝阳')

结果："北京-朝阳"

说明

• 日期类型的值按 yyyy-MM-dd HH:mm:ss 输出，其他类型按 toString()。
• 只有空白字符的字符串（如 " "）不算空值，会被保留。

toChinese

语法

toChinese(number)

参数	类型	必填	说明
number	Number	是	要转换的数值；传 null 返回 null

返回值：String，小写中文数字。

示例

toChinese(123)

结果："一百二十三"

说明

• 由 Hutool 的中文数字转换实现，参数按 double 处理，使用简体小写数字。

toChineseAmount

语法

toChineseAmount(number)

参数	类型	必填	说明
number	Number	是	金额；传 null 返回 null

返回值：String，中文大写金额。

示例

toChineseAmount(123.45)

结果："壹佰贰拾叁元肆角伍分"

说明

• 由 Hutool 的金额大写转换实现。与 numberToRMB 的差别：本函数使用「元」，numberToRMB 使用「圆」；大额金额建议使用本函数（见 numberToRMB 的限制）。

numberToRMB

语法

numberToRMB(value)

参数	类型	必填	说明
value	Object	是	金额，可以是数值，也可以是可解析为数字的文本

返回值：String，人民币大写。

示例

numberToRMB(1234.5)

结果："壹仟贰佰叁拾肆圆伍角"

numberToRMB(100)

结果："壹佰圆整"

numberToRMB(-15)

结果："负拾伍圆整"

说明

• 小数部分只处理到「分」（保留两位小数以内的有效值，其余舍去）；没有角分时结尾为「圆整」；负数前加「负」。
• 10 至 19 的整数部分省略开头的「壹」，如 15 得 "拾伍圆整"。
• value 为 null 或空返回空字符串；是无法解析的文本时原样返回该文本。
• 金额达到 10000000（一千万）及以上时，内部把 double 转成字符串会出现科学计数法（如 1.0E7），函数会因此报错，大额金额请使用 toChineseAmount。

注意事项

注意：replace 的第二个参数是正则表达式，这是最常见的踩坑点，见上文示例。

注意：substring 的第三个参数不可省略；越界会报错而不是自动截断，处理位数不定的字符串时优先使用 left、right。

提示：字符串函数的参数类型是字符串。单元格里的数值（BigDecimal）传入前用 ::string 转换，例如 left(A1::string, 4)；:: 语法见 报表基本语法。

相关文档

• 函数参考
• 逻辑与空值函数
• 日期函数
• 报表基本语法
• 表达式与函数