Word 模板 token 参考

Word 模板中可使用的数据路径（绑定）完整列表。本页对应产品内的 token 参考面板以及校验器所强制执行的绑定目录——如果某个路径未在此列出，编辑器会将其标记出来。语法和格式化器请参见 Word Template Mode。

如何阅读本页

标量绑定用于值 token：${issue.summary}。
集合绑定用于循环：${#each issue.subtasks as sub}…${/each}。在循环内部，通过循环变量访问项目字段：${sub.key}。
层级 —— A 为普遍可用；B 之所以提供，仅因为问题数据包中本就带有这些数据；C 可见但不可绑定，列出它们是为了如实说明产品范围。
可用的根取决于导出上下文。

导出上下文及其根

Word 模板运行在七种上下文之一，每种上下文暴露一组不同的顶层根。

上下文	可用的根
`single-issue`	`issue`、`generatedAt`
`automation`（Jira Automation 操作）	`issue`、`generatedAt`
`multi-issue`（JQL / 看板）	`issues`、`issueGroups`、`generatedAt`
`scheduled`	`issues`、`issueGroups`、`generatedAt`
`sprint`	`issues`、`issueGroups`、`sprint`、`generatedAt`
`release`	`issues`、`issueGroups`、`release`、`generatedAt`
`backlog`	`issues`、`issueGroups`、`backlog`、`generatedAt`

generatedAt（日期时间）在所有上下文中都可用。

层级 A —— 问题数据面（`issue.*`）

在 single-issue 和 automation 中可用。相同的字段也是 issues 集合中每一项的结构——在 ${#each issues as it} 内部使用 ${it.key}、${it.summary} 等。

标量

路径	类型
`issue.key`	字符串
`issue.summary`	字符串
`issue.description`	富文本（ADF）
`issue.status`	状态
`issue.status.category`	字符串
`issue.priority`	优先级
`issue.assignee`	用户
`issue.assignee.displayName`	字符串
`issue.reporter`	用户
`issue.reporter.displayName`	字符串
`issue.created`	日期时间
`issue.updated`	日期时间
`issue.dueDate`	日期
`issue.parent.key`	字符串
`issue.parent.summary`	字符串
`issue.parent.status`	字符串

用户类型的值默认渲染显示名；可使用 user 格式化器选取其中一部分，例如 ${issue.assignee | user("displayName")}。富文本值会带格式渲染；使用 | plain() 可去除格式。

集合

集合	项目字段（相对于循环变量）
`issue.labels`	基本类型列表 —— 循环变量本身就是标签字符串
`issue.components`	`name`
`issue.fixVersions`	`name`、`released`（布尔值）
`issue.affectsVersions`	`name`
`issue.subtasks`	`key`、`summary`、`status`、`priority`、`assignee`、`dueDate`
`issue.comments`	`author`（用户）、`author.displayName`、`body`（ADF）、`created`、`updated`
`issue.attachments`	`filename`、`mimeType`、`size`、`isImage`、`created`、`author.displayName` —— 仅元数据，不含二进制内容，也不含 URL
`issue.issueLinks`	`typeName`、`direction`、`linkedIssue.key`、`linkedIssue.summary`、`linkedIssue.status`
`issue.worklogs`	`author.displayName`、`timeSpent`、`timeSpentSeconds`、`created`、`started`

示例：

${#each issue.worklogs as wl}
${wl.author.displayName}: ${wl.timeSpentSeconds | duration("hm")} on ${wl.started | date("yyyy-MM-dd")}
${/each}

层级 A —— 多问题根

在 multi-issue、scheduled、sprint、release 和 backlog 中可用。

路径	种类	项目字段
`issues`	集合	完整的问题数据面，相对于循环变量
`issueGroups.fixVersions`	集合	`key`、`title`、`issues`
`issueGroups.sprints`	集合	`key`、`title`、`issues`
`issueGroups.assignees`	集合	`key`、`title`、`issues`
`issueGroups.worklogAssignees`	集合	`key`、`title`、`issues`

示例 —— 先分组，再遍历每组内的问题：

${#each issueGroups.assignees as group}
## ${group.title}
${#each group.issues as it}
- ${it.key}: ${it.summary}
${/each}
${/each}

层级 A —— 上下文数据包根

仅在各自的上下文中可用。

`sprint`

路径	类型
`sprint.sprint.name`	字符串
`sprint.sprint.goal`	字符串
`sprint.sprint.state`	选项
`sprint.stats.issueCount`	数字
`sprint.stats.percentDone`	数字

`release`

路径	类型
`release.release.name`	字符串
`release.release.releaseDate`	日期
`release.release.released`	布尔值
`release.stats.issueCount`	数字
`release.stats.percentDone`	数字

`backlog`

路径	类型 / 项目字段
`backlog.board.boardName`	字符串
`backlog.board.boardType`	选项
`backlog.stats.totalIssueCount`	数字
`backlog.groups`	集合 —— `kind`、`name`、`issueCount`、`issues`

层级 A —— 元数据

路径	类型	上下文
`generatedAt`	日期时间	全部

层级 B —— 变更历史

路径	种类	项目字段
`issue.changeHistory`	集合	`author.displayName`、`created`、`items`

层级 C —— 可见但不可绑定

这些在概念上存在，但无法解析；列出它们是为了让编辑器和校验能够如实说明适用范围。

能力	说明
`issue.jsm`	Jira Service Management 的请求、SLA 和审批数据面——已推迟。
模板内 JQL	由迁移扫描器检测并给出诊断，绝不执行。
Tempo	工作日志上可能存在 Tempo 镜像，但未提供绑定。
Xray / Zephyr	测试管理字段需要第三方应用。
Assets / Insight	对象字段已推迟。

自定义字段

自定义字段在单一命名空间下可绑定：

${ issue.customFields.<fieldId>.<…> }

未知的自定义字段 id 属于软性问题：编辑器会显示警告，值可能渲染为空，但绝不会硬性阻断——因此模板可以引用当前站点恰好没有的字段而不会失败。
裸路径 issue.customFields（整个映射）绝不可绑定。
只允许使用安全的标识符字符；__proto__、prototype 和 constructor 片段会被拒绝。

从 Xporter 迁移时的注意事项

迁移扫描器会为常见的 Xporter 字段名建议对应的 Exportelier 路径。要让建议的改写真正可解析，有两点需要注意：

自动转换修正的是语法，而不是路径是否存在。 改写具有正确的形态，但目标仍必须是本页中真实存在的绑定，否则会产生 unknown-binding 警告：
- 不在目录中： Creator → issue.creator、Resolution → issue.resolution、Project → issue.project、IssueType/Type → issue.issuetype。
- 大小写不匹配： DueDate 会被建议为 issue.duedate，但实际绑定是 issue.dueDate。
- 类型不匹配： Labels 被建议为标量，但 issue.labels 是集合——请使用循环。
问题链接。 别名 Links 会被建议为 links，但真实绑定是 issue.issueLinks。

完整的迁移对照表请参见 Xporter 语法：哪些可用。

绝不允许的路径

出于安全考虑，某些路径无论在何种上下文中都会以 unsafe-template 错误被拒绝——即内部字段、凭据字段或包含 URL 的字段。其中包括 auth、context、forge、internal、secrets、storage 和 token 等根，以及任何以 accountId、apiToken、avatarUrl、baseUrl、contentUrl、thumbnailUrl、cookie、session、headers、private 或 storageRef 结尾的路径。只要坚持使用本页列出的绑定，就不会遇到这些问题。

如何阅读本页​

导出上下文及其根​

层级 A —— 问题数据面（issue.*）​

标量​

集合​

层级 A —— 多问题根​

层级 A —— 上下文数据包根​

sprint​

release​

backlog​

层级 A —— 元数据​

层级 B —— 变更历史​

层级 C —— 可见但不可绑定​

自定义字段​

从 Xporter 迁移时的注意事项​

绝不允许的路径​