# 常用表达式函数示例

## 场景说明

展示积木报表中可用的表达式函数，包括日期函数、字符串函数、数学函数、条件表达式和行号表达式。表达式以 `=` 开头，可使用常量参数或数据集参数 `${dbCode.field}`。

## 表达式语法规则

- 表达式以 `=` 开头：`=函数名(参数)`
- 常量参数直接写值：`=round(341.234, 2)`
- 数据集参数用 `${}` 引用：`=round(${jm_expression.num}, 2)`
- 字符串常量用双引号或单引号：`=date("2021-07-29")`

## 日期函数

| 函数 | 表达式 | 常量参数示例 | 数据集参数示例 |
|------|--------|-------------|---------------|
| `date()` | `date("2021-07-29 12:11:10")` | `=date("2021-07-29 12:11:10")` | `=date("${ds.create_time}")` |
| `time()` | `time("12:11:10")` | `=time("12:11:10")` | `=time("${ds.create_time}")` |
| `now()` | `now()` | `=now()` | `=now()` |
| `year()` | `year("2021-07-29 12:11:10")` | `=year("2021-07-29 12:11:10")` | `=year("${ds.create_time}")` |
| `month()` | `month("2021-07-29 12:11:10")` | `=month("2021-07-29 12:11:10")` | `=month("${ds.create_time}")` |
| `day()` | `day("2021-07-29 12:11:10")` | `=day("2021-07-29 12:11:10")` | `=day("${ds.create_time}")` |

### now() 格式化

通过 style 的 `format` 属性控制 `=now()` 的显示格式：

| format 值 | 输出格式 | 示例 |
|-----------|---------|------|
| `"date"` | yyyy-MM-dd | 2021-07-29 |
| `"date2"` | yyyy/MM/dd | 2021/07/29 |
| `"time"` | HH:mm:ss | 12:11:10 |
| `"datetime"` | yyyy-MM-dd HH:mm:ss | 2021-07-29 12:11:10 |

## 字符串函数

| 函数 | 表达式 | 常量参数示例 | 数据集参数示例 |
|------|--------|-------------|---------------|
| `char()` | `char(22269)` | `=char(22269)` | — |
| `cnmoney()` | `cnmoney(341.234)` | `=cnmoney(341.234)` | `=cnmoney(${ds.num})` |
| `cnmoney("b")` | `cnmoney(341.234,"b")` | `=cnmoney(341.234,"b")` | `=cnmoney(${ds.num},"b")` |
| `cnmoney("bw")` | `cnmoney(341.234,"bw")` | `=cnmoney(341.234,"bw")` | `=cnmoney(${ds.num},"bw")` |
| `concat()` | `concat('hello ','word',' !')` | `=concat('hello ','world',' !')` | `=concat('${ds.upper}',' world',' !')` |
| `lower()` | `lower('HELLOW')` | `=lower('HELLOW')` | `=lower("${ds.upper}")` |
| `upper()` | `upper('world')` | `=upper('world')` | `=upper('${ds.lower}')` |

### cnmoney() 参数说明

| 参数 | 说明 | 示例输出 |
|------|------|---------|
| 无 | 中文大写金额 | 叁佰肆拾壹元贰角叁分肆厘 |
| `"b"` | 简写 | 三四一.二三四 |
| `"bw"` | 简写带万 | 三百四十一.二三四 |

## 数学函数

| 函数 | 表达式 | 常量参数示例 | 数据集参数示例 |
|------|--------|-------------|---------------|
| `rand()` | `rand()` | `=rand()` | — |
| `rand()*N` | `rand()*100` | `=rand()*100` | — |
| `round()` | `round(341.234,2)` | `=round(341.234,2)` | `=round(${ds.num},2)` |
| `round(rand())` | `round(rand(),2)` | `=round(rand(),2)` | — |
| `abs()` | `abs(-341.234)` | `=abs(-341.234)` | `=abs(${ds.num})` |
| `floor()` | `floor(341.234,2)` | `=floor(341.234,2)` | `=floor(${ds.num},2)` |
| `ceil()` | `ceil(341.234,2)` | `=ceil(341.234,2)` | `=ceil(${ds.num},2)` |
| `trunc()` | `trunc(341.234)` | `=trunc(341.234)` | `=trunc(${ds.num})` |

## 条件表达式

### case() — 简单条件

```
=case(条件, 真值, 假值)
```

常量：`=case(1==1,'男','女')`
数据集：`=case('${ds.sex}'=='1','男','女')`

### if() — 多分支条件

```
=(let sex='${ds.sex}';
 if(sex== '1'){
    return '男';
}elsif(sex== '2'){
    return '女';
}else{
    return  '未知';
})
```

**注意：** 多行 if 表达式需要用 `()` 包裹整个表达式，用 `let` 声明变量，分支用 `elsif`（不是 `else if`）。

## 行号表达式

| 函数 | 说明 | 示例 |
|------|------|------|
| `row()` | 自动行号 | `=row(1)` 从1开始编号 |

## 样式中的 format 属性

styles 数组中可通过 `format` 控制单元格显示格式：

```json
{ "format": "date" }
{ "format": "date2" }
{ "format": "time" }
{ "format": "datetime" }
```

对应的 style 索引（本示例中）：

| 索引 | format | 边框 | 用途 |
|------|--------|------|------|
| 0 | date | 无 | 日期格式(无边框) |
| 1 | date2 | 无 | 日期格式2(无边框) |
| 2 | time | 无 | 时间格式(无边框) |
| 3 | datetime | 无 | 日期时间格式(无边框) |
| 5 | date | thin四边 | 日期格式(带边框) |
| 6 | date2 | thin四边 | 日期格式2(带边框) |
| 7 | time | thin四边 | 时间格式(带边框) |
| 8 | datetime | thin四边 | 日期时间格式(带边框) |

## 单元格链接（display: link）

```json
{
    "text": "更多表达式请查看详细文档。",
    "linkIds": "580872825561501696,580872825561501696",
    "display": "link",
    "merge": [0, 1]
}
```

| 属性 | 说明 |
|------|------|
| `display` | `"link"` 表示显示为超链接 |
| `linkIds` | 链接目标的报表ID，多个用逗号分隔 |

## 单元格纵向合并（数据行内）

```json
"5": {
    "cells": {
        "1": {
            "text": "now()",
            "merge": [3, 0],
            "height": 100,
            "style": 4
        }
    }
}
```

`merge: [3, 0]` 表示向下合并3行、向右合并0列，即占据第5-8行的第1列。

## 样式方案（绿色主题）

| 索引 | 背景色 | 用途 |
|------|--------|------|
| 12 | #93d051（绿色） | 分类标题行（日期函数/字符串函数等） |
| 17 | #93d051（绿色） | 表头行（函数名称/表达式/常量参数/数据集参数） |
| 4 | — | 数据行（thin四边框） |