# docxload [![NPM version][npm-image]][npm-url] [![PRs Welcome][pr-image]][pr-url] [English Documentation ( 英文文档 )][en-doc-url] 通过标签语法在前端生成 .docx 文件，支持 JavaScript 和 TypeScript。
> **docxload** 是基于 [docx][docx-url] 包实现的 .docx 文件导出工具。**docx** 包拥有丰富的配置，能够实现绝大多数 docx 文档的样式需求。但其细致的配置也导致了配置代码相对复杂，当文档样式或内容过多时，其嵌套配置的方式会导致代码可读性降低，维护不方便。

**docxload** 简化了 **docx** 的配置，将一些基础配置封装，并以标签的形式暴露使用。**docxload** 通过标签的组合来完成配置，使配置工作更快，代码更易读；并且它支持 **docx** 的大多数配置，充分利用了 **docx** 的能力，详细配置请见下文。
## 安装 ```shell $npm install --save docxload ```
## 使用 ```js import docxload from 'docxload' // 标签属性值为 string 类型时，用双引号表示值 // 标签属性值为 number、boolean、或简单的表达式时，用大括号表示值 // 一个属性中，可以有多个子属性配置，形式为："key1: value1; key2: value2;"，如 underline 属性 let template = `

Hello, docxload

` docxload(template).then(() => { console.log('done') }).catch(err => { console.log('failed', err) }) ``` 更多配置示例，见[示例代码][demo-url]。
## API ```ts declare const docxload: (template: string, option?: object | string) => Promise<[Blob, (blob: Blob, fileName?: string) => void]> ``` ### 方法参数： **docxload** 方法支持两个参数：
*template*：标签模板；*option*：配置选项，为可选参数；
当 *option* 为 string 类型时，可配置导出文件的文件名；
当 *option* 为 object 类型时，有以下配置选项： | 配置字段 | 描述 | 字段类型 | 默认值 | | - | - | :-: | - | | fileName | 导出文件的文件名，默认后缀名是 *.docx* | String | data.docx | | immediate | 是否立即导出文件；
若为 false, 程序将生成文档的二进制文件，但不导出 | Boolean | true | ### 返回值： **docxload** 方法执行后将返回一个 Promise 对象，该 Promise 对象的 resolve 方法会传递一个数组 **[blob, exportFile]**，用于扩展操作： | 数组成员 | 描述 | 值类型 | | - | - | - | | blob | 待导出文件的二进制对象 | Blob | | exportFile | 用于导出文件的方法 *exportFile(blob, fileName)*；
接收两个参数：blob为二进制对象，fileName为文件名 | Function | ### 使用示例： ```js let template = ... function docxToPdf() { ... } docxload(template, { immediate: false }).then(([blob, exportFile]) => { // 对 blob 对象进行处理，如转成 pdf 格式 let pdfBlob = docxToPdf(blob) exportFile(pdfBlob, 'data.pdf') }).catch(err => { console.log('failed', err) }) ```
## 标签类型 **docxload** 中的标签有两种类型：
一种是与 **docx** 包中的类相对应的标签，可支持对应类中的配置选项；
另一种是通过封装 **docx** 包中的一些配置而实现的标签。
| 标签 | 描述 | docx 中对应的类 | 是否可配置属性 | | :-: | - | :-: | :-: | | \\ | 文档中的一页 | - | √ | | \\ | 标题 | - | × | | \

\

| 段落 | [Paragraph][docx-doc-paragraph] | √ | | \\ | 文本 | [TextRun][docx-doc-text] | √ | | \ | 图片 | [ImageRun][docx-doc-image] | √ | | \\
| 表格 | - | √ | | \\ | 表格行 | - | √ | | \\ | 单元格 | - | √ | | \
| 换行 | - | × | | \ | 占位标签，无实义 | - | × |
标签需按以下层级规则进行嵌套，同级标签不可嵌套： **page** > **title, p, table** > **span, img, br** **table** > **row** > **cell** *注意标签中的第二级必须是 title、p、table 之一* *template 标签可嵌套在任意标签层级；
在使用 jsx语法编写模板时，有些环境要求模板必须有根标签，此时\