0. 导读：怎么用这份文档

0.1 适合谁看

• 你会用 Word / Excel 排版，但没接触过「模板引擎」；
• 公司项目里有一堆 .docx 模板，里面写着 ${} 和 <aol:...>，你想弄明白它们是什么意思；
• 你想自己做一个「数据 → 自动出报表」的功能。

0.2 需要的前置知识

0.3 30 分钟速通路线

1. 第 1 节：把 8 个术语看懂（10 分钟）；
2. 第 3 节：把「Hello World」例子的代码复制运行，看到结果（10 分钟）；
3. 第 5 节 + 9.1 for：搞懂 ${} 和循环，这两样能解决 80% 的需求（10 分钟）；
4. 剩下的章节当成字典，用到时按目录查。

1. 一句话原理与术语表

1.1 它到底怎么工作的

你在 Word 里做的模板（tpl.docx）        你在 Java 里准备的数据
┌──────────────────────────┐          ┌──────────────────────────┐
│  员工：${name}            │          │  name = "张三"            │
│  ┌────┬──────┬────────┐  │          │  list = [ {name:张三,…},  │
│  │序号│ 姓名  │ 部门    │  │          │           {name:李四,…} ] │
│  ├────┼──────┼────────┤  │          └──────────────────────────┘
│  │<aol:for …>              │                       │
│  └────┴──────┴────────┘  │                       │
└──────────────────────────┘                       │
              └──────────► 引擎渲染 ◄───────────────┘
                             │
                             ▼
              员工：张三
              ┌────┬──────┬────────┐
              │ 1  │ 张三  │ 研发部  │
              │ 2  │ 李四  │ 市场部  │
              └────┴──────┴────────┘
                     结果 out.docx

1.2 术语表（看不懂的名词都在这）

docx / xlsx

本质都是 zip 压缩包，里面装着一堆 XML 文件。Word 文档的正文在包里的 word/document.xml，文字内容放在一层层段落、运行块、文本块里。引擎就是解压 → 改 XML → 压缩回去。

占位符 ${...}

写在模板里的「填空位」，例如 ${name}。渲染时被替换成数据里的 name 值。不带 aol 前缀，纯粹是取值。

标签 / aol 标签

写在模板里的「指令」，长得像 XML 标签：<aol:for ...></aol:for>。它不做取值，而是控制结构——循环、判断、合并、插图。aol 是默认命名空间（namespace），可以改（见第 15 节）。

上下文（Context）

一个「变量袋子」。你用 doc.variable("name", "张三") 放进去，模板里就能用 ${name} 取出来。循环时每一轮会克隆一份子上下文，这也是「循环里 ${name} 表示当前行」的原因。

DataSet / DataRow

anyline 的数据容器。DataSet ≈ 一张表（很多行），DataRow ≈ 一行记录。你把 JSON 或数据库查询结果转成它，<aol:for> 就能一行行遍历。

OGNL 表达式

${} 里可以写一点「小表达式」，如 ${score >= 60}、${list.size-1}、${item.name}。规则和 Java 的点号调用很像，但容错更高。表达式写错不会报错到页面上，只打日志（见第 12 节）。

JSON

一种文本格式的数据。{"name":"张三"} 是一个对象，[{...},{...}] 是一个数组（多行）。引擎可以直接把这种字符串变成 DataSet。

w:t / 「被拆散的文本」

Word 会把你输入的一句连续文字，偷偷切成好几个文本块（w:t），因为中间可能夹了拼写检查、语言标记等。这是新手最容易踩的坑：你看到的 ${name} 在文件里可能是 ${na + me} 两块。引擎有自动合并（recombine），但跨段落就救不回来了。

Imager / Uploader / Downloader

三个「外挂接口」，由你自己实现后注入： Imager 用来生成二维码/条形码图片； Downloader 用来把网上的图片下载到本地； Uploader 用于文档转 HTML 时把图片上传到你的文件服务器。 不注入，相关标签就静默不渲染。

2. 环境准备（从零开始）

2.1 需要的东西

• JDK 8 或更高（项目 pom.xml 里 source/target = 8）；
• Maven（或者 Gradle）；
• 一个能打开的 Word / WPS，用来做模板。

2.2 加依赖

在 pom.xml 里加（版本跟随 anyline 主版本，示例为 17.x）：

<dependency>
    <groupId>org.anyline</groupId>
    <artifactId>anyline-office</artifactId>
    <version>17.7.6-e-SNAPSHOT</version>
</dependency>

这个包依赖 anyline-core（会自动带进来）。如果从中央仓库拉不到快照版，需要加上官方仓库：

<repositories>
    <repository>
        <id>mdm</id>
        <url>http://maven.anyline.org/repository/maven-public/</url>
    </repository>
    <repository>
        <id>ossrh</id>
        <url>https://central.sonatype.com/repository/maven-snapshots/</url>
        <snapshots><enabled>true</enabled></snapshots>
    </repository>
</repositories>

2.3 建议的目录结构

D:/demo/
├── tpl.docx        // 你在 Word 里做的模板，只读，永不直接渲染
├── out.docx        // 程序生成的输出（先复制 tpl.docx 再渲染）
└── src/main/java/HelloWord.java

3. 第一个能跑起来的例子

目标：模板里写 员工姓名：${name}，程序跑完打开文档看到 员工姓名：张三。

员工姓名：${name}　　所属部门：${dept}

import org.anyline.office.docx.entity.WDocument;

import java.io.File;
import java.nio.file.Files;
import java.nio.file.StandardCopyOption;

public class HelloWord {
    public static void main(String[] args) throws Exception {
        File tpl = new File("D:/demo/tpl.docx");   // 原模板：只读
        File out = new File("D:/demo/out.docx");   // 输出文件

        // ① 先复制一份：渲染改的是这个副本，不是原模板
        Files.copy(tpl.toPath(), out.toPath(), StandardCopyOption.REPLACE_EXISTING);

        // ② 打开副本
        WDocument doc = new WDocument(out);

        // ③ 往上下文里放数据（key 就是模板里 ${} 中的名字）
        doc.variable("name", "张三");
        doc.variable("dept", "研发部");

        // ④ 渲染并保存（结果就地写回 out.docx）
        doc.save();

        System.out.println("已生成：" + out.getAbsolutePath());
    }
}

3.1 save() 内部到底做了 6 件事

知道这个顺序，后面排错会快很多（docx 侧）：

4. 三条数据通道

给模板送数据有三种方式，长得像但其实不一样，混用会迷惑，这里说清区别。

// 完整示例：一个变量、一段 HTML、一段纯文本
WDocument doc = new WDocument(out);
doc.variable("name", "张三");
doc.replace("content", "<b>标题</b>");          // 解析 HTML
doc.replace(false, "raw", "原样<b>不解析</b>"); // 不解析 HTML
doc.replace("word", new File("a.docx"));          // 插入另一个 word 文档内容
doc.save();                                         // 输出结果

xlsx 同套路：XWorkBook 也有 variable() / replace() / save()，模板单元格里直接写 ${列} 和 <aol:...> 标签（详见第 11 节）。

5. ${} 占位符完全指南

你可以先把 ${} 理解成「填空」。下面从最简单的开始，逐条加难度。

5.1 全部写法一览

5.2 三个容易忽略的细节

• 空值兜底：取不到值时输出 context.getPlaceholderDefault()，可以用 doc.setPlaceholderDefault("—") 换成短横线或空串。
• 属性值里的 ${} 也会被解析：fetchAttributeString 支持多段 ${} 拼接，所以 format="${fmt}"、items="${myList}" 这类「动态属性」是成立的。意思是：你先改变量，标签的属性值跟着变。
• Word 拆字问题：Word 会把 ${x} 拆到多个 w:t 里，引擎有自动合并（save() 第 3 步 recombine）。但跨段落、手动换行、书签、域里仍然会失败。

6. aol 标签基础

6.1 标签和 ${} 到底怎么分工

6.2 三种书写形式

<!-- ① 自闭合：不需要标签体 -->
<aol:if test="${score >= 60}" value="及格" else="不及格"/>

<!-- ② 成对：标签体里的内容会受到标签控制 -->
<aol:for items="${list}" var="item">${item.NAME}，</aol:for>

<!-- ③ 用标签体当数据源（value 属性没写时读 body） -->
<aol:money>${amount}</aol:money>

引擎按「标签名」分发（TagUtil 静态块里的注册表），标签名不区分大小写（内部统一 toLowerCase() 查表）， 但属性名区分大小写，建议一律小写。

6.3 命名空间：aol 是可以改的

aol 只是默认前缀（WDocument 里 namespace = "aol"）。如果模板里 aol: 和你的其它系统标签冲突，可以整体换掉：

WDocument doc = new WDocument(out);
doc.namespace("anyline");      // 之后模板里写 <anyline:for ...>

6.4 一个标签的生命周期

理解这 4 步，就知道为什么有些标签「不生效却也不报错」：

6.5 属性值的三种写法

<!-- ① 字面量：直接写死 -->
<aol:number value="1234.5" format="#,##0.00"/>

<!-- ② 动态：属性值里写 ${}，运行时先求值 -->
<aol:for items="${订单列表}" var="o">...</aol:for>
<aol:date format="${日期格式}" value="${@now}"/>

<!-- ③ 别名：同一个属性有多个名字，按优先级取第一个出现的 -->
<aol:sum data="${明细}" p="金额"></aol:sum>   <!-- p 就是 property -->

6.6 属性默认值：标签没写这个属性时怎么取值

每个标签属性都可以配一个「保底值」。标签显式写了就用标签上写的值，没写才按这里的默认值取。 配置项写成 标签名.属性名（大小写不敏感），值可以是 EL 表达式、普通字符串，也可以直接是一个对象。

// ① 全局：影响所有文件（建议在应用启动时配一次）
TagDefault.set("for.items", "${set}");

// ② 单个文件：只影响这个文档（context 就是文件的隔离边界）
XWorkBook book = new XWorkBook(out);
TagDefault.set(book.context(), "for.items", "${sales}");

// ③ 值也可以直接给对象，不用再包 ${}
TagDefault.set(book.context(), "for.items", set);

TagDefault.set(batch);                   // 批量：Map<String,Object>
TagDefault.set(book.context(), batch);   // 批量：Map<String,Object>

// 删除 / 清空
TagDefault.remove("for.items");
TagDefault.remove(book.context(), "for.items");
TagDefault.clear();
TagDefault.clear(book.context());

6.7 把标签定义成可复用片段：pre / ref

模板里同一段标签要写很多遍时，可以先「注册」再「引用」：

<!-- ① 用 <aol:pre id="xxx"> 注册一个片段（这段内容渲染后会被移除，只当定义） -->
<aol:pre id="金额栏"><aol:number value="${amount}" format="#,##0.00"/></aol:pre>

<!-- ② 用 <aol:金额栏/> 直接调用（以定义名当标签名） -->
合计：<aol:金额栏/>

<!-- ③ 也可以用 ref="名称" 引用，同时覆盖部分属性 -->
<aol:number ref="金额栏" value="${otherAmount}"/>

<!-- ④ 带 pre="名称" 的标签同样会被注册成片段，自身不输出 -->
<aol:date pre="日期" format="yyyy-MM-dd"/>

7. 标签清单

下面是注册表（TagUtil 静态块）里的全部 25 个标签。 「适用」一列：docx 表示正文可用； 仅 run 表示只实现了 run()，因此在 Excel 单元格中不生效。

8. 通用属性

这些属性不是某一个标签专属，而是由基类 AbstractTag 统一解析的。 也就是说：凡是从集合取数的标签（for / sum / avg / max / min / agg / concat / group / checkbox / chart），都认下面这套「数据源 + 切片」属性。

8.1 数据源与切片

8.2 输出控制

8.3 一个「全属性」的例子

<!-- 取「明细」里 金额 列，跳过前 2 条，最多 5 条，按 客户 去重，求和 -->
<aol:sum data="${明细}" b="2" q="5" ds="客户" p="金额"
         format="#,##0.00" scale="2" nvl="--"/>

sum、avg、max、min、agg 的差别只是「怎么算」， 「从哪些数据里算」完全共享上面这套属性，学会一个就会了全部。

9. 逐标签详解

每个标签一张卡片，统一按「干什么 → 属性表 → 最小示例 → 坑」来写。 属性表里的「别名」写法可以互换，「默认」列写了就说明不填时的行为。

9.1 for（循环）

<!-- ① 表格按行展开（模板行里写标签 + 占位符） -->
<aol:for items="${明细}" var="r" scope="tr" status="s">
序号 ${s.count} · 名称 ${r.NAME} · 金额 ${r.AMOUNT}
</aol:for>

<!-- ② 计数循环：没有 items，只有 end -->
<!-- ⚠ 实测：begin=1 end=5 会输出 5 份「副本」+ 1 份未替换的模板体（多一份），-->
<!--    固定份数建议写成 begin=1 end=4，或干脆用 items 传一个空集合 -->
<aol:for var="i" begin="1" end="5">第 ${i} 页 </aol:for>

<!-- ③ 固定 8 行，不够补空行（fill 是「把 end 撑到 N」，所以 8 行要写 7） -->
<aol:for items="${明细}" var="r" scope="tr" fill="7">${r.NAME}</aol:for>

<!-- ④ flatten：直接写列名 -->
<aol:for items="${明细}" var="r" scope="tr" flatten="true">${NAME} / ${AMOUNT}</aol:for>

<!-- ⑤ 嵌套：内层可以引用外层变量 -->
<aol:for items="${部门}" var="d">
  <aol:for items="${d.员工}" var="e">${d.名称} - ${e.姓名} </aol:for>
</aol:for>

WDocument doc = new WDocument(out);
doc.variable("明细", dataSet);   // DataSet / List<Map> / List<Bean> / [{...}] JSON 字符串都可以
doc.save();

9.2 if（判断）

<!-- ① 二选一文字输出（不需要标签体） -->
成绩：<aol:if test="${score >= 60}" value="及格" else="不及格"/>

<!-- ② 保留/删除标签体（标签体里可以有段落、表格、其它标签） -->
<aol:if test="${showDetail}">
  <h3>明细</h3>
  <aol:for items="${明细}" var="r" scope="tr">${r.NAME}</aol:for>
</aol:if>

<!-- ③ 把结果存成变量，后面 ${} 用 -->
<aol:if test="${score >= 60}" var="合格"/>
是否合格：${合格}

<!-- ④ 不满足条件时删掉内容（⚠ remove+scope 当前版本会抛 NPE 且行删不掉，见上方） -->
<aol:if test="${r.QTY > 0}">${r.NAME}</aol:if>
<!-- 想真正「整行消失」，请改为在 Java 侧过滤数据后交给 aol:for -->

9.3 数值类：sum / avg / max / min / agg

这五个是「算一个数出来」。数据源怎么写见 8.1，这里只讲各自的差异。

合计：<aol:sum data="${明细}" p="金额" format="#,##0.00"/>
数量：<aol:sum data="${明细}" p="数量" nvl="0"/>
纯数字列表：<aol:sum data="${数字列表}"/>

平均单价：<aol:avg data="${明细}" p="单价" scale="2"/>

<!-- 只输出金额最大值 -->
最大金额：<aol:max data="${明细}" p="金额"/>

<!-- 取最大金额那一整行，再展开它的几个字段 -->
<aol:max data="${明细}" p="金额" var="最大单"/>
最大单客户：${最大单.客户} · 金额：${最大单.金额}

明细条数：<aol:agg type="count" data="${明细}" p="金额"/>
金额中位数：<aol:agg type="median" data="${明细}" p="金额" scale="2"/>
标准差：<aol:agg type="stdev" data="${明细}" p="金额" scale="2"/>
行数（任意集合）：<aol:agg type="count" data="${名单}" empty="true"/>
均值并格式化：<aol:agg type="avg" data="${明细}" p="金额" scale="2" format="#,##0.00"/>

5 个标签怎么选（速查）

坑

1. avg / max / min 只认 DataSet：数据源是别的集合类型时不报错、直接输出空，很容易误判为「数据没传进去」。
2. 字段名要和数据里的 key 完全一致：DataSet 默认做了大小写归一（通常大写），如果 p="amount" 取不到就试 p="AMOUNT"。
3. sum 遇到脏数据会抛异常，不是当 0：源码是 new BigDecimal(val.toString())，所以 "1,234.00"、"-"、"12元" 这类值会直接抛 NumberFormatException（已实测，堆栈定位到 Sum.java:82）。因为异常被 TagUtil 捕获，现象是「这个合计格子是空的，同时日志里有堆栈」， nvl="0" 也不会生效（异常发生在兜底之前）。对比：agg type="sum" 容错——它把解析失败的值当 null 跳过（empty="true" 时当 0），不会炸。所以脏数据列建议用 agg。
4. avg / median / stdev / var 默认 10 位小数：不写 scale 时结果形如 34.3333333333，并且会去掉末尾多余的 0（实测 median 输出 2 而不是 2.0000000000）。报表上基本都要显式写 scale 或 format。
5. number / date / money 的 value 没有 v 别名：只有 value 一个写法（有 v 别名的是 qr/bar/checkbox）。写成 v="..." 会取不到值，输出空。
6. 空数据的表现要显式兜底：sum 无数据且没写 nvl 时输出空串，报表上就是一个空洞，建议统一写 nvl="0"。
7. 先切数据再算：begin/end/qty/distinct 会真正影响计算结果（切片在计算之前完成），做「小计」时很实用，但别误以为只影响显示。

9.4 格式化类：number / money / date

这三个的共同点：它们不改变文档结构，只把一个值变成一段好看的文字， 所以也是少有的「在 Excel 单元格里也能用」的标签（number / date）。

<aol:number value="${amount}" format="#,##0.00"/>
<aol:number value="${rate}" format="0.00%"/>
<aol:number format="#,##0">${qty}</aol:number>   <!-- 用标签体当输入 -->

人民币（大写）：<aol:money value="${amount}"/>
人民币（大写）：<aol:money>${amount}</aol:money>

签章日期：<aol:date evl="true" format="yyyy年MM月dd日"/>
开票时间：<aol:date value="${createTime}" format="yyyy-MM-dd HH:mm"/>
<aol:date format="yyyy-MM-dd">${某个日期字符串}</aol:date>

9.5 集合处理：set / select / concat / group

<!-- 普通赋值（类型自动推断：这里会变成 BigDecimal） -->
<aol:set var="税率" value="0.13"/>
<aol:set var="是否含税" value="true"/>
<aol:set var="客户名">${customer.name}</aol:set>

<!-- 之后就能当变量用（含参与表达式计算） -->
含税金额：<aol:number value="${金额 * (1 + 税率)}" format="#,##0.00"/>
客户：${客户名}

客户：<aol:concat data="${明细}" p="客户" split="、"></aol:concat>

<aol:group data="${订单}" var="按客户" by="客户"/>
<aol:group data="${订单}" var="按部门岗位" by="部门,岗位" extract="true"/>

<!-- 输入(姓名,科目,分数) -->
张三 数学 100
张三 物理 90
李四 数学 80

<!-- 一行搞定透视 -->
<aol:pivot data="${明细}" pk="姓名" class="科目" value="分数" var="宽表"/>

<!-- 宽表里就能这样取 -->
<aol:for items="${宽表}" var="row">
  ${row.姓名}：数学 ${row.数学}，物理 ${row.物理}
</aol:for>

<!-- 多个 value 会生成复合列名(2010-数学-分数 / 2010-数学-等级) -->
<aol:pivot data="${明细}" pk="编号,姓名" class="年度,科目" value="分数,等级" var="宽表" sep="_"/>

9.6 checkbox（勾选项）

<!-- 单选：value 是一个值 -->
性别：<aol:checkbox data="${性别选项}" value="${user.SEX}" rely="CODE" valueKey="CODE" textKey="NM"/>

<!-- 多选：value 是集合 -->
爱好：<aol:checkbox data="${爱好选项}" value="${user.HOBBIES}" vk="CODE" tk="NM" vol="4"/>

<!-- 只要文本，不要方框 -->
状态：<aol:checkbox data="${状态选项}" value="${order.STATUS}" type="text" split=" / "/>

doc.variable("性别选项", DataSet.parseJson(KEY_CASE.SRC,
    "[{\"CODE\":\"M\",\"NM\":\"男\"},{\"CODE\":\"F\",\"NM\":\"女\"}]"));
doc.variable("user", DataRow.parseJson(KEY_CASE.SRC, "{\"SEX\":\"M\",\"HOBBIES\":[\"A\"]}"));

<!-- 正确：用 CODE 做值比对 -->
<aol:checkbox data="${选项}" value="${user.SEX}" vk="CODE" tk="NM"/>

<!-- 错误：把值比对字段写成了 NM，rely 是 CODE 也没用 -->
<aol:checkbox data="${选项}" value="${user.SEX}" vk="NM" tk="NM" rely="CODE"/>

9.7 merge（单元格合并）

<!-- 明细表：把「客户」这一列的相邻同值单元格纵向合并 -->
<aol:for items="${明细}" var="r" scope="tr">
  ${r.客户} | ${r.商品} | <aol:merge scope="tc"/>${r.金额}
</aol:for>

<!-- 只有当「客户」也相同时才合并「订单号」列 -->
<aol:merge scope="tc" by="客户" ignore="null,-"/>

<!-- 横向合并（一行内相邻列同值） -->
<aol:merge scope="tr"/>

9.8 富文本与图形：img / html / qr / bar

<aol:img src="${logoUrl}" style="width:${logoW}px;height:${logoH}px;"/>
<aol:img src="file:D:/tpl/logo.png" style="width:120px;"/>

<aol:html>
  <div style="font-size:14px;color:#333;">
    <b>${title}</b><br/>
    <table><tr><td>${a}</td><td>${b}</td></tr></table>
  </div>
</aol:html>

<aol:qr value="https://anyline.org" style="width:120px;height:120px;"/>
<aol:bar value="${order.NO}" width="200" height="60"/>

9.9 page（分页符）

<aol:page/>              <!-- 在本标签后分页 -->
<aol:page position="after"/>

9.10 chart（原生图表）

<!-- ① 单个 ${变量}（推荐）：Java 侧塞 DataSet / List<Map> -->
<aol:chart type="pie" title="销售分布" data="${sales}"
           categoryKey="name" valueKey="value" width="5274310" height="3076575"/>

<!-- ② 直接把 JSON 写在属性里 -->
<aol:chart type="column" data='[{"name":"A","value":30},{"name":"B","value":70}]'/>

<!-- ③ 交错模式：ChartData 对象（支持多系列） -->
<aol:chart data="${chart}" dimension="3D" shape="cylinder"/>

// ① 单系列
DataSet sales = DataSet.parseJson(KEY_CASE.SRC,
    "[{\"name\":\"产品A\",\"value\":30},{\"name\":\"产品B\",\"value\":70}]");
doc.variable("sales", sales);

// ③ 多系列：ChartData
ChartData chart = ChartData.build()
        .title("两年对比").type("column").dimension("3D").shape("cylinder")
        .width("600px").height("380px");      // 带 px 会自动换算成 EMU
chart.addSeries("2024").add("华东", 120).add("华南", 90).add("华北", 60);
chart.addSeries("2025").add("华东", 150).add("华南", 110).add("华北", 80);

doc.variable("chart", chart);

doc.save();

9.11 mark 与「写了没用」的标签

<aol:mark name="合同金额">${amount}</aol:mark>

想自己写一个标签？

public class MyTag extends AbstractTag implements Tag {
    public void run() throws Exception {
        String v = fetchAttributeString("value", "v");   // 属性（支持 ${} 求值）
        Object d = data();                                   // 数据源（含切片）
        output("结果文本");                               // 写回文档 / 写入 var
    }
}
TagUtil.reg("mytag", MyTag.class);                          // 注册后模板里写 <aol:mytag/>

可用的工具：fetchAttributeString(names...)、fetchAttributeData(names...)、 data()、output(result)、body(text, "标签名")、 doc（WDocument）、context、tops/contents/box。

9.12 grid：检测项网格（四维透视表）

把「长表」数据按 组 × 检测项 × 轴值 × 值类型 四维铺进一个 Word 表格。 典型场景：检测报告里行是样品（轴值）、列是检测项、每个检测项下再分「标准值 / 检测值」（值类型）。

什么时候用它

数据是长表（一条记录一个值）： {组:一班, 检测项:身高, 样品:张三, 类型:标准值, 结果:170}， 而最终表格要二维铺开。for 只能一维循环，pivot 只能做行转列， 这种「行、列、还要再分类型」的网格要用 grid。

行式模板长什么样（dir="h"，默认）

┌────────┬──────────────┬──────────────┬──────────────┐
│        │  ${指标}      │  ${指标}      │  ${指标}      │ ← 名称行（标签写在这一行的任意格子里）
│ ${组}  ├──────┬───────┼──────┬───────┼──────┬───────┤
│        │ 标准值│ 检测值 │ 标准值│ 检测值 │ 标准值│ 检测值 │ ← 表头行（可选，固定文本=值类型）
├────────┼──────┼───────┼──────┼───────┼──────┼───────┤
│        │${样品}│ ${结果}│ ${结果}│ ${结果}│ ${结果}│ ${结果}│ ← 数据行（样板，按轴值克隆）
└────────┴──────┴───────┴──────┴───────┴──────┴───────┘
<aol:grid items="${rows}"/>

• 名称行：第 1 格写 ${组}（不需要分组可以留空），之后每格写一个 ${指标}。 各项名格要按 gridSpan=K 画好（K = 值类型数，上图 K=2，即每个检测项占 2 列）。
• 表头行（可选）：写值类型的固定文本。可以只写前 K 个格，也可以按项重复写满整行—— 引擎会按名称行项名格的宽度取前 K 个，多余的重复自动忽略。
• 数据行：轴值格写 ${样品}，值格统一写 ${结果}。 值格里的占位符名决定从记录里取哪个字段；值格不写占位符就不会被填充（保持模板原样）。
• 标签：写在名称行里，run 阶段执行，所以只认表格里的位置。

列式两种版式（dir="v"）

<!-- layout="item"（默认）：轴值沿列展开，每个检测项占 K 行 -->
行1(轴头行):  [${组}]   [${样品}]  [${样品}] …
行2(项首行):  [${指标}] [${结果}]  [${结果}] …   ← 项名格 vMerge 跨 K 行
行3(类型行):  [标准值]  [${结果}]  [${结果}] …   ← 类型文本写在标签列

<!-- layout="block"：轴值横向成块 -->
行1(轴头行):  [${组}]   [${样品}]             [${样品}] …
行2(项名行):  [      ]  [${指标}] [${指标}]   [${指标}] [${指标}]  ← 项名格 gridSpan=K
行3..K+2:    [标准值]  [${结果}] [${结果}]   [${结果}] [${结果}]  ← K 个值类型行

列式的 K = 值类型行的行数（不是表头文本），由模板直接决定； vol 在列式里表示「每行最多几个轴块」，默认 1（不写会有 warn）。

属性

数据规则

1. 检测项为空的记录跳过并 warn；轴值 / 值类型为空时，已声明对应字段的记录跳过并 warn，未声明的按单轴 / 单类型处理。
2. 同名（组+项+轴+类型）重复的记录，后值覆盖前值并 warn。
3. 数据为空时整个模板区（名称行 / 表头行 / 数据行）会被删除。

9.13 全标签属性总表（一站式速查）

前面的卡片是「按需求讲」，这一节是「按属性查」—— 把源码里 真正被解析的每一个属性都列出来，包括官方一路没写进文档、 以及解析了却不生效的那几个。查表规则：

• 「别名」栏：写哪个都行，按 fetchAttributeString 里列出的先后顺序取第一个出现的；
• 「必填」栏：是 = 不写就完全不工作；否 = 有默认行为；
• 「生效」栏：生效 / 不生效， 「不生效」的别浪费时间试。

共有的「取数 + 切片」属性

下面这些由基类 AbstractTag 统一解析，凡是从集合取数的标签都认（for / sum / avg / max / min / agg / concat / group / checkbox / chart）：

各标签的「专属属性」逐条清单

子标签：<aol:split>

复合饼图的参数也可以写成 chart 标签体里的子标签，属性与上表后半段一一对应：

「解析了却不生效」清单（照这个避坑）

10. Word 模板制作规范

前 9 章讲「怎么写标签」，这一章讲「模板本身怎么设计才不会踩坑」。模板没做对，标签写得再对也出不来结果。

10.1 第一条铁律：模板文件先复制

// 正确做法
File tmp = File.createTempFile("rpt", ".docx");
Files.copy(Paths.get("D:/tpl/invoice.docx"), tmp.toPath(), StandardCopyOption.REPLACE_EXISTING);

WDocument doc = new WDocument(tmp);
doc.variable("...", ...);
doc.save();                       // 改写的是 tmp，母版 safe

// 错误做法：直接 new WDocument(new File("D:/tpl/invoice.docx"))
// 第二次运行就会变成一个「已经被填过内容」的模板

10.2 ${} 被 Word 拆散这件事

Word 保存时会把一段文字拆成多个 w:r/w:t（因为字体/拼写检查/输入历史等原因）， 于是 ${name} 可能变成 ${na + me}。 引擎在启动时会做一次 recombine() 把同一个段落里被拆开的 ${} 和 <aol:...> 合并回来，绝大多数情况能自动救回来。

但它救不了下面这些情况，请从源头避免：

1. 占位符跨段落：${ 在上一段、} 在下一段 —— 无解，请保证一个 ${} 在一个段落内。
2. 标签跨段落：同理，<aol:for ...> 的尖括号也必须在同一段落内（标签体可以跨段落，标签本身的 <> 不行）。
3. 占位符里有换行/软回车：写 ${a+Shift+Enter+b} 会解析失败。
4. 中文输入法中途切换：容易把 $ 输成全角。请确认是半角 $ { }。
5. 把 ${} 拆开后再改字体：改字体是最容易造成拆分的操作，建议先写占位符、最后统一改格式，或者干脆用「全选 → 清除格式」重来。

10.3 表格模板的规范

10.4 段落、换行与空白

• 不能在标签里写 \n：Word 里的换行是段落，不是字符。要换行就写真的回车（在标签体内换行），或者用 <br/>（经 html 渲染）。
• 标签体内的「空段落」也是内容：写 <aol:for> 时前后各空一行，会真的多出一行空白，建议紧贴内容写。
• 空白占位符的默认值：取不到值时输出什么，由 doc.setPlaceholderDefault(...) 控制（默认空串），见 12.4。
• 文件末尾的段落：Word 文档必须有结尾段落，删除操作（remove）把它删空后会被引擎补回一个空段落，属正常现象。

10.5 页眉 / 页脚 / 图表

• 页眉页脚里的 ${} 也会被替换（引擎按 页眉 → 页脚 → 图表 → 正文 的顺序处理）。
• 页眉页脚里不要写 aol 标签：标签渲染只针对正文 document.xml，写在页眉里的标签会原样留在文档中。
• 页码用 Word 自己的「插入 → 页码」功能，不要试图用 ${} 实现。
• 图表（Excel 图表/Word 图表）里的文字占位符也支持替换，但图表标签 <aol:chart> 只在正文生效。

10.6 样式全部交给 Word

10.7 HTML 对照表（<aol:html> / <aol:img> 用）

引擎内部把 HTML 子集翻译成 OOXML。下面是实际实现了的标签与属性：

10.8 模板自查清单

• 模板是「只读母版 + 临时副本」的用法，不是直接改母版；
• 每个 ${} 和每个标签的尖括号都在同一个段落内；
• ${} 是半角字符；
• 循环标签写在模板行的单元格里，表头行没有循环标签；
• 没有 <aol:select> / <aol:include> 这类不会生效的标签；
• 需要图片/二维码的地方已确认 Java 侧注入了 Downloader / Imager；
• 取不到值的地方想好了兜底（setPlaceholderDefault 或标签的 nvl）。

11. Excel（xlsx）使用说明

Excel 模板简单得多，也受限得多。这一章先说清楚「能做什么」，再说「为什么不能」，避免你在错误的路上耗时间。

11.1 基本用法

// 同样是「复制母版 → 打开 → 填数 → 保存回同一个文件」
File tmp = File.createTempFile("rpt", ".xlsx");
Files.copy(Paths.get("D:/tpl/report.xlsx"), tmp.toPath(), StandardCopyOption.REPLACE_EXISTING);

XWorkBook book = new XWorkBook(tmp);
book.variable("title", "2026年销售报表");
book.variable("明细", detailDataSet);
book.save();

save() 内部顺序（顺序很重要，排错时按它对照）：

11.2 哪些单元格会被处理

11.3 单元格里能用的标签

那 Excel 里怎么求和？两个办法： ① 用 Excel 自己的公式（模板里写 =SUM(D2:D100)），这也是最自然的方式； ② 在 Java 侧用 agg/sum 算好，再用 book.variable("合计", value) 传进来填。

11.4 行循环（xlsx 版的 for）

<!-- 在第 2 行（模板行）的任意单元格里写： -->
<aol:for items="${明细}" var="r">${r.NAME}</aol:for>

11.5 合并单元格（xlsx 版的 merge）

<!-- 写在模板行的某个单元格里 -->
<aol:merge scope="tc"/>            <!-- 纵向：相邻行同值合并 -->
<aol:merge scope="tr"/>            <!-- 横向：相邻列同值合并 -->
<aol:merge scope="tc" by="客户" ignore="null,-"/>

和 docx 一样是延迟执行：parseTag() 阶段只登记， 所有行循环跑完后由 executeMerges() 统一合并，所以不用担心「数据还没填完就合并了」。

11.6 图表（xlsx 版 chart）

<!-- 写在单元格里（和 ${} 一样，必须写在同一个单元格内） -->
<aol:chart type="column" title="销售分布" data="${sales}"
           categoryKey="name" valueKey="value" width="400" height="300"/>

引擎按顺序做四件事：

1. 生成图表部件 xl/charts/chartN.xml（序号与模板里已有的图表连续，不会覆盖）；
2. 新建一个隐藏工作表（ChartData1、ChartData2…）把图表数据写进去；
3. 在工作表关联的 xl/drawings/drawingN.xml 里加 xdr:graphicFrame，锚定到标签所在单元格；
4. 补齐 [Content_Types].xml 与各级 .rels（没有 drawing 时会一起新建）。

11.7 docx 与 xlsx 差异对照

12. 调试与排错

12.1 先把日志打开

引擎内部用的是 anyline 自己的日志门面 LogProxy，会桥接到你项目里已有的日志实现。 把它调成 DEBUG / INFO，就能看到标签的执行轨迹与报错信息：

// logback 示例：只放开 office 包
<logger name="org.anyline.office" level="DEBUG"/>

还有一类「没有日志的失败」：标签「只实现 run() 却写在 Excel 单元格里」、 「avg 的数据源不是 DataSet」—— 这些是直接 return， 不打日志、不报错，只能对照本文档判断。

12.2 症状 → 原因 → 处理

12.3 二分法定位：先让数据可见

出问题时不要在脑子里猜，按「数据 → 标签 → 排版」的顺序逐段排除：

<!-- 第 1 步：把数据原样打在模板上，确认真的进来了 -->
明细条数：${明细}          <!-- DataSet 会整体 toString，能看到条数 -->

<!-- 第 2 步：确认取值路径对（循环里逐字段打印） -->
<aol:for items="${明细}" var="r" scope="tr">
  name=${r.NAME} | amount=${r.AMOUNT}
</aol:for>

<!-- 第 3 步：确认标签语法对（先用最简单的属性） -->
<aol:if test="${1 == 1}" value="IF-OK" else="IF-FAILED"/>

12.4 取不到值时输出什么：setPlaceholderDefault

WDocument doc = new WDocument(tmp);
doc.setPlaceholderDefault("-");      // 所有找不到的 ${key} 都输出 "-"
// 默认值是空串（也就是留下空白）

这是唯一能全局控制「空值显示」的地方；nvl 这类属性是标签自己的局部兜底， 两者不冲突：标签的 nvl 优先。

12.5 实例复用与重复 save()

• save() 内部会先 load()，每次 save 都会重新解析文件；同一个实例连续 save 两次，图表部件会累积（每次都会追加新的 chartN.xml 与关系项）。
• 因此推荐一个实例只 save 一次：要生成 N 份就 N 次「复制母版 + new + save」。
• 多线程并发生成时，每个线程操作自己的副本文件，不要共享 File。

13. 常见坑速查

把这一节当交付前的检查清单，逐条打勾。

13.1 模板侧

• 母版文件永远被复制后再交给引擎（否则第二次运行全乱）；
• 每个 ${}、每个标签的 <> 都在同一个段落 / 同一个单元格内；
• 没有全角 ＄｛｝、没有中文标点混入；
• 循环标签写在模板行（tr）的单元格里，表头行不放循环标签；
• 页眉页脚只写 ${}，不写 aol 标签；
• 模板里没有 <aol:select>、<aol:include> 这类无效标签残留；
• Excel 模板里没有「只在 docx 生效」的标签。

13.2 标签侧

• for：var 写了吗？序号用 count 而不是 index 了吗？scope 和标签位置匹配吗？
• if：字符串比较加引号了吗？remove 配 scope 了吗？
• 数值类：字段名大小写对吗？数据源是 DataSet 吗（avg/max/min）？
• number/date：format 真的写了吗（不写就原样输出、看起来像「没生效」）？
• money：传的是裸数字吗（带千分位会被截断成 1）？
• checkbox：data 是 List<Map> 吗？rely / valueKey 和选项数据的列名一致吗？
• merge：写在模板行里了吗？只写在表格内了吗？
• chart：data 是一个完整的 ${} 吗？宽高单位是 EMU 吗？
• qr/bar/img：Java 侧注入了 Imager / Downloader 吗？

13.3 数据侧

• 集合不是单个对象（for/chart/checkbox 都要求集合）；
• 字段名和模板里的 ${} 完全一致（含大小写）；
• 数值列里没有 "1,234.00"、"—" 之类的脏值；
• 日期列传的是 Date 或可解析的字符串；
• 用 DataSet 时注意它的默认列名归一化规则（一般是大写）。

13.4 运行侧

• 文件没被 Word / Excel 打开占用（否则写回失败）；
• 先复制再生成，生成完再决定是否改名/移动；
• 临时文件记得清理（File.deleteOnExit() 或 finally 里删）；
• 生成完最好用 Word/Excel 打开一次，确认没有「文档结构损坏」提示（合并单元格 + 空表格最容易触发）。

14. 能力边界

知道「它不做什么」，比知道「它能做什么」更能省时间。

14.1 不负责排版

引擎不生成样式、不做自动布局、不自动调列宽行高。 所有视觉结果都来自你的模板。所以「生成的文档丑」不是 bug，是模板问题。

14.2 不支持的场景（明确说明）

14.3 已知的「静默失败」（最需要小心）

15. 进阶技巧

15.1 用 pre / ref 消灭重复

同一段标签写很多遍时，先注册、再引用，模板会干净很多（机制见 6.6）：

<!-- 定义（这段不渲染） -->
<aol:pre id="金额格"><aol:number value="${v}" format="#,##0.00"/></aol:pre>

<!-- 引用 -->
含税：<aol:金额格 v="${amount}"/>
不含税：<aol:金额格 v="${amount / 1.13}"/>

ref 也可以用来「继承 + 覆盖」： <aol:number ref="金额格" v="${x}"/> 会把定义里的 format 一起带过来。

15.2 内置变量 ${aov:...} / ${alv:...}

aov: 与 alv: 两个命名空间都指向同一批「表达式执行器」， 运行时按 名字 查表，把结果填进占位符。

15.3 文档拼接与书签定位

需要把多个模板拼成一份文档、或者往书签位置插内容时，用这些 API：

// 组合思路：模板 A 尾部插入模板 B 的全部内容
WDocument doc = new WDocument(tmpA);
doc.load();
Element tail = /* 模板 A 里某个已存在的元素 */;
doc.insert(tail, new File("D:/tpl/B.docx"));
doc.save();

在 HTML 里也可以直接拼：<word src="D:/tpl/B.docx"/>， 渲染时会把 B 的 p 与 tbl 就地展开。

15.4 把生成结果导出成 HTML

WDocument doc = new WDocument(tmp);
doc.load();
String html = doc.html(uploader, 0);   // uploader 用来处理图片上传，可传 null

适合做「预览」：先生成 docx，再把同一份文档转成 HTML 给浏览器看。 注意这是结构级转换，复杂排版（浮动表格、文本框）不会完美还原。

15.5 组合拳：一个综合报表的套路

<!-- 1) 标题用 if 做分支 -->
<aol:if test="${type == 'A'}" value="A类销售报表" else="通用销售报表"/>

<!-- 2) 明细表格：模板行循环 + 序号 + 金额格式化 -->
<aol:for items="${明细}" var="r" scope="tr" status="st">
${st.count} | ${r.客户} | <aol:number value="${r.金额}" format="#,##0.00"/>
</aol:for>

<!-- 3) 合计行：放在循环外的独立行 -->
合计：<aol:sum data="${明细}" p="金额" format="#,##0.00" nvl="0"/>

<!-- 4) 空数据也要有交代 -->
<aol:if test="${明细} == null">（本期无数据）</aol:if>

<!-- 5) 生成时间 + 签章位 -->
打印时间：<aol:date evl="true" format="yyyy-MM-dd HH:mm"/>
<aol:mark name="签章"/>

<!-- 6) 图 -->
<aol:chart type="pie" title="销售分布" data="${图表数据}" categoryKey="name" valueKey="value"/>

顺序建议：标签的执行顺序是「按文档中出现的位置，从上到下」。 所以「先复制行、再算合计」天然成立；但如果你把 sum 放在 for 之前， 它算的还是原始数据（结果一样，因为 sum 不依赖循环结果）。 唯一要注意顺序的是 merge「登记 vs 执行」——它自动延迟，不用你管。

16. API 速查表

16.1 Word：org.anyline.office.docx.entity.WDocument

16.2 Excel：org.anyline.office.xlsx.entity.XWorkBook

16.3 常用标签属性一览（按用途记）

16.4 依赖与扩展点

16.5 最后：一段完整的可运行骨架

public void generate(Map<String,Object> data) throws Exception {
    // 1. 复制母版
    File tmp = File.createTempFile("rpt", ".docx");
    Files.copy(Paths.get("D:/tpl/report.docx"), tmp.toPath(), StandardCopyOption.REPLACE_EXISTING);

    try {
        // 2. 打开 + 配置
        WDocument doc = new WDocument(tmp);
        doc.setPlaceholderDefault("");
        doc.setImager(imager);           // 有二维码/条形码才需要
        doc.setDownloader(downloader);   // 有远程图片才需要

        // 3. 填数据
        for (Map.Entry<String,Object> e : data.entrySet()) {
            doc.variable(e.getKey(), e.getValue());
        }

        // 4. 生成（写回 tmp）
        doc.save();

        // 5. 交付
        Files.copy(tmp.toPath(), Paths.get("D:/out/report.docx"),
                   StandardCopyOption.REPLACE_EXISTING);
    } finally {
        tmp.delete();                    // 清理临时文件
    }
}

17. 容易误解的点（误解 → 事实）

这一节把最常被「想当然」的地方单独列出来。左边是大多数人第一反应会写的、右边是引擎的真实行为。 每一条都能在源码里找到依据，所以不要试图「试出来」——直接按事实写。

17.1 标签语法与机制

17.2 ${} 占位符

17.3 for 循环

17.4 if 判断

17.5 数值与聚合

17.6 格式化标签

17.7 集合处理与勾选/合并

17.8 图片 / 码 / 图表 / 分页

17.9 Excel 专属误解

17.10 文件与运行

18. 可复制示例集（模板 + Java 成对）

前面各章讲「知识点」，这一章讲「拿来就跑」。每个示例都由三块组成： ① 模板怎么摆（在 Word/Excel 里哪一行、哪个单元格写什么）→ ② Java 怎么准备数据 → ③ 结果长什么样 + 这一例最容易踩的坑。 字段名故意用中文，方便你对照自己的模板。

18.1 公共骨架（所有示例都从这里开始）

先复制这个通用方法，后面每个示例只管准备 data 和写模板：

import org.anyline.office.docx.entity.WDocument;
import org.anyline.entity.DataSet;
import org.anyline.entity.DataRow;
import java.io.File;
import java.nio.file.*;
import java.util.*;

/** 渲染入口：复制模板 → 灌数据 → 写回副本 */
public File render(File tpl, Map<String,Object> data) throws Exception {
    // 1) save() 会就地改写文件，必须先复制一份，绝不能在原始模板上渲染
    File tmp = File.createTempFile("rpt", ".docx");
    Files.copy(tpl.toPath(), tmp.toPath(), StandardCopyOption.REPLACE_EXISTING);

    // 2) 打开、配置、灌数据
    WDocument doc = new WDocument(tmp);
    doc.setPlaceholderDefault("");                 // 取不到值时输出空串，而不是把 ${} 留在文档里
    for (Map.Entry<String,Object> e : data.entrySet()) {
        doc.variable(e.getKey(), e.getValue());      // key 就是模板里 ${key} 的 key
    }

    // 3) 渲染（内部会跑标签 + 替换占位符）并写回 tmp
    doc.save();
    return tmp;                                    // 调用方把 tmp 拷到最终路径即可
}

数据有三种准备方式，按需要选：

再给一个省事的「造行」工具，后面示例都用它：

/** 快速造一行：map("name","张三","amount",1234.5) */
static Map<String,Object> map(Object... kv) {
    Map<String,Object> m = new LinkedHashMap<>();
    for (int i = 0; i < kv.length; i += 2) {
        m.put(String.valueOf(kv[i]), kv[i+1]);
    }
    return m;
}

/** 造一个 DataRow（给 group / max / min / concat 用） */
static DataRow row(Object... kv) {
    DataRow r = new DataRow();
    for (int i = 0; i < kv.length; i += 2) {
        r.put(String.valueOf(kv[i]), kv[i+1]);
    }
    return r;
}

18.2 示例 1：明细表（for + 序号 + 金额格式化）

模板——Word 里建一个 3 列表格：

【表格第 1 行 = 表头】 序号 | 客户 | 金额

【表格第 2 行 = 模板行，三个单元格分别写：】
  第 1 格： <aol:for items="${rows}" var="r" scope="tr" status="st">${st.count}
  第 2 格： ${r.customer}
  第 3 格： <aol:number value="${r.amount}" format="#,##0.00"/></aol:for>

Java：

List<Map<String,Object>> rows = new ArrayList<>();
rows.add(map("customer","张三", "amount", 1234.5));
rows.add(map("customer","李四", "amount", 890));
data.put("rows", rows);
// File out = render(new File("D:/tpl/report.docx"), data);

结果：

序号 | 客户 | 金额
1    | 张三 | 1,234.50
2    | 李四 | 890.00

• 序号用 ${st.count}（从 1）；${st.index} 是下标（从 0）。
• ${r.amount} 直接写只会输出 1234.5，千分位必须过 aol:number。
• scope="tr" 时，<aol:for> 开关标签要落在同一行的不同单元格里。

18.3 示例 2：合计 / 条数 / 平均值 / 最大值

模板——写在普通段落里即可：

条数：<aol:agg type="count" data="${rows}"/>
合计：<aol:sum data="${rows}" p="amount" format="#,##0.00" nvl="0"/>
前两条合计：<aol:sum data="${rows}" p="amount" end="1" format="#,##0.00" nvl="0"/>
客单价：<aol:agg type="avg" data="${rows}" p="amount" scale="2"/>
最大值：<aol:max data="${rows}" p="amount"/>

Java（max 需要 DataSet，这里统一用 DataSet）：

DataSet rows = new DataSet();
rows.add(row("customer","张三", "amount", 1234.5));
rows.add(row("customer","李四", "amount", 890));
rows.add(row("customer","王五", "amount", 2100));
data.put("rows", rows);

结果：条数 3；合计 4,224.50；前两条 2,124.50；客单价 1,408.17；最大值 2100。

• max / min / avg（标签）只认 DataSet，传 List 会整格空白 → 用 agg，或先把数据转成 DataSet。
• sum 遇到 "1,234"、"-" 这类脏数据会抛异常、整格空白 → 脏数据列改用 <aol:agg type="sum" .../>（内部容错跳过）。
• end="1" 表示「下标 0~1」，即前两条；切片在求和之前生效，这正是做「小计」的手法（做「总计」时不要加切片）。
• sum 的 nvl 只有 n 一个别名；min/max 没有别名。

18.4 示例 3：条件文字与空数据提示

模板（写在循环体里或独立段落）：

等级：<aol:if test="${r.amount >= 1000}" value="大额" else="普通"/>
统计：<aol:if test="${rows.size} == 0" value="本期无数据" else="共 ${rows.size} 条"/>

Java：同示例 1 的 rows，允许为空列表。

结果：等级：大额 / 统计：共 2 条；空列表时输出 统计：本期无数据。

• 想「不满足就删整行」的 remove="true" scope="tr" 在当前版本必然失败（内部先移除标签再取父节点，空指针被吞掉），请在 Java 侧过滤数据。
• 不写 else 时条件为假会留下空行 / 空段落，模板里要预留。
• 字符串比较必须写引号：test="${r.type == 'A'}"；写成 == A 会把 A 当变量名。

18.5 示例 4：固定 8 行（数据不足补空）

模板——和示例 1 同一个表格，模板行加 fill：

  第 1 格： <aol:for items="${rows}" var="r" scope="tr" status="st" fill="7">${st.count}
  第 2 格： ${r.customer}
  第 3 格： <aol:number value="${r.amount}" format="#,##0.00"/></aol:for>

Java：rows 只有 2 条（同上）。

结果：固定打印 8 行（2 条数据 + 6 行空白），模板行本身被移除。

• fill 是结束下标（从 0 计），要补到 8 行就写 fill="7"。
• 不要用「不写 items 的计数循环」来凑固定行数：源码在计数循环里把 remove 置成 false，会多残留一份未替换的模板行。要 N 行优先用 items + fill="N-1"。
• 补出来的空行里 ${r.xxx} 会是空串；行高/边框由模板行样式决定。

18.6 示例 5：纵向合并相同值（merge）

模板——3 列表格（部门 | 姓名 | 金额），模板行：

  第 1 格： <aol:for items="${rows}" var="r" scope="tr"><aol:merge scope="tc"/>${r.dept}
  第 2 格： ${r.name}
  第 3 格： ${r.amount}</aol:for>

Java：

List<Map<String,Object>> rows = new ArrayList<>();
rows.add(map("dept","研发部", "name","张三", "amount", 1000));
rows.add(map("dept","研发部", "name","李四", "amount", 2000));
rows.add(map("dept","市场部", "name","王五", "amount",  800));
data.put("rows", rows);

结果：前两行的「研发部」合并成一个跨 2 行的单元格。

• merge 必须写在被循环的模板行里，别写在表头行（扫描从模板行上一行开始）。
• 空值默认不参与合并；想把「连续空值合并」要先把它们统一成某个标记值，再用 ignore 排除真正不该合并的。
• by 用文本匹配时只看首行，匹配失败会静默「多合并」；能用下标就用 by="0"。

18.7 示例 6：勾选框 / 选中项（checkbox）

模板：

勾选展示：<aol:checkbox data="${depts}" value="${selected}" vk="CODE" tk="NM" vol="4"/>
纯文本  ：<aol:checkbox data="${depts}" value="${selected}" vk="CODE" tk="NM" type="text" split=","/>

Java：

List<Map<String,Object>> depts = new ArrayList<>();
depts.add(map("CODE","D1", "NM","研发部"));
depts.add(map("CODE","D2", "NM","市场部"));
depts.add(map("CODE","D3", "NM","财务部"));
data.put("depts", depts);
data.put("selected", Arrays.asList("D1","D3"));   // 多选；单选可传字符串 "D1"

结果：☑研发部 □市场部 ☑财务部（按 vol 每行 4 个换行）；第二行输出纯文本 研发部,财务部。

• 比值只认 valueKey（vk）：写成 vk="CODE"；rely 只决定「是否为 true/checked/空串」的额外判断。
• 选项行里 rely 列若是空串会被判为「选中」，白送一个勾——不打算用 rely 就别写它。
• data 必须是 Collection<Map>，传单个 Map 什么都不输出；textKey 默认 NM。

18.8 示例 7：二维码与图片（qr / img）

模板：

<aol:qr value="${url}" style="width:120px;height:120px;"/>
<aol:img src="${logo}" style="width:150px;height:100px;"/>

Java——这两个标签必须额外注入依赖：

WDocument doc = new WDocument(tmp);
doc.setImager(myImager);          // 二维码/条形码：自己实现 Imager，不注入就不插图
doc.setDownloader(myDownloader);  // 远程图片：自己实现 Downloader，不注入则下载失败
doc.variable("url",  "https://anyline.org");
doc.variable("logo", "D:/img/logo.png");                 // 本地图片
// doc.variable("logo", "https://cdn.xx.com/logo.png");  // 远程图片（走 Downloader）
doc.save();

• 本库不自带 Imager / Downloader 实现，不注入就静默不渲染，也不报错。
• qr/bar 生成的是临时文件，插入后立即删除，别依赖那个路径。
• style 里的 px 会被去掉；img 的 src 支持 ${}。

18.9 示例 8：图表（chart）

模板——chart 是自闭合标签，写在正文段落里即可：

<aol:chart type="bar" title="月度销量" data="${chartData}"
           categoryKey="name" valueKey="value"
           width="5715000" height="3429000"/>

Java：

List<Map<String,Object>> chartData = new ArrayList<>();
chartData.add(map("name","1月", "value", 120));
chartData.add(map("name","2月", "value", 200));
chartData.add(map("name","3月", "value", 150));
data.put("chartData", chartData);

结果：一张 600×360 像素左右的柱状图。

• data 必须整个属性就是一个 ${}（data="${chartData}"）；data="前缀${x}" 不会求值。
• 宽高单位是 EMU（1px≈9525）：5715000≈600px，写 600 会几乎看不见。
• t / d 别名和 type / data 冲突，一律写全名；type 拼错会静默降级成饼图。

18.10 示例 9：分组小计（group + agg）

模板——先在空白段写一行分组指令，再用一个 3 列表格渲染：

<aol:group data="${rows}" by="dept" var="groups"/>

【表格第 1 行 = 表头】 部门 | 笔数 | 金额小计

【表格第 2 行 = 模板行】
  第 1 格： <aol:for items="${groups}" var="g" scope="tr">${g.dept}
  第 2 格： <aol:agg type="count" data="${g.items}"/>
  第 3 格： <aol:sum data="${g.items}" p="amount" format="#,##0.00" nvl="0"/></aol:for>

Java（group 需要 DataSet）：

DataSet rows = new DataSet();
rows.add(row("dept","研发部", "name","张三", "amount", 1000));
rows.add(row("dept","研发部", "name","李四", "amount", 2000));
rows.add(row("dept","市场部", "name","王五", "amount",  800));
data.put("rows", rows);

结果：研发部 | 2 | 3,000.00；市场部 | 1 | 800.00。

• group 只认 DataSet，传 List 会静默不分组。
• group 自己不输出任何文字，必须写 var，再用 for 渲染。
• 每个分组的成员放在固定的属性名 items 里，即 ${g.items}。
• extract="true" 会把成员从原集合真正移除，要保留原数据就先传副本。

18.11 示例 10：去重拼接（concat）

模板：

参与部门：<aol:concat data="${rows}" p="dept" split="、" ds="dept"/>

Java：rows 同上（DataSet，dept 有重复行）。

结果：参与部门：研发部、市场部（已去重）。

• concat 必须 DataSet，且必须写 p（列名）；用 ds 去重。
• 不需要写在 for 里，一个单元格 / 一个段落放一个即可。

18.12 示例 11：Excel 版（XWorkBook）

模板（report.xlsx 里）：

A1: 销售报表
A3: 姓名        B3: 金额          C3: 部门
A4: <aol:for items="${rows}" var="r">${r.name}
B4: <aol:number value="${r.amount}" format="#,##0.00"/>
C4: ${r.dept}</aol:for>

Java：

File tmp = File.createTempFile("rpt", ".xlsx");
Files.copy(Paths.get("D:/tpl/report.xlsx"), tmp.toPath(), StandardCopyOption.REPLACE_EXISTING);

XWorkBook book = new XWorkBook(tmp);
book.variable("title", "2026 年销售报表");
book.variable("rows", rows);      // List
book.save();                              // 合并占位符 → 解析标签 → 替换 → 写回原文件

结果：第 4 行按数据条数向下展开。

• 单元格里只有 aol:number / aol:date 真正可用；sum / if / checkbox / … 一律无效（它们只实现 run()，而单元格走的是文本 parse()）。
• Excel 的 for 只支持整行循环：scope / begin / end / fill / status 全部无效；状态变量固定叫 s，用 ${s.count}。
• 合计建议用 Excel 自己的公式（=SUM(B4:B100)），或在 Java 侧算好用 book.variable("合计", v) 传进来。
• 公式、数字、布尔、日期单元格不参与替换，标签只能写在文本单元格里。

18.13 一页速查：模板片段 → 你会得到什么