aol:for 的 var 属性使用说明

适用模块：anyline-office / docx 模板渲染 · 标签：<aol:for>

1. 作用

var 声明循环迭代变量名。标签每遍历一行（一个元素），就把当前行的数据对象绑定到该变量上， 循环体内通过 var.字段 访问当前行的列值。 

<aol:for items="${list}" var="item">${item.NAME}</aol:for>

等价语义：for (Object item : list) { ... } —— item 就是「当前行上下文」。

  • 不写 var：Context.variable(null, item) 会被忽略，当前行不会被绑定，循环体只能靠 status 变量。
  • 属性值本身支持 ${}，可用动态变量名，如 var="${prefix}"。

2. 基本语法 

<aol:for items="${集合或JSON}" var="item" status="s" scope="body|td|tc|tr|table">
    ... 循环体：${item.字段} / ${s.index} / ${s.count} ...
</aol:for>

3. 相关属性一览

属性 别名 默认 说明
var — 无 迭代变量名，绑定当前行
items data d is 无 数据源，集合 / JSON 数组字符串 / 逗号分隔字符串
status s 无 循环状态变量名，绑定 index/count/prev/next
scope sp body 遍历范围：标签体 / 单元格 / 行列 / 行 / 表格
begin start b 0 起始下标
end e 无 结束下标（计数循环必填）
step — 1 步长
fill — 无 数据不足时补空行到指定条数
qty q 无 只取指定数量
index i 无 只取指定下标的那一条
selector st 无 只取指定列（BeanUtil.selects）
distinct ds 无 按列去重
formatDate fd 无 数据源指定字段的日期格式化
remove — true 无数据时是否删除模板行
flatten flat fl false 把当前行属性平铺到上下文，可用 ${字段} 直接访问（见第 6 节）

4. 用法示例

文本循环 

<aol:for items="${users}" var="u">${u.NAME}(${u.AGE}) </aol:for>

表格按行循环（最常用） 

<aol:for items="${rows}" var="r" scope="tr">
  序号：${s.count}，名称：${r.NM}，数量：${r.QTY}
</aol:for>

嵌套循环

子上下文的 parent 指向外层，内层可直接引用外层变量： 

<aol:for items="${depts}" var="d">
  <aol:for items="${d.USERS}" var="u">${d.NAME} - ${u.NAME}</aol:for>
</aol:for>

计数循环

var 绑定的是下标整数（不是行数据）： 

<aol:for var="i" begin="1" end="5">第${i}行 </aol:for>

动态变量名 

<aol:for items="${list}" var="${prefix}_item">${x_item.NAME}</aol:for>

5. status 状态变量

status（别名 s）绑定一个 Map，键固定为：

键 含义
index 当前下标（绝对下标 i，计数循环里即当前计数值）
count 第几次迭代，从 1 开始
prev 上一条数据（集合循环）；计数循环里是上一个数
next 下一条数据；计数循环里是下一个数
注意 index 是绝对下标而非相对序号，配 begin 使用时两者可能不同，序号建议用 count。 
<aol:for items="${rows}" var="r" status="s">
  ${s.count}/${s.index}  ${r.NM}
</aol:for>

6. 与 flatten 的关系

默认需要写 var.字段。开启 flatten="true" 后，当前行的一级属性会平铺进上下文，可直接写 ${字段}： 

<!-- 两种写法等效 --> <aol:for items="${rows}" var="r" flatten="true">${NM}</aol:for>
<aol:for items="${rows}" var="r">${r.NM}</aol:for>

平铺规则：index/count/prev/next 及 var、status 名不会被覆盖；务必保证属性全局唯一时才可以启用（如利用各级编码+列名计算的md5值），平铺键会遮蔽同名外层变量，退出本轮自动恢复。

7. 常见坑

  1. 键名大小写必须完全一致：占位符是精确匹配，数据集列名经 KeyAdapter 转换后（如统一大写）模板里就得写 ${item.NAME}，否则取到空。
  2. 未设 var 时 item 不可用：循环体里写 ${item.x} 会解析为空，需显式声明 var。
  3. 计数循环的 var 是数字：${i.NAME} 无意义，只有 begin/end 而没有 items 时走的是计数模式。
  4. prev/next 边界：首条无 prev、末条无 next，取值前需判空（如 <aol:if test="null != s.prev">）。
  5. var 作用域仅限本轮：退出循环后该变量不再存在，循环外的 ${item.x} 取不到值。
  6. 嵌套同名 var：内层会遮蔽外层同名变量，建议内外层用不同变量名。