# docxload [![NPM version][npm-image]][npm-url] [![PRs Welcome][pr-image]][pr-url] [中文文档（Chinese Documentation）][cn-doc-url] Generate .docx files on the frontend using tag syntax, compatible with both JavaScript and TypeScript.
> **docxload** is a tool for generating .docx files, which is developed based upon [docx][docx-url]. The package **docx** has rich configurations to meet most of demand about setting document content and content style, but its detailed configuration rules sometimes would generate a relatively complex code. When there are too many document style or content, **docx**'s nested style code would become low-readable, which is not good for maintenance.

**docxload** simplifies **docx**'s configuration. It uses tag string to represent **docx**'s class and generates **docx** configuration by combining different tags, which is easier to code and to read.
## Installation ```shell $npm install --save docxload ```
## Usage ```js import docxload from 'docxload' // When a tag attribute's value is of the string type, it should be enclosed in double quotes // When a tag attribute's value is a number, boolean, or a simple expression, it should be enclosed in curly braces // a tag attribute could have multiple sub attributes configured as "key1: value1; key2: value2;", such as the "underline" attribute let template = `

Hello, docxload

` docxload(template).then(() => { console.log('done') }).catch(err => { console.log('failed', err) }) ``` For more configuration examples, please refer to [demo][demo-url].
## API ```ts declare const docxload: (template: string, option?: object | string) => Promise<[Blob, (blob: Blob, fileName?: string) => void]> ``` ### Payloads: **docxload** has 2 parameters：
*template*：tag template；*option*：configuration option，is an optional parameter；
When *option*'s data type is string, it would set the generated file's name;
When *option*'s data type is object, it has following configuration fields: | Field | Description | Type | Default | | - | - | :-: | - | | fileName | the generated file's name，its default extension name is *.docx* | String | data.docx | | immediate | whether to generate a document immediately;
if false, docxload will generate the document's binary data in memory | Boolean | true | ### Returns: -------------------------- **docxload** would return a Promise instance which resolves an array **[blob, exportFile]**: | Array Member | Description | Type | | - | - | - | | blob | a Binary Object of the file to be generated | Blob | | exportFile | a method for generating a file;
*exportFile(blob, fileName)*
accepts 2 parameters：blob as binary object，fileName as file name | Function | ### Example: ```js let template = ... function docxToPdf() { ... } docxload(template, { immediate: false }).then(([blob, exportFile]) => { // processing the blob object let pdfBlob = docxToPdf(blob) exportFile(pdfBlob, 'data.pdf') }).catch(err => { console.log('failed', err) }) ```
## Tags **docxload** has 2 types of tag：
1. corresponding with a class in **docx**, supporting almost all the configuration of the class; 2. representing some configuration code of **docx**
| Tag | Description | Class in **docx** | Configurable | | :-: | - | :-: | :-: | | \\ | a page in the document | - | √ | | \\ | title | - | × | | \

\

| paragraph | [Paragraph][docx-doc-paragraph] | √ | | \\ | text | [TextRun][docx-doc-text] | √ | | \ | image | [ImageRun][docx-doc-image] | √ | | \\
| table | - | √ | | \\ | a row of the table | - | √ | | \\ | a cell of the table | - | √ | | \
| break line | - | × | | \ | a placeholder, no meaning | - | × |
Tags should be nested according to the following level rules, tags at the same level should not be nested: **page** > **title, p, table** > **span, img, br** **table** > **row** > **cell** *note: the second level of the tags must be one of \, \ or \.* *\