docxload

To generate .docx files on front-end by tag template.

docxload is a tool for generating .docx files, which is developed based upon docx. The package docx has rich configuration to meet most of demand about setting document content and content style, but its detailed configuration rules sometimes would generate a relatively complexed 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 data type is string, using Double quotes
// when a tag attribute's data type is js expression, using curly braces
// a tag attribute could have multiple subattributes configured as "key1: value1; key2: value2;", such as the "underline" attribute
let template = `
  <page>
    <p>
      <span 
        underline="type: single; color: #000;"
        color="#000"
      >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, check out demo.

API

function docxload(template: string, option?: object | string): Promise

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)
})

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

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 subattributes: 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 subattributes: 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 row atLeast - 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 name or 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 data when 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 subattributes: 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 indentical to border's	String	-	-

trevorHsu/docxload