模板语法

变量是模板中的占位符，生成时会被多维表格记录中的真实数据替换。

基础语法

用大括号包住准确的字段名：

{Field_Name}

示例：

• {Customer_Name} → “Acme Corp”
• {Invoice_Date} → “2024-01-15”
• {Total_Amount} → “1,500.00”

提示

使用 AutomaDoc 插件中的变量页面，可以浏览全部可用字段，并一键复制准确的语法。

支持的字段类型

类别	字段类型	默认输出
文本	文本、邮箱、条码字段	原样输出
数字	数字、货币、进度（%）、评分	按飞书格式（例如 $1,234.56）
日期/时间	日期、创建时间、修改时间	按飞书格式（遵循时区设置）
选择	单选、多选	文本 / 逗号分隔
人员	人员、创建人、修改人、群组	显示名称
联系方式	电话、链接	电话号码 / 链接地址
复选框	是/否	true / false
附件	文件与图片	参见动态图片
关联记录	访问关联表中的数据	参见关联记录
查找引用	从关联记录中获取的值	解析后的值
公式	计算字段（文本、数字、日期）	取决于结果类型

关联记录（嵌套字段）

使用点号语法访问关联记录中的字段：

{Customer.Name}
{Customer.Address}
{Customer.Email}

最多支持 5 层嵌套：

{Order.Customer.Company.Address.City}

字段的扩展属性（点号语法）

部分字段类型可以通过点号语法访问子属性。不使用点号时，它们会输出默认值。

链接字段

{Website}          → "https://example.com" (链接地址)
{Website.text}     → "Example Site" (链接文字)
{Website.link}     → "https://example.com" (链接地址)

人员 / 创建人 / 修改人

创建人和修改人只含单个用户，可直接使用点号语法。而 User（人员） 字段始终是列表——即使只有一个人——因此 {Assignee.name} 取不到值，请改用下标或循环：

{Created_By}            → "John Doe"
{Created_By.name}       → "John Doe"
{Created_By.en_name}    → "John Doe" (英文名)
{Created_By.id}         → "ou_abc123"

{Assignee}              → "John Doe, Jane Roe"
{Assignee[0].name}      → "John Doe"
{Assignee[0].en_name}   → "John Doe" (英文名)
{Assignee[0].id}        → "ou_abc123" (飞书用户 ID)

需要列出全部人员时请使用循环：

{#Assignee}
  {name} ({en_name})
{/Assignee}

地理位置字段

{Office}                → "Headquarters, 123 Main St, City"
{Office.name}           → "Headquarters"
{Office.full_address}   → "123 Main St, City, Country"
{Office.address}        → "123 Main St"

群组字段

群组字段同样是列表，{Team.name} 取不到值，请改用下标或循环：

{Team}          → "Engineering, Design" (逗号分隔的群组名)
{Team[0].name}     → 第一个群组名
{Team[0].id}       → 第一个群组 ID

遍历全部群组请使用循环：

{#Team}
  {name} (ID: {id})
{/Team}

多选字段

多选字段可以循环遍历，也可以用自定义分隔符连接：

{Tags}                  → "Red, Blue, Green" (默认逗号分隔)
{Tags | join:" / "}     → "Red / Blue / Green"
{#Tags}
  - {.}
{/Tags}

数字与日期字段（过滤器覆盖格式）

数字与日期/时间字段默认按飞书的格式显示。一旦应用过滤器，就会改用原始值（真实数字或时间戳），并完全覆盖飞书的格式：

{Price}                 → "$1,234.50" (飞书格式)
{Price | number:2}      → "1,234.50" (原始数字，重新格式化)
{Price | currency:"EUR":"de-DE"} → "1.234,50 €" (原始数字，德语区格式)

{Date}                  → "2026/02/26" (飞书格式)
{Date | date:"DD MMM YYYY"}     → "26 Feb 2026" (原始时间戳，重新格式化)

未使用过滤器的字段，始终保持飞书的原始格式。

循环（多值关联字段）

对于关联多条记录的字段，使用循环语法为每一项重复内容：

{#Line_Items}
  Product: {Product_Name}
  Quantity: {Quantity}
  Price: {Price}
{/Line_Items}

{#Field} 开始循环，{/Field} 结束循环。循环内部引用字段时不需要加上父级前缀。

简写结束标签

可以用 {/} 代替重复写字段名：

{#Line_Items}
  {Product_Name} - {Price}
{/}

表格行展开

当循环标签放在表格行内时，整行会为每一项复制一次——非常适合明细表：

Product	Qty	Price
{#Line_Items} {Product_Name}	{Quantity}	{Price} {/Line_Items}

基础类型数组

对于简单值（而非对象）组成的数组，用 {.} 引用当前项：

{#Tags}
  {.}
{/Tags}

循环元数据

在任意循环内部，可以使用以下特殊变量：

变量	说明	示例
{$index}	当前索引（从 0 开始）	0、1、2 ……
{$num}	行号（从 1 开始）	1、2、3 ……
{$first}	第一项时为 true	输出 true / false
{$last}	最后一项时为 true	输出 true / false

警告

循环变量可以输出自身的值，但不能用在条件里——{#if $num} 和 {#if $first} 不会被识别，会原样出现在文档中。{#if …} 只接受字段名。

嵌套循环

循环可以嵌套。内层循环可以访问外层作用域中的字段：

{#Departments}
  Department: {Name}
  {#Employees}
    {Name} works in {Department.Name}
  {/Employees}
{/Departments}

如果同一个字段名在内层和外层都存在，内层优先。

条件内容

根据字段值显示或隐藏内容。

非空判断

仅当字段有值时显示内容：

{#if Discount}
  Discount applied: {Discount}
{/if}

为空判断（取反）

仅当字段为空时显示内容：

{#if !Notes}
  No additional notes.
{/if}

相等判断

{#if Status == "Approved"}
  This invoice has been approved.
{/if}

不等判断

{#if Status != "Draft"}
  This document has been submitted.
{/if}

过滤器

过滤器用竖线（|）语法改变值的显示方式：

{Field | filterName}
{Field | filterName:"arg1":"arg2"}

过滤器在取到值之后、写入文档之前生效。未使用过滤器时，值按飞书的默认格式显示。

字符串过滤器

过滤器	说明	示例	输出
upper	转为大写	{Name | upper}	ACME CORP
lower	转为小写	{Name | lower}	acme corp
capitalize	每个单词首字母大写	{Name | capitalize}	Acme Corp
trim	去除首尾空格	{Name | trim}	Acme Corp
truncate	截断到指定长度（默认 50）	{Description | truncate:16}	Lorem ipsum dolo...
pad	用指定字符补位（默认 0）	{$num | pad:3}	001

数字过滤器

所有数字过滤器都可以接受一个可选的地区参数，用于按地区格式化：

过滤器	参数	示例	输出
number	小数位数、地区	{Price | number:2}	1,234.50
number	小数位数、地区	{Price | number:2:"de-DE"}	1.234,50
currency	货币代码、地区	{Price | currency:"USD"}	$1,234.50
currency	货币代码、地区	{Price | currency:"EUR":"de-DE"}	1.234,50 €
currency	货币代码、地区	{Price | currency:"JPY":"ja-JP"}	￥1,235
percent	小数位数、地区	{Rate | percent:1}	45.6%
percent	小数位数、地区	{Rate | percent:1:"de-DE"}	45,6 %

注意

数字与日期过滤器使用飞书返回的原始值，而不是已格式化的显示文本。因此无论飞书如何显示，您都可以自由地重新格式化数字与日期。

日期过滤器

用自定义格式输出日期——当飞书内置格式不符合需求时非常有用。

语法： {Field | date:"format":"timezone":"locale"}

所有参数都是可选的。时区默认为 UTC，地区默认为 en-US。

过滤器	参数	示例	输出
date	格式、时区、地区	{Date | date:"DD MMM YYYY"}	26 Feb 2026
date	格式、时区、地区	{Date | date:"dddd, DD MMMM YYYY"}	Thursday, 26 February 2026
date	格式、时区、地区	{Date | date:"DD MMMM YYYY":"UTC":"fr-FR"}	26 février 2026
date	格式、时区、地区	{Date | date:"dddd, DD MMMM YYYY":"UTC":"de-DE"}	Donnerstag, 26 Februar 2026

支持的日期占位符：

占位符	输出	示例
YYYY	四位年份	2026
MMMM	月份全称（随地区变化）	February、février、Februar
MMM	月份缩写（随地区变化）	Feb、fév、Feb
MM	两位月份	02
dddd	星期全称（随地区变化）	Thursday、Donnerstag、木曜日
ddd	星期缩写（随地区变化）	Thu、Do、木
DD	两位日期	26
HH	24 小时制小时	15
mm	分钟	30
ss	秒	00

示例：

{Invoice_Date | date:"DD MMM YYYY"}                         → 26 Feb 2026
{Invoice_Date | date:"YYYY-MM-DD"}                          → 2026-02-26
{Invoice_Date | date:"MM/DD/YYYY"}                          → 02/26/2026
{Invoice_Date | date:"DD/MM/YYYY":"Asia/Tokyo"}             → 26/02/2026 (东京时区)
{Invoice_Date | date:"dddd, DD MMMM YYYY":"UTC":"ja-JP"}    → 木曜日, 26 2月 2026
{Invoice_Date | date:"DD MMMM YYYY":"UTC":"id-ID"}          → 26 Februari 2026

其他过滤器

过滤器	说明	示例	输出
join	连接数组值（默认 , ）	{Tags | join:" / "}	Red / Blue / Green
default	空值时的兜底文本	{Phone | default:"N/A"}	N/A

串联过滤器

多个过滤器可以用竖线串联，从左到右依次生效：

{Name | trim | upper}             → "  hello  " 变成 "HELLO"
{$num | pad:3}                    → 1 变成 "001"
{Phone | default:"N/A" | upper}   → null 变成 "N/A"

在循环中使用过滤器

过滤器同样适用于循环变量和当前项引用：

{#Items}
  #{$num | pad:3} - {Name | upper}
{/Items}

{#Tags}{. | capitalize}, {/Tags}

动态图片

把模板中的占位图片替换成附件字段中的真实图片：

1. 在 Word 模板中插入任意一张图片（作为占位图）。
2. 右键点击图片 → 编辑替代文字。
3. 在替代文字描述中填写 {FieldName}。
4. 保存模板。

生成时，占位图会被附件字段中的真实图片替换，并保留占位图的尺寸。

注意

替代文字中可以包含其他文字，例如 Company Logo {Logo}。

多张图片

对于包含多个附件的字段，可使用索引语法：

{Photo}      → 第一张图片（等同于 {Photo[0]}）
{Photo[1]}   → 第二张图片
{Photo[2]}   → 第三张图片

遍历所有图片

如果附件数量不固定，可以用循环语法，并把 {.} 作为图片的替代文字。每个附件都会展开为一份占位图的副本：

{#Product_Photos}
  [替代文字为 {.} 的图片]
{/Product_Photos}

放在表格中时，每个附件会各占一行：

#	Photo	Filename
{#Product_Photos} {$num}	替代文字：{.}	{name} {/Product_Photos}

循环内部可用的属性：

变量	说明	示例
{name}	文件名	photo1.jpg
{type}	MIME 类型	image/jpeg
{size}	文件大小（字节）	204800

注意

固定数量的排版仍然可以使用硬编码的索引语法（{Photo[0]}、{Photo[1]}），适用于明确知道要展示几张图片的场景。

关联记录循环中的图片

图片占位符同样可以在循环块中使用，每次迭代都会解析该项对应的图片：

{#Employees}
  Name: {Name}
  Photo: [替代文字为 {Photo} 的图片]
{/Employees}

二维码与条形码

根据字段值生成二维码和条形码。配置方式与动态图片相同——通过图片的替代文字设置。

二维码

{QR:FieldName}

示例：{QR:Order_ID} 会生成一个包含 Order_ID 值的二维码。

条形码

语法	类型	说明
{BARCODE:FieldName}	Code128	默认类型，支持字母与数字
{BARCODE128:FieldName}	Code128	显式指定 Code128
{BARCODE39:FieldName}	Code39	仅支持大写字母与数字
{BARCODEEAN13:FieldName}	EAN-13	13 位零售商品码
{BARCODEEAN8:FieldName}	EAN-8	8 位短版 EAN
{BARCODEUPCA:FieldName}	UPC-A	12 位北美零售码
{BARCODEUPCE:FieldName}	UPC-E	压缩版 UPC
{BARCODEITF14:FieldName}	ITF-14	物流／整箱条码
{BARCODEDATAMATRIX:FieldName}	DataMatrix	二维码，信息密度高
{BARCODEPDF417:FieldName}	PDF417	二维码，堆叠线性码

前缀不区分大小写——{qr:Field} 与 {QR:Field} 效果相同。

页眉与页脚

所有占位符语法在页眉和页脚中同样有效，用法与正文一致。

常见用途：

• 页眉中的公司名称或 Logo
• 页脚中的文档编号或日期
• 动态标题，例如 Invoice for {Customer_Name}

添加方式：插入 → 页眉/页脚 → 编辑，然后输入 {Field_Name} 之类的占位符。

语法速查

语法	说明
{Field}	普通变量
{Field.Nested}	关联记录字段（点号语法）
{URL.text} / {URL.link}	链接字段子属性
{Created_By.name} / {Assignee[0].name}	人员字段子属性
{Location.name} / {Location.full_address}	地理位置子属性
{Team[0].name} / {Team[0].id}	群组字段子属性
{#Field}...{/Field}	遍历多值字段
{/}	简写结束标签（关闭最近的循环）
{.}	循环中的当前项（用于基础类型数组）
{$index}	循环索引（从 0 开始）
{$num}	行号（从 1 开始）
{$first} / {$last}	是否为首项／末项
{#if Field}...{/if}	条件（非空）
{#if !Field}...{/if}	条件（为空）
{#if Field == "val"}...{/if}	条件（相等）
{#if Field != "val"}...{/if}	条件（不等）
{Field | upper}	过滤器：转大写
{Field | lower}	过滤器：转小写
{Field | capitalize}	过滤器：单词首字母大写
{Field | trim}	过滤器：去除首尾空格
{Field | truncate:30}	过滤器：截断并加省略号
{Field | pad:3}	过滤器：补零
{Field | number:2}	过滤器：指定小数位数
{Field | number:2:"de-DE"}	过滤器：按地区格式化数字
{Field | currency:"USD"}	过滤器：货币格式
{Field | currency:"EUR":"de-DE"}	过滤器：按地区格式化货币
{Field | percent:1}	过滤器：百分比
{Field | date:"DD MMM YYYY"}	过滤器：自定义日期格式
{Field | date:"dddd, MMMM DD":"UTC":"fr-FR"}	过滤器：按地区格式化日期
{Field | join:" / "}	过滤器：用分隔符连接数组
{Field | default:"N/A"}	过滤器：兜底值
{Field | trim | upper}	串联过滤器（从左到右）
{Photo} / {Photo[1]}	图片（通过替代文字）
{QR:Field}	二维码（通过替代文字）
{BARCODE:Field}	条形码（通过替代文字）