报表与数据集函数

概述

这一组函数只在报表表达式里可用，读取的是当前报表实例的信息：当前单元格的行列号、总行列数、页码、序号、模板名称，以及按名称读取数据集。共 13 个函数。

取值时机

行号、列号、页码依赖计算完成后的报表结构，不同位置的表达式取值时机不同，先了解这一点可以避免得到 0 或 1 的困惑。

函数	含义	单元格「内容公式」中的取值	条件渲染、页眉页脚等后置阶段
row() column()	当前单元格计算后的行号、列号，从 1 开始	主内容计算阶段为 0（此时行列尚未编号）	正常取值
rows() columns()	计算后的总行数、总列数	主内容计算阶段尚未定型，不能当作最终值	最终值
page() pageCount()	当前页码、总页数	含这两个函数的表达式会被推迟到分页后计算；分页前（网格预览）为 1 和 1	分页导出（PDF、Word）时为真实页码

在单元格内容里做行号，推荐使用 &A1（扩展序号，见 报表基本语法）而不是 row()；在 条件渲染 的公式条件里，row() 可以正常使用，例如隔行变色写 row() % 2 == 1。

函数详解

row

语法

row()

无参数。

返回值：Integer，当前单元格所在行的计算后行号，从 1 开始。

示例

row() % 2 == 1

结果：在条件渲染的公式条件里，奇数行为 true

说明

• 在单元格「内容公式」的主计算阶段调用得到 0，因为此时行还没有编号；请只在条件渲染、页眉页脚这类后置阶段使用。
• 行号是整张报表计算后的行号，包含表头行、合计行和被扩展出来的所有行。

rows

语法

rows()

无参数。

返回值：Integer，计算后报表的总行数。

示例

rows()

结果：一个表头 1 行、数据 20 行、合计 1 行的报表在后置阶段为 22

说明

• 在主内容计算阶段调用时结果尚未定型，不能当作最终值。判断「是否最后一行」请在条件渲染中写 row() == rows()。

column

语法

column()

无参数。

返回值：Integer，当前单元格所在列的计算后列号，从 1 开始。

示例

column() == 1

结果：在条件渲染的公式条件里，第一列为 true

说明

• 取值时机同 row()：主内容计算阶段为 0。

columns

语法

columns()

无参数。

返回值：int，计算后报表的总列数。

示例

columns()

结果：一张 6 列的报表为 6

说明

• 取值时机同 rows()。

page

语法

page()

无参数。

返回值：Integer，当前页码，从 1 开始。

示例

'第' + page() + '页'

结果：分页导出时为 第1页、第2页 等；网格预览时恒为 第1页

说明

• 含 page() 的表达式在分页后才计算；分页前的预览一律按第 1 页处理，不会报错。
• 页码通常放在页眉页脚里，页眉页脚的设置见 报表设置与页面。

pageCount

语法

pageCount()

无参数。

返回值：Integer，分页后的总页数，至少为 1。

示例

page() + '/' + pageCount()

结果：分页导出时形如 2/5；网格预览为 1/1

说明

• 分页前尚未生成页，按共 1 页返回。

seq

语法

seq()
seq(key)

参数	类型	必填	说明
key	String	否	序列名称。相同 key 共享一条序列；省略或为空时使用默认序列

返回值：int，该序列的下一个数字，从 1 开始，每调用一次加 1。

示例

seq()

结果：第一次调用得 1，第二次得 2

seq('明细')

结果：名为 明细 的序列，从 1 开始独立计数

说明

• 计数器属于当前报表实例，每次预览或导出重新从 1 开始，不同 key 之间互不影响。
• 序号按表达式的计算顺序递增，而不是按页面上从上到下的顺序，遇到多层扩展或先后计算次序不同的格子时序号可能与视觉顺序不一致。给数据列加行号更稳的写法是扩展序号：在同一行另一格写 &B2，它表示 B2 扩展出的第几行。

cellOffset

语法

cellOffset(cellName, rowOffset, colOffset)

参数	类型	必填	说明
cellName	String	是	基准单元格名称，如 B2；该单元格必须能对应到唯一一个计算后的单元格
rowOffset	int	是	相对行偏移，负数向上，正数向下。必须是整数类型，不能是小数或长整型
colOffset	int	是	相对列偏移，负数向左，正数向右

返回值：Object，偏移到的单元格的值；偏移后超出报表范围时返回 null。

示例

cellOffset('B2', -1, 0)

结果：当前 B2 所在行上一行的 B2 值，用于与上一行对比

cellOffset('B2', 0, 1)

结果：B2 右边一格的值

说明

• 「基准单元格」指的是当前正在计算的行列位置上的那一个 B2 实例；若名称对应多个实例、无法判断哪一个，会报错。
• 偏移按计算后的行列计算，被隐藏的行会被跳过（不计入偏移量）。
• 典型用途：与上一行比较，如公式条件 $$value != cellOffset('B2', -1, 0)（条件渲染里 $$value 是当前单元格值）。

fileName

语法

fileName()

无参数。

返回值：String，当前报表模板的名称。

示例

fileName()

结果：模板名为「月度门诊报表」时得 "月度门诊报表"

说明

• 常用于页眉页脚或标题格中显示报表名称。

fileId

语法

fileId()

无参数。

返回值：String，当前报表模板的 ID。

示例

fileId()

结果：返回形如一串字符的模板标识

dataset

语法

dataset(datasetName)
dataset(datasetName, fieldName)

参数	类型	必填	说明
datasetName	String	是	数据集名称，包括报表内定义的数据集和公共数据集
fieldName	String	否	字段名称；省略时返回整行记录

返回值：List。指定字段时是该字段所有行的值的列表；省略时是所有行记录的列表。

示例

dataset('门诊').size()

结果：数据集「门诊」的行数

sum(dataset('门诊', '金额'))

结果：数据集「门诊」中「金额」列的合计

dataset('门诊', '科室').distinct().size()

结果：科室的去重个数

说明

• 数据集名称不存在时报错「数据集【名称】未定义！」。
• 数据集在同一次报表计算中只查询一次并缓存，多个单元格重复引用不会重复取数。
• 引用的是整个数据集，而不是当前单元格所在分组的部分；需要按条件取值时用 datasetSelect 或集合的 filter 方法。
• 预览时若设置为不取数（仅结构预览），返回空列表。数据集的定义与参数见 数据集概述。

rawDataset

语法

rawDataset(datasetName)
rawDataset(datasetName, fieldName)

参数	类型	必填	说明
datasetName	String	是	数据集名称
fieldName	String	否	字段名称；省略时返回整行记录

返回值：List，与 dataset 相同的结构：指定字段时是字段值的列表，省略时是记录列表。

示例

sum(rawDataset('门诊', '金额'))

结果：数据集「门诊」中「金额」列的合计

说明

• rawDataset 与 dataset 走同样的取数流程，但各自维护缓存；需要拿到数据集取数后原始、完整结果时使用它。数据集名称不存在时同样报「数据集【名称】未定义！」。

datasetSelect

语法

datasetSelect(datasetName, valueField, condField, condValue)

参数	类型	必填	说明
datasetName	String	是	数据集名称
valueField	String	是	取值字段
condField	String	是	条件字段
condValue	Object	是	条件值；与条件字段的值都转成文本后比较是否相等

返回值：List，条件字段等于条件值的各行的取值字段值；数据集为空或没有匹配行时返回空列表。

示例

datasetSelect('门诊', '金额', '科室', '内科')

结果：内科各行的金额列表

sum(datasetSelect('门诊', '金额', '科室', A2))

结果：与 A2 同科室的金额合计

说明

• 只支持「字段等于值」这一种条件，不支持大于、小于或多条件；需要复杂条件时先 dataset('门诊') 再用 filter。
• 比较前两侧都调用 toString()：数字 1 与文本 "1" 视为相等，条件字段值为 null 的行不匹配。
• 这是为 FineReport 的 ds.select(取值字段, 条件字段==条件值) 提供的等价写法，迁移说明见 帆软报表迁移。

常见用法

行序号与上一行对比

在数据行的 C2 格写 &B2 得到序号；在条件渲染里给与上一行相同的单元格淡色：

$$value == cellOffset('B2', -1, 0)

页脚页码

页脚文本写：

'第 ' + page() + ' 页，共 ' + pageCount() + ' 页'

分页导出后为「第 1 页，共 3 页」等。预览网格中恒为「第 1 页，共 1 页」。

各函数所属的完整目录见 内置函数总览。