{"id":21614480,"url":"https://github.com/binfoe/docxer","last_synced_at":"2026-05-16T11:31:44.589Z","repository":{"id":240196878,"uuid":"801931730","full_name":"binfoe/docxer","owner":"binfoe","description":"docx template engine","archived":false,"fork":false,"pushed_at":"2024-11-22T02:17:46.000Z","size":211,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-08T22:10:12.382Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/binfoe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-17T07:43:12.000Z","updated_at":"2024-11-22T02:17:50.000Z","dependencies_parsed_at":"2024-05-17T09:26:19.126Z","dependency_job_id":"a0a1e2fc-3d20-42c3-8377-2e0cc492aabb","html_url":"https://github.com/binfoe/docxer","commit_stats":null,"previous_names":["binfoe/docxer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/binfoe/docxer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binfoe%2Fdocxer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binfoe%2Fdocxer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binfoe%2Fdocxer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binfoe%2Fdocxer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/binfoe","download_url":"https://codeload.github.com/binfoe/docxer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binfoe%2Fdocxer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33100813,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T04:41:52.686Z","status":"ssl_error","status_checked_at":"2026-05-16T04:41:52.009Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-24T22:08:08.697Z","updated_at":"2026-05-16T11:31:44.551Z","avatar_url":"https://github.com/binfoe.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# docxer\n\n\u003e docx 模板渲染引擎\n\n## 使用\n\nCli 使用：\n\n```bash\nnpm i -g docxer\n# 命令：\ndocxer [inputDocxFile] [inputDataFile] [outputDocxFile]\n# 示例：\ndocxer /var/some_template.docx /var/some_data.json /var/some_output.docx\n```\n\nTypeScript 使用（在 Node 和浏览器都可使用）：\n\n```ts\nimport fs from 'fs';\nimport { processDocx } from 'docxer';\nconst buf = fs.readFileSync('some_template.docx');\nprocessDocx({\n  docxFileBuf: buf,\n  renderData: {\n    name: '小静',\n    age: 18,\n  },\n}).then((outputBuf) =\u003e {\n  fs.writeFileSync('some_output.docx', outputBuf);\n});\n```\n\n[ClearScript](https://github.com/microsoft/ClearScript) 使用：\n\n```js\nimport { processDocx } from 'docxer/all';\n```\n\n`docxer/all` 导出的产物是把依赖的比如 jszip 等库都一起打包到了产物文件中，以一个完整的独立文件的方式提供给业务使用。\n\n## API\n\n```ts\n/** 渲染配置。 */\ninterface RenderConfig {\n  // 渲染结束后，额外删除文档尾部的段落。默认为 0。该参数可用于修正渲染后可能多出来的空段落（空页）。\n  dropTailParagraphs?: number;\n}\n/**\n * 渲染 docx 文件主函数。返回渲染后的 docx 文件的 binary 内容，可直接写入磁盘。\n */\nexport function processDocx(options: {\n  /** 模板 docx 文件，原始 binary 文件内容 */\n  docxFileBuf: ArrayBuffer | Buffer;\n  /** 渲染数据。必须是 object 对象，且不能有 '$helper' 这个保留单词的属性名。 */\n  renderData: { [key: string]: unknown };\n  /** 渲染配置。该配置在 docx 模板文件中还可以通过 #prepare 指令指定的代码进行覆写。 */\n  renderConfig?: RenderConfig;\n}) {\n  return buf as Buffer | ArrayBuffer;\n}\n```\n\n## 正文批注指令\n\n- `#var [expr]` 将批注的内容替换为表达式的返回值。如果批注的内容有不同样式，比如多个颜色，则只会保留第一个字符的样式。\n- `#if [expr]` 如果表达式的值为 `false`，则删除批注的内容。\n- `#ifp [expr]` 如果表达式的值为 `false`，则删除批注所在的整个段落。\n- `#iep [expr]` 删除批注所在段落，并插入表达式返回值数量的空段落。表达式必须返回一个整数。\n- `#ig` 删除批注的内容。该指令用于忽略(ignore)指定内容，这些内容可能在模板中用于支撑排版，没有实际意义。\n- `#igp` 删除批注所在段落。和 `#ig` 类似用于支撑排版。\n- `#for [each] [datasource]` [`TODO`]\n- `#forp [each] [datasource]` [`TODO`]\n\n## 表格批注指令\n\n#### `#table [start](-[end]) [each] [datasource]`\n\n标记当前表格使用动态数据渲染，会执行 `datasource` 参数的表达式并返回一个Array，渲染引擎会遍历 Array 循环生成表格数据行。`each` 参数是一个变量名称，在表格行里使用正文批注指令时，可通过该名称访问每次循环的数据。`start` 和 `end` 是要循环渲染的模板行，从`1` 开始计数，如果要跳过表头，则一般指定为 `2`。在模板行中，可以使用任意`正文批注指令`。`end` 可不指定，默认为 `start`。`end` 之后的所有行会被删除。\n\n#### `#dymtable [columns] [datasource]`\n\n标记当前表格完全使用动态渲染。`columns` 参数是一个表达式，返回列的定义数据。`datasource` 是表格数据行。渲染时会将表格的第一行使用 `columns` 数据填充（多余的列会被删除，缺少的列会拿第一列克隆），然后将表格的第二行克隆后使用 `datasource` 填充。受当前代码逻辑所限，`columns` 表达式不能有空格，但 `datasource` 表达式中可以含空格。\n\n`columns` 表达式需要返回结构 `{ width?: number; name: string; key: string }`，其中 name 是表头文字，key 是从 `datasource` 中取数据的属性名，width 是宽度（像素 px 单位，会乘以 20 换算成 dxa 单位写入 docx 文件）。width 为可选字段，不指定则不修改模板中的宽度。\n\n## 图片描述指令\n\n图片不支持批注，但可以添加描述信息，在描述信息中可配置指令。所有指令都针对当前图片生效。\n\n- `#if [expr]` 满足条件时图片才会被保留，否则会被删除。\n- `#var [expr]` 替换图片内容为表达式返回的值。如果返回值是 string 类型代表 base64 数据，Buffer/ArrayBuffer 类型代表 binary 数据。\n- `#for [each] [datasource]` [`TODO`]\n\n## 文本框描述指令\n\n文本框里的内容不支持批注，但文本框本身和图片一样可以添加描述。为了实现像文本批注那样能针对不同位置的文本内容定义指令，采用以下语法。\n\n`#@ ` 指定用于指定接下来连续的正文批注指令的作用位置，相当于用语法而不是人工操作来指定了批注的位置。该位置指定指令包括：\n\n- `#@ p1 w关键字` 指定段落 `p\\[X\\]` 的 `关键字` 所在范围。\n- `#@ p2 c3 c6` 指定段落 `p\\[X\\]` 从某开始列到结束列，其中列(Col)和 Word 以及主流文本编辑器含义一致。\n\n注意段落号从 1 开始计数，不是写代码的数组的 0 开始。\n\n在 `#@ ` 之后是至少一条正文批注指令。直到遇到下一个 `#@ ` 指定，则开始下一个位置的批注。\n\n## 配置指令\n\n段落开头识别到 `#docxer-config` 关键字，则从当前段落开始都是配置页。配置页不会被渲染到输出文档中。\n\n渲染页不使用批注指明指令，直接在正文中编写指令。每一条指令都需要独占一个段落。指令的参数在紧接着的下一个段落配置。\n\n### `#prepare` 指令\n\n该指令用于在渲染前执行额外的代码。推荐在 vscode 的 ide 中书写代码，然后整体拷贝到文本框中。将文本框的文字环绕配置为嵌入文本，嵌入到该指令紧邻的下一个段落。如果代码很少没有换行，也可以直接书写在该指定的下一个段落中。\n\nprepare 代码中可使用 `$data` 和 `$config` 两个全局变量。\n\n`$data` 是渲染数据，可任意读取和修改，也可以新增数据。这些数据都可在模板正文中的指令表达式使用。\n\n`$config` 是渲染配置，可任意读取和修改。该配置是文档的 API 章节中写明的 `RenderConfig` 结构，详见上文。\n\n示例：如果渲染之后的文档，因为 `#docxer-config` 指令在尾部产生了多于的空段进而导致出现了空白页，可通过配置 `$config.dropTailParagraphs` 来删除。\n\n```js\n$config.dropTailParagraphs = 1;\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinfoe%2Fdocxer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbinfoe%2Fdocxer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinfoe%2Fdocxer/lists"}