2.0.2 • Published 5 months ago

docxload v2.0.2

Weekly downloads
-
License
MIT
Repository
github
Last release
5 months ago

docxload

NPM version PRs Welcome

中文文档(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

TagDescriptionClass in docxConfigurable
\\a page in the document-
\\title-×
\\paragraphParagraph
\\textTextRun
\imageImageRun
\\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 \<title>, \<p> or \<table>.

\ can be embedded in any tag level; when writing a template in jsx syntax, some environment require a root tag in the 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

AttributeDescriptionTypeOptionDefault
orientationorientation of the pageStringvertical - portrait horizontal - landscapevertical
headerpage 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 supportedStringalignment:center, left, right, distribute, both, start, end;area:all - all pages,odd - odd number pages,even - even number pages-
footerpage footer, its attribute configuration is identical to header'sString--

p

AttributeDescriptionTypeOptionDefault
alignmenthorizontal alignmentStringcenter, left, right, distribute, both, start, endleft
headingtitle levelStringtitle, heading_1, heading_2, heading_3, heading_4, heading_5, heading_6-
indentto increase indentation, one unit is one Tab indentationNumber--
spacingparagraph 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-ruleStringline-rule:multiple - multiple line spacing,line's unit is rowatLeast - the minimum line spacing,line's unit is pound-

span

AttributeDescriptionTypeOptionDefault
font-sizefont size of textNumber-20
boldto make text boldBoolean-false
italicsitalic textBoolean-false
colortext color, using color hex valuesString--
highlightto highlight text, using color nameString--
all-capsto transform all the letters into capital lettersBoolean-false
small-capsto transform all the letters into capital letters in mini styleBoolean-false
strikestrikethroughBoolean-false
double-strikedouble strikethroughBoolean-false
super-scriptsuperscriptBoolean-false
sub-scriptsubscriptBoolean-false
underlineunderline 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 colorString, Booleantype:single, word, double, thick, dotted, dottedheav, dash, dashedheav, dashlong, dashlongheav, dotdash,dashdotheavy, dotdotdas, dashdotdotheavy, wave, wavyheavy, wavydouble;false

img

AttributeDescriptionTypeOptionDefault
widthwidth of the imageNumber-100
heightheight of the imageNumber-100
srcimage resource, can be both url or base64 encoded datawhen the src value is an url,docxload will request for the image automaticallyString--

table

AttributeDescriptionTypeOptionDefault
widththe entire width of a table,unit: %String-100%

row

AttributeDescriptionTypeOptionDefault
heightthe height of a row,unit: cmString, Number-1cm

cell

AttributeDescriptionTypeOptionDefault
widththe width of a cell,unit: %,the percentage is relative to the entire table widthString-average width
colspanto merge columnsNumber--
rowspanto merge rowsNumber--
alignhorizontal alignmentStringcenter, left, right, distribute, both, start, endcenter
vertical-alignvertical alignmentStringcenter, bottom, topcenter
fontSizefont sizeNumber-20
borderborders of a cell, it has 3 sub attributes: style: border style size: border width, Number color: border color, color hex valuesStringstyle: 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-lefta border of a cell, its attribute configuration is identical to border'sString--
2.0.2

5 months ago

2.0.1

5 months ago

2.0.0

5 months ago

1.0.6

4 years ago

1.0.5

4 years ago

1.0.4

4 years ago

1.0.3

4 years ago

1.0.2

4 years ago

1.0.1

4 years ago

1.0.0

4 years ago

0.1.5

4 years ago

0.1.0

4 years ago

0.1.2

4 years ago

0.1.1

4 years ago

0.1.4

4 years ago

0.1.3

4 years ago

0.0.2

4 years ago

0.0.0

4 years ago