Word 模板准备

English

Sheet to Doc 是一个功能强大的工具，可以自动将 Excel, CSV, JSON, JSONL数据写入docx格式的Word模版，批量的转换为Word文档。

在邮件合并的基础上，本工具开发了更多功能，比如自定义文件名，自定义文件路径，嵌入图片等等等等。

备注

本页面内容较长，我们建议您结合页面左侧的目录来浏览本页面内容，以方便您了解页面结构。

准备您的 Word 模板

提示

我们推荐您使用微软的Word来准备您的模板文件，如果没有Word，您可以使用其他编辑器（如WPS）来准备模板文件。建议您在准备模版的时候就把格式设置好，Sheet-to-Doc 只是填入数据，并不会改变您已经设置的格式。

创建一个新的 Word 文档，必须是.docx格式文件。
使用 {占位符} 语法插入占位符。关于占位符的详细用法，见下方“占位符”部分。
根据需要添加任何其他文本、图片、表格等等，并设置格式。
将模板保存为 .docx 文件。

占位符

占位符是指在 Word 模板中用于插入数据的特殊标记。每个占位符都以英文字符 { 和 } 括起来，例如 {姓名}、{@图片 | _inline_image} 等。

数据占位符

是否支持	生成模式1（多文档）	生成模式2（单文档）
数据占位符	支持	支持

数据占位符是指在 Word 模板中用于插入数据的特殊标记。例如 {姓名}、{出生日期} 等。

可以参考使用案例中的邀请函例子。

警告

占位符的名称必须与 Excel 表格中的列标题完全匹配，否则数据将无法正确填充。

假设您的 Excel 表格包含以下列：姓名、年龄、性别。

    姓名    年龄    性别
    张三    25    男

在 Word 模板中，您可以插入以下占位符：

{姓名},{年龄},{性别}。

当工具运行时，它将使用 Excel 表格中的数据填充这些占位符。

张三,25,男。

循环占位符

是否支持	生成模式1（多文档）	生成模式2（单文档）
循环占位符1	不支持	支持
循环占位符2	支持	支持

如果您的 Excel 表格中包含多行数据，且您希望

在一个Word文档中重复填充模板中的内容，或者
每行数据占用一页Word文档，生成多个Word文档。

那么，您可以使用循环占位符1或循环占位符2来实现。

循环占位符1

循环占位符1适用于在一个Word文档中，重复写入Excel表格中数据的每一行，最终产出一个文件。

循环占位符1的格式为 {#data}...{/data}。

循环占位符1固定为{#data}和{/data}，不能改动。
当你使用循环占位符1时，必须选择生成模式2。

小技巧

如果你希望每行数据单独占用一页Word，那么需要在模版后面添加一个分页符，然后在第二页的开头添加{/data}，可以参考使用案例当中的邀请函的例子。

在 {#data}...{/data} 内部，您可以使用数据占位符等其他占位符，如 {#data}{姓名}{/data} 来引用具体数据。注意{}需要使用英文字符。

可以参考使用案例中的邀请函、获奖通知例子。

假设您的 Excel 表格包含以下列：姓名、年龄、性别。

    姓名    年龄    性别
    张三    25    男
    李四    30    女

在 Word 模板中，您可以插入以下占位符：

{#data}

{姓名},{年龄},{性别}。

{/data}

当生成模式2下，它将循环阅读Excel 表格中的数据，然后逐行填充这些占位符。

张三,25,男。

李四,30,女。

循环占位符2

（自2.4.0版本开始）

循环占位符2，相较于循环占位符1，是一个更通用的版本。

循环占位符2的格式为{#loop1}...{/loop1}。
循环占位符2中的loop1可以替换为其他名称，例如{#person}...{/person}，{#资料}...{/资料}等，但不可以是{#data}...{/data}。
循环占位符2可以在生成模式1和2下生效。

警告

循环占位符2使用起来相对比较复杂，如果不是必须，建议使用循环占位符1。如果使用循环占位符2，需要在Excel数据准备和Word模版准备上就开始做若干考虑，否则会导致数据填充错误，通过以下例子进行说明。

我们采用和循环占位符1相同的例子，假设您的 Excel 表格包含以下列：姓名、年龄、性别。

    姓名    年龄    性别
    张三    25    男
    李四    30    女
    王五    35    男

如果您使用循环占位符2，需要在Excel数据准备和Word模版准备上做一些考虑。

Excel数据需要做如下调整：

    资料.姓名    资料.年龄    资料.性别
    张三        25          男
    李四        30          女
    王五        35          男

我们把表头姓名、年龄、性别前面都添加了资料.，这是为了在Word模版中使用循环占位符2时，能够正确引用Excel数据中的列。

下面分生成模式1，和生成模式2进行说明。

生成模式1下，您需要在Word模版中使用{#资料}和{/资料}来作为循环占位符2，包裹数据占位符{姓名}、{年龄}、{性别}的内容。
生成模式2下，您可以在Word模版中使用{#资料}和{/资料}来作为循环占位符2，包裹数据占位符{姓名}、{年龄}、{性别}的内容，同时您还需要在最外侧使用{#data}和{/data}，因为这是使用生成模式2必须要出现的占位符。

在为生成模式1准备的 Word 模板中，您可以插入以下占位符：

{#资料}

{姓名},{年龄},{性别}。

{/资料}

当选择生成模式1时，它将循环阅读Excel 表格中的数据，然后生成3个文件。

张三,25,男。

李四,30,女。

王五,35,男。

在为生成模式2准备的 Word 模板中，您可以插入以下占位符：

{#data}

{#资料}

{姓名},{年龄},{性别}。

{/资料}

{/data}

当使用生成模式2时，它将循环阅读Excel 表格中的数据，然后逐行填充这些占位符。最终生成一个文件。

张三,25,男。

李四,30,女。

王五,35,男。

判断占位符

是否支持	生成模式1（多文档）	生成模式2（单文档）
判断占位符1	支持	支持
判断占位符2	支持	支持
判断占位符3	支持	支持

如果您的 Excel 表格中包含条件数据，您可以使用判断占位符来根据条件填充模板中的内容。比如说，当某个数据达到某个值时，才填充模板中的内容，否则不填充。

判断占位符1 - true false

判断占位符1的格式为 {#a条件}...{/a条件}。注意{}需要使用英文字符。

a条件：判断占位符1中的a条件，可以是Excel数据中的任意列，例如姓名、年龄、性别、获奖等。
条件：判断占位符1中的条件，必须是true或false。

假设您的 Excel 表格包含以下列：姓名、年龄、性别，获奖（是否获奖）。我们以是否获奖为条件，来填充模板中的内容。

    姓名    年龄    性别    获奖
    张三    25    男    true
    李四    30    女    false
    王五    35    男    true

在 Word 模板中，您可以插入判断占位符{#获奖}...{/获奖}：

本次比赛获奖名单：

{#data}

{#获奖}

{姓名},{年龄},{性别}。

{/获奖}

{/data}

当工具运行时，它将循环 Excel 表格中的数据，并完成判断是否是获奖人员（根据获奖列的值是不是true），如果是，则填充占位符，如果不是，则不填充。

本次比赛获奖名单：

张三,25,男。

王五,35,男。

判断占位符2 - 等于不等于指定值

判断占位符2的格式为 {#a条件 == "指定值"}...{/}或{#a条件 != "指定值"}...{/}。注意{}，#等等符号需要使用英文字符。

举例：

假设您的 Excel 表格包含以下列：姓名、奖品。我们以奖品为条件，来填充模板中的内容。

    姓名    奖品
    张三    手表
    李四    充电宝
    王五    手表

下载本模板文件：Sample3-docx

{#data}

{姓名}获得了{奖品}，展示如下：

{#奖品 == “手表”}

{/}

{#奖品 == “充电宝”}

充电宝

{/}

{/data}

警告

例子中的”手表”和”充电宝”外面的双引号必须是英文双引号。
如果条件指定值是数字，则不用加双引号，直接写数字即可。

当工具运行时，它将循环 Excel 表格中的数据，并判断设置的条件（年龄列是否大于等于30），如果是，则填充占位符，如果不是，则不填充。

张三获得了手表，展示如下：

李四获得了充电宝，展示如下：

充电宝

王五获得了手表，展示如下：

判断占位符3 - 比大小

（自2.4.0版本开始）

判断占位符3的格式为 {#a条件运算符 "指定值"}...{/}。

运算符包括 >、>=、<、<=。
注意{}，#等等符号需要使用英文字符。

假设您的 Excel 表格包含以下列：姓名、年龄。我们以年龄为条件，来填充模板中的内容。

模版：

{#data}

{#年龄 >= 30}

{姓名}是30岁及以上的人。

{/}

{/data}

警告

如果条件指定值是数字，则不用加双引号，直接写数字即可。
本例子应当在生成模式2所有数据在一个Word文档中重复生成下运行。

当工具运行时，它将循环 Excel 表格中的数据，并判断设置的条件，如果是，则填充占位符，如果不是，则不填充。

李四是30岁及以上的人。

王五是30岁及以上的人。

图片占位符

是否支持	生成模式1（多文档）	生成模式2（单文档）
图片占位符	支持	支持

（自2.2.0 版本开始）

Sheet-to-Doc提供两种插入图片的方法：

第一种方法见上述的判断占位符2中的方法（也就是提前将所有可能出现的图片预先插入到Word模板中）通过条件来判断是否显示特定图片
另外一种方法就是本章节的图片占位符方法，通过在Word模板中插入特殊的占位符，来动态插入图片，图片需要提前上传到工具中。

图片占位符是指在 Word 模板中用于插入图片的特殊标记。每个图片占位符都以英文字符 { 和 } 括起来， {@图片 | _inline_image:width:height}、{@图片 | _block_image:width:height} 等。

_inline_image 表示内联图片，会将图片插入到文本中，与文本紧密结合。
_block_image 表示块级图片(上下型环绕)，会将图片插入到段落中，与段落独立。
width 和 height 是可选参数，用于指定图片的宽度和高度。如果不指定，图片将按照5cm x 5cm的大小显示。如果需要指定，需要使用厘米作为单位。例如 {@图片 | _inline_image:10:10} 表示将图片插入到文本中，宽度为10cm，高度为10cm。
符号需要使用英文字符，例如 {@图片 | _inline_image} 中的 @、|、_ 都需要使用英文字符。

可以参考使用案例中的获奖通知例子。

注意：

图片占位符必须以@开头，例如 {@图片 | _inline_image}
图片占位符必须包含图片类型（| _inline_image 或 | _block_image），否则工具无法识别, 其中|, _需要使用英文字符
图片占位符必须在Word模版中以单独一行的形式出现，不能与其他文本在同一行。否则无法正常显示。
图片占位符必须包含图片文件名变量，否则工具无法识别图片文件名，例如 {@图片 | _inline_image} 中的 图片 就是图片文件名变量
图片文件名与上传的图片文件名一致（区分大小写，需要有后缀名），否则工具无法找到对应的图片文件（例如 watch.png）。图片名称可以包含中文，但如果包含特殊字符，有可能会出现错误。

例子：

假如Excel数据列出了图片名称、图片中文名。

例如：

    图片中文名  图片名称
    手表    watch.png
    充电宝    batterybank.png

同时需要上传 watch.png 和 batterybank.png 这两张图片。

Word模版采用以下格式：

{#data}

{@图片名称 | _inline_image}

{/data}

生成模式2下，会生成如下文档：

充电宝

二维码占位符

是否支持	生成模式1（多文档）	生成模式2（单文档）
二维码占位符	支持	支持

（自2.7.0 版本开始）

提示

如果您的二维码已经是图片了，请使用图片占位符来插入二维码图片。如果您现在没有二维码，只有二维码内容，还没有生成二维码，您可以使用二维码占位符来生成并插入二维码。

您可以在Word模版中插入二维码占位符，例如 {@二维码 | _qrcode:width:height},并提供二维码对应的数据内容，来插入二维码。

width 和 height 是可选参数，用于指定二维码的宽度和高度。如果不指定，二维码将按照5cm x 5cm的大小显示。如果需要指定，需要使用厘米作为单位。例如 {@二维码 | _qrcode:10:10} 表示将二维码插入到文本中，宽度为10cm，高度为10cm。
二维码占位符必须以@开头，例如 {@二维码 | _qrcode} 中的 @ 就是二维码占位符的开始符号。
二维码占位符必须包含二维码类型（| _qrcode），否则工具无法识别, 其中|, _需要使用英文字符
二维码占位符必须在Word模版中以单独一行的形式出现，不能与其他文本在同一行。否则无法正常显示。
二维码会以内连图片的形式插入到文本中，与文本紧密结合。
二维码占位符必须包含二维码内容变量，否则工具无法识别二维码内容，例如 {@二维码 | _qrcode} 中的 二维码 就是二维码内容变量。
二维码内容变量可以是Excel数据中的任意一列，例如 {@姓名 | _qrcode} 中的 姓名 就是二维码内容变量。
二维码内容变量可以是Excel数据中的任意一列，例如 {@设备编号 | _qrcode} 中的 设备编号 就是二维码内容变量。
二维码内容变量对应的数据格式必须是字符串或数字，且长度不可以超过200个字符。比如设备编号 EQ20303, 它的长度不可以超过200个字符。

例子：

假如Excel数据列出了设备、设备编号。

例如：

    设备  设备编号
    鼠标    EQ20303
    键盘    EQ20304

Word模版采用以下格式：

{#data}

{设备}

{@设备编号 | _qrcode}

{/data}

生成模式2下，会生成如下文档：

鼠标

鼠标二维码

键盘

键盘二维码

过滤器（Filters）

您可以使用过滤器来转换模板中的数据。过滤器通过管道符（|）应用到占位符上，语法为：{占位符 | 过滤器名称} 或 {占位符 | 过滤器名称:参数}。注意{},|和:需要使用英文字符。另外，如果过滤器需要参数，如果这个参数不是数字，那么这个参数需要用英文双引号括起来。

可以参考使用案例中的收据例子。

字符串过滤器

过滤器名称	描述	示例	输出
`toUpperCase`	将英文字符串转换为大写	`{姓名 \| toUpperCase}`	`Zhang San` → `ZHANG SAN`
`toLowerCase`	将英文字符串转换为小写	`{姓名 \| toLowerCase}`	`Zhang San` → `zhang san`
`capitalize`	将英文字符串的第一个字符大写	`{姓名 \| capitalize}`	`Zhang San` → `Zhang san`

数字过滤器

基本数字格式化

过滤器名称	描述	示例	输出
`fixed`	将数字格式化为固定小数位数	`{价格 \| fixed:2}` 当价格为 123.456	`123.46`
`round`	将数字四舍五入到最接近的整数	`{价格 \| round}` 当价格为 123.6	`124`
`ceil`	将数字向上取整到最接近的整数	`{价格 \| ceil}` 当价格为 123.1	`124`
`floor`	将数字向下取整到最接近的整数	`{价格 \| floor}` 当价格为 123.9	`123`

货币和财务格式化

过滤器名称	描述	示例	输出
`currency`	将数字格式化为货币格式	`{价格 \| currency:"¥":2}` 当价格为 1234.56	`¥1,234.56`
`accounting`	将数字格式化为会计格式（负数使用括号）	`{价格 \| accounting:"¥":2}` 当价格为 -1234.56	`¥(1,234.56)`
`thousandSeparator`	将数字格式化为带千位分隔符	`{价格 \| thousandSeparator:2}` 当价格为 1234567.89	`1,234,567.89`

百分比和科学计数法

过滤器名称	描述	示例	输出
`percentage`	将数字格式化为百分比	`{利率 \| percentage:2}` 当利率为 0.1234	`12.34%`
`scientific`	将数字格式化为科学计数法	`{数值 \| scientific:2}` 当数值为 123456	`1.23e+05`

数字缩写

过滤器名称	描述	示例	输出
`shortNumber`	将数字格式化为简短形式（K, M, B）	`{金额 \| shortNumber}` 当金额为 1234567	`1.23M`

占位符出现位置

占位符可以出现在Word模版的任何位置，包括但不限于：

段落
表格
列表
标题
页眉
页脚
文本框等等