逻辑与空值函数

概述

本篇包含条件判断（if）和空值处理的 9 个函数：isNull、isNotNull、isEmpty、isNotEmpty、isBlank、isNotBlank、ifNull、ifEmpty、coalesce。先区分三个容易混淆的概念：

概念	判断函数	为真的情形
空值（null）	isNull / isNotNull	值为 null
空（empty）	isEmpty / isNotEmpty	null、空字符串 ""、空数组、空集合、空 Map
空白（blank）	isBlank / isNotBlank	null、空字符串，以及只含空格、制表符等空白字符的字符串

数值 0 和 false 不属于以上任何一种。

功能入口

• 单元格属性面板「数据」标签，内容类型为「公式」时的「内容公式」，点击「编辑」打开「表达式编辑」对话框，在右侧「函数」标签页搜索并插入。
• 条件渲染中「条件类型」选「公式条件」时，公式的结果必须是布尔值 true 才算命中，见 条件渲染。

条件判断 if

if(条件, 真值, 假值) 写起来像函数，实际由解析器在编译时改写为三元表达式 条件 ? 真值 : 假值，所以它是语法而不是注册函数，只有被判定为「真」的那个分支会被求值。

语法

if(condition, valueIfTrue, valueIfFalse)
condition ? valueIfTrue : valueIfFalse

参数	类型	必填	说明
condition	任意	是	条件。按「真值规则」判断：null、false、0、空字符串、空集合、空数组、空 Map 为假，其余为真
valueIfTrue	任意	是	条件为真时的结果
valueIfFalse	任意	是	条件为假时的结果，三个参数缺一不可

返回值：被选中的分支的值。

示例

if($$value >= 90, '优秀', if($$value >= 60, '合格', '不合格'))

结果：$$value 为 95 得 "优秀"，为 70 得 "合格"，为 40 得 "不合格"。

说明

• 只有以 if( 开头且括号内最外层含逗号的写法才按「Excel 风格」处理；不含逗号的 if (条件) { ... } 是语句形式，用于多行脚本，见 脚本使用说明。
• 不支持 ?:（Elvis）、?? 这类简写；空值兜底请使用下文的 ifNull、coalesce。

函数详解

isNull

语法

isNull(value)

参数	类型	必填	说明
value	Object	是	任意值

返回值：boolean；仅当 value 为 null 时为 true。

示例

isNull(null)

结果：true

isNull('')

结果：false

说明

• ""、0、false 都不是 null。

isNotNull

语法

isNotNull(value)

参数	类型	必填	说明
value	Object	是	任意值

返回值：boolean；value 不为 null 时为 true。

示例

isNotNull(0)

结果：true

isEmpty

语法

isEmpty(value)

参数	类型	必填	说明
value	Object	是	任意值

返回值：boolean；value 为 null、空字符串、长度为 0 的数组、空集合或空 Map 时为 true。

示例

isEmpty('')

结果：true

isEmpty(' ')

结果：false

isEmpty(0)

结果：false

说明

• 判断依据是 Hutool 的 ObjectUtil.isEmpty。只含空格的字符串不算空，需要把它也当作空时使用 isBlank。

isNotEmpty

语法

isNotEmpty(value)

参数	类型	必填	说明
value	Object	是	任意值

返回值：boolean；与 isEmpty 相反。

示例

isNotEmpty('科室')

结果：true

isBlank

语法

isBlank(str)

参数	类型	必填	说明
str	CharSequence	是	字符串；null 视为空白

返回值：boolean；null、空字符串、只含空白字符（空格、制表符、换行等）时为 true。

示例

isBlank('   ')

结果：true

isBlank('A')

结果：false

说明

• 参数类型是字符串，传入数值等其他类型会因类型不匹配报错，先用 ::string 转换。

isNotBlank

语法

isNotBlank(str)

参数	类型	必填	说明
str	CharSequence	是	字符串；null 视为空白

返回值：boolean；与 isBlank 相反。

示例

isNotBlank(' 内科 ')

结果：true

ifNull

语法

ifNull(value, defaultValue)

参数	类型	必填	说明
value	Object	是	要检查的值
defaultValue	Object	是	value 为 null 时返回的默认值

返回值：value 不为 null 时返回 value，否则返回 defaultValue。

示例

ifNull(null, 0)

结果：0

ifNull('', '暂无')

结果：""（空字符串不是 null，原样返回）

说明

• 只判断 null；空字符串要兜底请使用 ifEmpty。
• 数据集计算字段可以使用它，如 ifNull($$record['customerName'], '')。

ifEmpty

语法

ifEmpty(value, defaultValue)

参数	类型	必填	说明
value	Object	是	要检查的值
defaultValue	Object	是	value 为空时返回的默认值

返回值：value 不为空时返回 value，否则返回 defaultValue；「空」的定义同 isEmpty。

示例

ifEmpty('', '暂无')

结果："暂无"

ifEmpty('内科', '暂无')

结果："内科"

说明

• 空字符串、null、空集合都会触发默认值；只含空格的字符串不会。

coalesce

语法

coalesce(value1, value2, ...)

参数	类型	必填	说明
value1, value2, ...	Object	是	依次检查的值，至少一个

返回值：第一个不为 null 的值；全部为 null（或没有参数）时返回 null。

示例

coalesce(null, null, 3)

结果：3

coalesce(null, '', 'x')

结果：""（空字符串不是 null）

说明

• 只跳过 null，不跳过空字符串。需要「第一个非空」时组合使用 ifEmpty。

组合使用示例

需求	表达式
空值显示为 0	ifNull($$value, 0)
空字符串或空值显示「未填写」	ifEmpty($$value, '未填写')
姓名为空白（含全空格）时显示「匿名」	isBlank($$value) ? '匿名' : $$value
多个候选字段取第一个非空值	coalesce($$record.mobile, $$record.phone, '无')

注意事项

注意：条件渲染的公式条件不按真值规则判断，公式结果必须是布尔 true（或文本 "true"）才命中；数值 1 或非空文本都不算命中。详见 条件渲染。

提示：引擎为同名的 isNull、isNotNull、ifNull 提供了脚本内置版本和平台版本，两者行为一致，无需关心使用的是哪一个。

相关文档

• 函数参考
• 报表基本语法
• 文本函数
• 条件渲染
• 聚合与集合函数