docxload

中文文档（Chinese Documentation）

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. 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

$npm install --save docxload

Usage

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 = `
  <page>
    <p>
      <span 
        underline="type: single; color: #000000;"
        color="#000000"
      >Hello, </span>
      <span font-size={30}>docxload</span>
    </p>
  </page>
`

docxload(template).then(() => {
  console.log('done')
}).catch(err => {
  console.log('failed', err)
})

For more configuration examples, please refer to demo.

API

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:

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 | | :-: | - | :-: | :-: | | <page></page> | a page in the document | - | √ | | <title></title> | title | - | × | | <p></p> | paragraph | Paragraph | √ | | <span></span> | text | TextRun | √ | | <img /> | image | ImageRun | √ | | <table></table> | table | - | √ | | <row></row> | a row of the table | - | √ | | <cell></cell> | a cell of the table | - | √ | | <br /> | break line | - | × | | <template></template> | 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 <title>, <p> or <table>.

<template> can be embedded in any tag level; when writing a template in jsx syntax, some environment require a root tag in the template; <template> can be the root tag.

Tag Attributes

The following attributes have simplified some configurations of docx. For more attributes of a tag, please check out the documentation of the tag's corresponding class in docx. Please refer to this documentation when an attribute configuration is different from docx's.

page

| Attribute | Description | Type | Option | Default | | - | - | - | - | - | | orientation | orientation of the page | String | vertical - portrait horizontal - landscape | vertical | | header | page header, it has several sub attributes:alignment: horizontal alignment;format: string template, which provides template variables including current page number $pageCurrent, total page amount $pageTotal;area: specific pages on which the header can be showed;all attributes of tag <span> are supported | String | alignment:center, left, right, distribute, both, start, end;area:all - all pages,odd - odd number pages,even - even number pages | - | | footer | page footer, its attribute configuration is identical to header's | String | - | - |

p

| Attribute | Description | Type | Option | Default | | - | - | - | - | - | | alignment | horizontal alignment | String | center, left, right, distribute, both, start, end | left | | heading | title level | String | title, heading_1, heading_2, heading_3, heading_4, heading_5, heading_6 | - | | indent | to increase indentation, one unit is one Tab indentation | Number | - | - | | spacing | paragraph spacing, it has 4 sub attributes:before: spacing before paragraph, number, unit: pound;after: spacing after paragraph, number, unit: pound;line-rule: line rule;line: line spacing value, number, its unit is decided by line-rule | String | line-rule:multiple - multiple line spacing，line's unit is rowatLeast - the minimum line spacing，line's unit is pound | - |

span

| Attribute | Description | Type | Option | Default | | - | - | - | - | - | | font-size | font size of text | Number | - | 20 | | bold | to make text bold | Boolean | - | false | | italics | italic text | Boolean | - | false | | color | text color, using color hex values | String | - | - | | highlight | to highlight text, using color name | String | - | - | | all-caps | to transform all the letters into capital letters | Boolean | - | false | | small-caps | to transform all the letters into capital letters in mini style | Boolean | - | false | | strike | strikethrough | Boolean | - | false | | double-strike | double strikethrough | Boolean | - | false | | super-script | superscript | Boolean | - | false | | sub-script | subscript | Boolean | - | false | | underline | underline When is Boolean type and the value is true, using default underline style;When is String type, it has two subattributes:type: underline type; color: underline color | String, Boolean | type:single, word, double, thick, dotted, dottedheav, dash, dashedheav, dashlong, dashlongheav, dotdash,dashdotheavy, dotdotdas, dashdotdotheavy, wave, wavyheavy, wavydouble; | false |

img

| Attribute | Description | Type | Option | Default | | - | - | - | - | - | | width | width of the image | Number | - | 100 | | height | height of the image | Number | - | 100 | | src | image resource, can be both url or base64 encoded datawhen the src value is an url，docxload will request for the image automatically | String | - | - |

table

| Attribute | Description | Type | Option | Default | | - | - | - | - | - | | width | the entire width of a table,unit: % | String | - | 100% |

row

| Attribute | Description | Type | Option | Default | | - | - | - | - | - | | height | the height of a row,unit: cm | String, Number | - | 1cm |

cell

| Attribute | Description | Type | Option | Default | | - | - | - | - | - | | width | the width of a cell,unit: %,the percentage is relative to the entire table width | String | - | average width | | colspan | to merge columns | Number | - | - | | rowspan | to merge rows | Number | - | - | | align | horizontal alignment | String | center, left, right, distribute, both, start, end | center | | vertical-align | vertical alignment | String | center, bottom, top | center | | fontSize | font size | Number | - | 20 | | border | borders of a cell, it has 3 sub attributes: style： border style size： border width, Number color： border color, color hex values | String | style: single, dash_dot_stroked, dashed,dash_small_gap, dot_dash, dot_dot_dash, dotted, double, double_wave, inset, nil, none, outset, thick, thick_thin_large_gap, thick_thin_medium_gap, thick_thin_small_gap, thin_thick_large_gap, thin_thick_medium_gap, thin_thick_small_gap, thin_thick_thin_large_gap,thin_thick_thin_medium_gap, thin_thick_thin_small_gap, three_d_emboss, three_d_engrave, triple, wave | - | | border-top border-right border-bottom border-left | a border of a cell, its attribute configuration is identical to border's | String | - | - |