Xporter 语法：哪些可用
本页如实说明当您将 Word 文档上传到 Word Template Mode 时，Xporter 风格的模板语法会被如何处理。它对应每次上传都会运行的迁移扫描器——与您在编辑器兼容性报告中看到的分类完全一致。
诚实的承诺
Exportelier 不兼容 Xporter，不是 Xporter 的替代品，也不会运行 Xporter 模板。它所做的是帮助您迁移：上传时，扫描器会识别常见的 Xporter 风格语法，并逐个结构地告诉您它是已经可用、可以自动转换、需要手动改写，还是按设计不在支持范围内。
两条硬性保证：
- 外部语法只被识别，绝不被执行。 扫描器读取的是结构的形态——
#{for …}、${dateformat(…)}——上传模板中的任何内容都不会作为代码求值。 - 不复制任何厂商代码。 检测模式和别名建议均由 Exportelier 基于公开记录的语法形态自行编写。
每项发现都归入以下四类之一。
1. 原样支持
如果您的模板已经使用 Exportelier 的规范语法，它就能直接工作。这类结构只会产生一条信息提示，而不是警告。
| 结构 | 示例 |
|---|---|
| 值 token | ${issue.key} |
| 循环 | ${#each issue.subtasks as sub}…${/each} |
| 条件 | ${#if issue.assignee}…${#else}…${/if} |
2. 可自动转换
具有安全一对一等价形式的常见 Xporter 语法。编辑器会显示警告，并提供可复制的替换内容。
| Xporter 结构 | Exportelier 对应形式 | 说明 |
|---|---|---|
${Key}、${Summary}、${Status}、… | ${issue.key}、${issue.summary}、${issue.status}、… | 标量字段别名。 |
${Assignee.displayName} | ${issue.assignee.displayName} | 已知的根别名；路径的其余部分保持不变。 |
#{for comments} | ${#each comments as c} | 循环开始。 |
#{if(Assignee)} | ${#if issue.assignee} | 简单的真值条件。 |
#{else} | ${#else} | Else 标记。 |
可识别的标量别名（16 个）： Key、Summary、Description、Status、Priority、Resolution、Assignee、Reporter、Creator、Created、Updated、DueDate、IssueType、Type、Project、Labels。
可识别的集合别名（5 个）： Comments、Attachments、Subtasks、Links、Worklogs。
建议的改写具有正确的形态，但目标仍必须是 token 参考中真实存在的绑定。部分别名需要手动调整：
- 不可绑定：
Creator→issue.creator、Resolution→issue.resolution、Project→issue.project、IssueType/Type→issue.issuetype。这些都不是 Tier-A 绑定。 - 大小写不匹配：
DueDate会被建议为issue.duedate；实际绑定是issue.dueDate。 - 类型不匹配：
Labels被建议为标量，但issue.labels是集合——请使用${#each issue.labels as l}…。 - 问题链接：
Links会被建议为links，但真实绑定是issue.issueLinks。
3. 不支持但可解释
没有清晰的一对一映射，但有明确的方式表达相同意图。编辑器会说明改写方法；这是警告，而不是阻断项。
| Xporter 结构 | 原因 | 替代做法 |
|---|---|---|
${Comments[0].Body} | 路径不支持方括号索引。 | 改为迭代：${#each comments as c}${c.body}${/each}。 |
#{end} | 通用的单一终止符。 | 请使用匹配的结束标记——${/each} 或 ${/if}。 |
#{if(votes > 0)} | 条件只判断单个路径的真值——不支持运算符。 | 改为判断是否存在：${#if issue.votes}。 |
#{elseif(…)} | 不存在 elseif。 | 请嵌套条件。 |
任何其他 #{…} 指令 | 无法识别。 | 请替换为 ${…} 语法。 |
不成对的 ${#each}/${/if}、错误路径、未闭合的 ${ | 由解析器捕获。 | 请修正该 token；报告会显示准确位置。 |
4. 不安全或不支持
这些内容有意不在支持范围内——支持它们会把模板变成脚本引擎，而 Exportelier 有意不做脚本引擎。编辑器会显示错误，且该结构绝不会被执行。
| Xporter 结构 | 状态 | 替代做法 |
|---|---|---|
${dateformat("yyyy-MM-dd")} 及其他函数或过滤器调用 | 函数绝不会被运行。 | 请使用固定的格式化器集合，例如 ${issue.created | date("yyyy-MM-dd")}。 |
${jql("project = ABC")} / #{JQL: …} | 绝不会从模板中运行 JQL。 | 请通过导出上下文选择问题。 |
| JavaScript、Groovy、Velocity、FreeMarker、JS 过滤器 | 这不是脚本语言。 | 请使用 token、循环、条件和格式化器表达布局。 |
set 变量、break/continue、算术运算、表达式 | 这不是脚本语言。 | 请重构为受支持的结构。 |
校验器如何处理这些发现
在上传时，每项发现都会成为一条带有严重级别的诊断信息：
- info——原样支持，无需处理。
- warning——可自动转换或可解释；导出仍会继续，但如果绑定未知，某个 值可能渲染为空。
- error——不安全或不受支持的语法、不安全的路径，或解析错误。
Word 会保留但不会填充的结构——文本框、脚注、内容控件、域代码、批注和修订——会作为 unsupported-location 警告单独报告。文档会保留它们，但其中的 token 不会被填充。