Update documentation
This commit is contained in:
@ -1,13 +1,3 @@
|
|||||||
<p align="center">
|
|
||||||
<img alt="clippy the assistant" src="https://i.imgur.com/37uBGhO.gif">
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p align="center">
|
|
||||||
Easily generate .docx files with JS/TS. Works for Node and on the Browser. :100:
|
|
||||||
</p>
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# Welcome
|
# Welcome
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
@ -66,12 +56,6 @@ Packer.toBuffer(doc).then((buffer) => {
|
|||||||
// Done! A file called 'My First Document.docx' will be in your file system.
|
// Done! A file called 'My First Document.docx' will be in your file system.
|
||||||
```
|
```
|
||||||
|
|
||||||
## Honoured Mentions
|
|
||||||
|
|
||||||
[@felipeochoa](https://github.com/felipeochoa)
|
|
||||||
|
|
||||||
[@h4buli](https://github.com/h4buli)
|
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<img alt="clippy the assistant" src="http://i60.tinypic.com/339pvtt.png">
|
<img alt="clippy the assistant" src="http://i60.tinypic.com/339pvtt.png">
|
||||||
</p>
|
</p>
|
||||||
|
10
docs/_coverpage.md
Normal file
10
docs/_coverpage.md
Normal file
@ -0,0 +1,10 @@
|
|||||||
|
<img src="https://i.imgur.com/37uBGhO.gif" alt="drawing" style="width:200px;"/>
|
||||||
|
|
||||||
|
> Easily generate .docx files with JS/TS. Works for Node and on the Browser. :100:
|
||||||
|
|
||||||
|
- Simple, declarative API
|
||||||
|
- 50+ usage examples
|
||||||
|
- Battle tested, mature, 95%+ coverage
|
||||||
|
|
||||||
|
[GitHub](https://github.com/dolanmiu/docx)
|
||||||
|
[Get Started](#Welcome)
|
@ -1,6 +1,6 @@
|
|||||||
* [Getting Started](/)
|
* [Getting Started](/)
|
||||||
|
|
||||||
* [Examples](examples.md)
|
* [Examples](https://github.com/dolanmiu/docx/tree/master/demo)
|
||||||
|
|
||||||
* API
|
* API
|
||||||
|
|
||||||
|
@ -1,25 +1,23 @@
|
|||||||
# Contribution Guidelines
|
# Contribution Guidelines
|
||||||
|
|
||||||
* Include documentation reference(s) at the top of each file:
|
- Include documentation reference(s) at the top of each file:
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
// http://officeopenxml.com/WPdocument.php
|
// http://officeopenxml.com/WPdocument.php
|
||||||
```
|
```
|
||||||
|
|
||||||
* Follow Prettier standards, and consider using the [Prettier VSCode](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) plugin.
|
- Follow Prettier standards, and consider using the [Prettier VSCode](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) plugin.
|
||||||
|
|
||||||
* Follow the `TSLint` rules
|
- Follow the `TSLint` rules
|
||||||
|
|
||||||
## Always think about the user
|
## Always think about the user
|
||||||
|
|
||||||
The number one pillar for contribution to `docx` is to **ALWAYS** think about how the user will use `docx`.
|
|
||||||
|
|
||||||
Put yourself in their position, and imagine how they would feel about your feature you wrote.
|
Put yourself in their position, and imagine how they would feel about your feature you wrote.
|
||||||
|
|
||||||
1. Is it easy to use?
|
1. Is it easy to use?
|
||||||
2. Has it been documented well?
|
2. Has it been documented well?
|
||||||
3. Is it intuitive?
|
3. Is it intuitive?
|
||||||
4. Is it consistent with the rest of the API?
|
4. Is it declarative?
|
||||||
5. Is it fun to use?
|
5. Is it fun to use?
|
||||||
|
|
||||||
## Good Commit Names
|
## Good Commit Names
|
||||||
@ -27,6 +25,7 @@ Put yourself in their position, and imagine how they would feel about your featu
|
|||||||
Please write good commit messages when making a commit: https://chris.beams.io/posts/git-commit/
|
Please write good commit messages when making a commit: https://chris.beams.io/posts/git-commit/
|
||||||
|
|
||||||
**Do not:**
|
**Do not:**
|
||||||
|
|
||||||
```
|
```
|
||||||
c // What?
|
c // What?
|
||||||
rtl // Adding acryonyms without explaining anything else is not helpful
|
rtl // Adding acryonyms without explaining anything else is not helpful
|
||||||
@ -35,34 +34,6 @@ demo updated // Getting better, but capitalize the first letter
|
|||||||
Unesesary coment removed // Make sure to use correct spelling
|
Unesesary coment removed // Make sure to use correct spelling
|
||||||
```
|
```
|
||||||
|
|
||||||
## No leaky components in API interface
|
|
||||||
|
|
||||||
> This mainly applies to the API the end user will consume.
|
|
||||||
|
|
||||||
Try to make method parameters of the outside API accept primitives, or `json` objects, so that child components are created **inside** the component, rather than being **injected** in.
|
|
||||||
|
|
||||||
This is so that:
|
|
||||||
|
|
||||||
1. Imports are much cleaner for the end user, no need for:
|
|
||||||
```ts
|
|
||||||
import { ChildComponent } from "./my-feature/sub-component/deeper/.../my-deep.component";
|
|
||||||
```
|
|
||||||
|
|
||||||
2. This is what I consider "leakage". The code is aware of the underlying implementation of the component.
|
|
||||||
3. It means the end user does not need to import and create the child component to be injected.
|
|
||||||
|
|
||||||
**Do not**
|
|
||||||
|
|
||||||
`TableFloatProperties` is a class. The outside world would have to `new` up the object, and inject it in like so:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
public float(tableFloatProperties: TableFloatProperties): Table
|
|
||||||
```
|
|
||||||
|
|
||||||
```ts
|
|
||||||
table.float(new TableFloatProperties(...));
|
|
||||||
```
|
|
||||||
|
|
||||||
**Do**
|
**Do**
|
||||||
|
|
||||||
`ITableFloatOptions` is an interface for a JSON of primitives. The end user would need to pass in a json object and not need to worry about the internals:
|
`ITableFloatOptions` is an interface for a JSON of primitives. The end user would need to pass in a json object and not need to worry about the internals:
|
||||||
@ -71,30 +42,28 @@ This is so that:
|
|||||||
public float(tableFloatOptions: ITableFloatOptions): Table
|
public float(tableFloatOptions: ITableFloatOptions): Table
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Delcariative API
|
||||||
|
|
||||||
|
Make sure the API is declarative, so no _method calling_ or _mutation_. This is a design decision, consistent with the rest of the project. There are benefits to delcariative code over other styles of code, explained here: https://dzone.com/articles/why-declarative-coding-makes-you-a-better-programm
|
||||||
|
|
||||||
|
**Do not:**
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
table.float({...});
|
const paragraph = doc.createParagraph();
|
||||||
|
const text = paragraph.createText();
|
||||||
|
text.contents = "Hello World";
|
||||||
```
|
```
|
||||||
|
|
||||||
## Add vs Create
|
**Do**
|
||||||
|
|
||||||
This is just a guideline, and the rules can sometimes be broken.
|
|
||||||
|
|
||||||
* Use `create` if the method `new`'s up an element inside:
|
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
public createParagraph() {
|
doc.addSection({
|
||||||
const paragraph = new Paragraph();
|
children: [
|
||||||
this.root.push(paragraph);
|
new Paragraph({
|
||||||
}
|
children: [new TextRun("Hello World")],
|
||||||
```
|
}),
|
||||||
|
],
|
||||||
* Use `add` if you add the element into the method as a parameter.
|
});
|
||||||
*Note:* This may look like its breaking the previous guideline, but it has semantically different meanings. The previous one is using data to construct an object, whereas this one is simply adding elements into the document:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
public add(paragraph: Paragraph) {
|
|
||||||
this.root.push(paragraph);
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Getters and Setters
|
## Getters and Setters
|
||||||
@ -107,7 +76,7 @@ public get Level() {
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
There is no performance advantage by doing this. It means we don't need to prefix all private variables with the ugly `_`:
|
This is the convention of this project. There is no performance advantage by doing this. It means we don't need to prefix all private variables with `_`:
|
||||||
|
|
||||||
**Do not:**
|
**Do not:**
|
||||||
|
|
||||||
@ -121,30 +90,6 @@ private get _level: string;
|
|||||||
private get level: string;
|
private get level: string;
|
||||||
```
|
```
|
||||||
|
|
||||||
## Temporal Methods
|
|
||||||
|
|
||||||
Some methods are `non-temporal`, which means regardless of when you call the method, it will have the same affect on the document. For example, setting the width of a table at the end of the document will have the same effect as setting the width at the start:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
table.setWidth(1000); // now removed as of version 5.0.0
|
|
||||||
```
|
|
||||||
|
|
||||||
Whereas some methods are `temporal`, which means depending on the time-frame they are called, it would produce a difference result. For example, moving `createParagraph()` around your code will physically alter the document.
|
|
||||||
|
|
||||||
```ts
|
|
||||||
doc.createParagraph("hello");
|
|
||||||
```
|
|
||||||
|
|
||||||
If a method is `non-temporal`, put it in the objects `constructor`. For example:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
const table = new Table(width: number);
|
|
||||||
```
|
|
||||||
|
|
||||||
`Non-temporal` methods are usually methods which can only be used one time and one time only. For example, `.float()`. It does not make sense to call `.float()` again if its already floating.
|
|
||||||
|
|
||||||
I am not sure what the real term is, but this will do.
|
|
||||||
|
|
||||||
## Interfaces over type alias
|
## Interfaces over type alias
|
||||||
|
|
||||||
Do not use `type`, but rather use `Interfaces`. `type` cannot be extended, and a class cannot implement it.
|
Do not use `type`, but rather use `Interfaces`. `type` cannot be extended, and a class cannot implement it.
|
||||||
@ -152,14 +97,14 @@ Do not use `type`, but rather use `Interfaces`. `type` cannot be extended, and a
|
|||||||
> "In general, use what you want ( type alias / interface ) just be consistent"
|
> "In general, use what you want ( type alias / interface ) just be consistent"
|
||||||
> "always use interface for public API's definition when authoring a library or 3rd party ambient type definitions"
|
> "always use interface for public API's definition when authoring a library or 3rd party ambient type definitions"
|
||||||
>
|
>
|
||||||
> * https://medium.com/@martin_hotell/interface-vs-type-alias-in-typescript-2-7-2a8f1777af4c
|
> - https://medium.com/@martin_hotell/interface-vs-type-alias-in-typescript-2-7-2a8f1777af4c
|
||||||
|
|
||||||
`Interface` is generally preferred over `type`: https://stackoverflow.com/questions/37233735/typescript-interfaces-vs-types
|
`Interface` is generally preferred over `type`: https://stackoverflow.com/questions/37233735/typescript-interfaces-vs-types
|
||||||
|
|
||||||
**Do not:**
|
**Do not:**
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
type RelationshipFileInfo = { id: number, target: string };
|
type RelationshipFileInfo = { id: number; target: string };
|
||||||
```
|
```
|
||||||
|
|
||||||
**Do:**
|
**Do:**
|
||||||
@ -193,26 +138,26 @@ enum WeaponType = {
|
|||||||
|
|
||||||
## Spell correctly, in full and in American English
|
## Spell correctly, in full and in American English
|
||||||
|
|
||||||
I am not sure where these habits in software development come from, but I do not believe it is beneficial:
|
|
||||||
|
|
||||||
**Do not:**
|
**Do not:**
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
readdy // misspelling
|
readdy; // misspelling
|
||||||
perm // abbreviation
|
perm; // abbreviation
|
||||||
conf // abbreviation
|
conf; // abbreviation
|
||||||
cnty // abbreviation
|
cnty; // abbreviation
|
||||||
relationFile // abbreviation
|
relationFile; // abbreviation
|
||||||
colour // U.K. English
|
colour; // U.K. English
|
||||||
```
|
```
|
||||||
|
|
||||||
**Do:**
|
**Do:**
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
ready
|
ready;
|
||||||
permission
|
permission;
|
||||||
config
|
config;
|
||||||
country
|
country;
|
||||||
relationshipFile
|
relationshipFile;
|
||||||
color
|
color;
|
||||||
```
|
```
|
||||||
|
|
||||||
## Keep files small (within reason)
|
## Keep files small (within reason)
|
||||||
|
219
docs/examples.md
219
docs/examples.md
@ -1,219 +0,0 @@
|
|||||||
# Examples
|
|
||||||
|
|
||||||
> All examples can run independently and can be found in the `/demo` folder of the project
|
|
||||||
|
|
||||||
All the examples below can be ran locally, to do so, run the following command:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
npm run demo
|
|
||||||
```
|
|
||||||
|
|
||||||
This command will run the `demo selector app` in the `/demo` folder. It will prompt you to select a demo number, which will run a demo from that folder.
|
|
||||||
|
|
||||||
## Simple
|
|
||||||
|
|
||||||
A simple hello world of the `docx` library:
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo1.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo1.ts_
|
|
||||||
|
|
||||||
## Styles
|
|
||||||
|
|
||||||
### Styling with JS
|
|
||||||
|
|
||||||
This example shows how to customise the look and feel of a document using JS configuration
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo2.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo2.ts_
|
|
||||||
|
|
||||||
### Styling with XML
|
|
||||||
|
|
||||||
This example shows how to customise the look and feel of a document using XML configuration
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo13.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo13.ts_
|
|
||||||
|
|
||||||
## Numbering
|
|
||||||
|
|
||||||
This example shows many levels of numbering
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo3.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo3.ts_
|
|
||||||
|
|
||||||
## Table
|
|
||||||
|
|
||||||
Example of simple table
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo4.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo4.ts_
|
|
||||||
|
|
||||||
### Styling table borders
|
|
||||||
|
|
||||||
Styling the borders of a table
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo20.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo20.ts_
|
|
||||||
|
|
||||||
## Images
|
|
||||||
|
|
||||||
### Add image to the document
|
|
||||||
|
|
||||||
Importing Images from file system path
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo5.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo5.ts_
|
|
||||||
|
|
||||||
### Add images to header and footer
|
|
||||||
|
|
||||||
Example showing how to add image to headers and footers
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo9.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo9.ts_
|
|
||||||
|
|
||||||
### Scaling images
|
|
||||||
|
|
||||||
Example showing how to scale images
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo12.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo12.ts_
|
|
||||||
|
|
||||||
### Add Image to media before adding to document
|
|
||||||
|
|
||||||
This is the best way to add an image to a document because you can add the same image in two locations without increasing document size by re-using the same image
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo23.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo23.ts_
|
|
||||||
|
|
||||||
### Add image to table
|
|
||||||
|
|
||||||
As before, to add an image to a table, you would need to add it to the `Media` object first
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo24.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo24.ts_
|
|
||||||
|
|
||||||
### Images using Base64 URI
|
|
||||||
|
|
||||||
If you want to use a Base64 image instead
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo18.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo18.ts_
|
|
||||||
|
|
||||||
## Margins
|
|
||||||
|
|
||||||
Example showing how to set custom margins
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo6.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo6.ts_
|
|
||||||
|
|
||||||
## Orientation
|
|
||||||
|
|
||||||
Example showing how to set the document to `landscape` or `portrait`
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo7.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo7.ts_
|
|
||||||
|
|
||||||
## Headers & Footers
|
|
||||||
|
|
||||||
Example showing how to add headers and footers
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo8.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo8.ts_
|
|
||||||
|
|
||||||
## Multiple headers and footers
|
|
||||||
|
|
||||||
Check out `Sections` for this feature
|
|
||||||
|
|
||||||
## Page Breaks
|
|
||||||
|
|
||||||
### Normal page breaks
|
|
||||||
|
|
||||||
Example showing how to page break
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo14.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo14.ts_
|
|
||||||
|
|
||||||
### Page break before
|
|
||||||
|
|
||||||
Example showing how to page break before like in Word
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo15.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo15.ts_
|
|
||||||
|
|
||||||
## Sections
|
|
||||||
|
|
||||||
Example of how sections work. Sections allow multiple headers and footers, and `landscape`/`portrait` inside the same document.
|
|
||||||
Also you can have different page number formats and starts for different sections.
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo16.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo16.ts_
|
|
||||||
|
|
||||||
## Footnotes
|
|
||||||
|
|
||||||
Example of how to add footnotes. Good for references
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo17.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo17.ts_
|
|
||||||
|
|
||||||
## Packers
|
|
||||||
|
|
||||||
## Buffer output
|
|
||||||
|
|
||||||
Example showing how to use the Buffer packer and then write that buffer to the file system
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo19.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo19.ts_
|
|
||||||
|
|
||||||
|
|
||||||
## Bookmarks
|
|
||||||
|
|
||||||
Example showing how to make bookmarks to make internal hyperlinks within the document
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo21.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo21.ts_
|
|
||||||
|
|
||||||
## Bidirectional text
|
|
||||||
|
|
||||||
Example showing how to use bidirectional text for certain languages such as Hebrew
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo22.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo22.ts_
|
|
||||||
|
|
||||||
## Showcase
|
|
||||||
|
|
||||||
### My CV
|
|
||||||
|
|
||||||
Example showing how to add headers and footers
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo10.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo10.ts_
|
|
||||||
|
|
||||||
### Style and Images
|
|
||||||
|
|
||||||
This example shows how to customise the look and feel of a document and add images
|
|
||||||
|
|
||||||
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/demo11.ts ':include')
|
|
||||||
|
|
||||||
_Source: https://github.com/dolanmiu/docx/blob/master/demo/demo11.ts_
|
|
@ -1,12 +1,11 @@
|
|||||||
<!DOCTYPE html>
|
<!DOCTYPE html>
|
||||||
<html lang="en">
|
<html lang="en">
|
||||||
|
|
||||||
<head>
|
<head>
|
||||||
<meta charset="UTF-8">
|
<meta charset="UTF-8" />
|
||||||
<title>docx - Generate .docx documents with JavaScript</title>
|
<title>docx - Generate .docx documents with JavaScript</title>
|
||||||
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
|
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
|
||||||
<meta name="description" content="Generate .docx documents with JavaScript">
|
<meta name="description" content="Generate .docx documents with JavaScript" />
|
||||||
<meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
|
<meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0" />
|
||||||
<link
|
<link
|
||||||
rel="stylesheet"
|
rel="stylesheet"
|
||||||
href="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/style.min.css"
|
href="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/style.min.css"
|
||||||
@ -19,22 +18,19 @@
|
|||||||
<div id="app"></div>
|
<div id="app"></div>
|
||||||
<script>
|
<script>
|
||||||
window.$docsify = {
|
window.$docsify = {
|
||||||
name: 'docx',
|
name: "docx",
|
||||||
repo: 'https://github.com/dolanmiu/docx',
|
repo: "https://github.com/dolanmiu/docx",
|
||||||
loadSidebar: true,
|
loadSidebar: true,
|
||||||
subMaxLevel: 2,
|
subMaxLevel: 2,
|
||||||
search: 'auto',
|
search: "auto",
|
||||||
}
|
coverpage: true,
|
||||||
|
};
|
||||||
</script>
|
</script>
|
||||||
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
|
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
|
||||||
<script src="//unpkg.com/docsify/lib/plugins/emoji.min.js"></script>
|
<script src="//unpkg.com/docsify/lib/plugins/emoji.min.js"></script>
|
||||||
<script src="https://unpkg.com/docsify-copy-code@2"></script>
|
<script src="https://unpkg.com/docsify-copy-code@2"></script>
|
||||||
<script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
|
<script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
|
||||||
<script src="//unpkg.com/prismjs/components/prism-typescript.min.js"></script>
|
<script src="//unpkg.com/prismjs/components/prism-typescript.min.js"></script>
|
||||||
<script
|
<script src="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/index.min.js" type="text/javascript"></script>
|
||||||
src="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/index.min.js"
|
|
||||||
type="text/javascript">
|
|
||||||
</script>
|
|
||||||
</body>
|
</body>
|
||||||
|
|
||||||
</html>
|
</html>
|
||||||
|
@ -2,11 +2,7 @@
|
|||||||
|
|
||||||
> Packers are the way in which `docx` turns your code into `.docx` format. It is completely decoupled from the `docx.Document`.
|
> Packers are the way in which `docx` turns your code into `.docx` format. It is completely decoupled from the `docx.Document`.
|
||||||
|
|
||||||
Packers in `version 4` and above are now one single `Packer`. It works in both a node and browser environment (Angular etc). Now, the packer returns a `Buffer`, `Blob` or `base64 string`. It is up to you to take that and persist it with node's `fs`, send it down as a downloadable file, or anything else you wish. As of version 4, this library will not have options to export to PDF.
|
Packers works in both a node and browser environment (Angular etc). Now, the packer returns a `Buffer`, `Blob` or `base64 string`. It is up to you to take that and persist it with node's `fs`, send it down as a downloadable file, or anything else you wish. As of `version 4+`, this library will not have options to export to PDF.
|
||||||
|
|
||||||
## Version 5
|
|
||||||
|
|
||||||
Packers in `version 5` and above are now static methods on `Packer`.
|
|
||||||
|
|
||||||
### Export as Buffer
|
### Export as Buffer
|
||||||
|
|
||||||
@ -36,117 +32,3 @@ Packer.toBlob(doc).then((blob) => {
|
|||||||
saveAs(blob, "example.docx");
|
saveAs(blob, "example.docx");
|
||||||
});
|
});
|
||||||
```
|
```
|
||||||
|
|
||||||
## Version 4
|
|
||||||
|
|
||||||
The `Packer` in `version 4` requires an instance of `Packer`, so be sure to `new` it.
|
|
||||||
|
|
||||||
### Export as Buffer
|
|
||||||
|
|
||||||
This will return a NodeJS `Buffer`. If this is used in the browser, it will return a `UInt8Array` instead.
|
|
||||||
|
|
||||||
```ts
|
|
||||||
const packer = new docx.Packer();
|
|
||||||
|
|
||||||
packer.toBuffer(doc).then((buffer) => {
|
|
||||||
fs.writeFileSync("My Document.docx", buffer);
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### Export as a `base64` string
|
|
||||||
|
|
||||||
```ts
|
|
||||||
const packer = new docx.Packer();
|
|
||||||
|
|
||||||
packer.toBase64String(doc).then((string) => {
|
|
||||||
console.log(string);
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### Export as Blob
|
|
||||||
|
|
||||||
This is useful if you want to send it as an downloadable in a browser environment.
|
|
||||||
|
|
||||||
```ts
|
|
||||||
const packer = new docx.Packer();
|
|
||||||
|
|
||||||
packer.toBlob(doc).then((blob) => {
|
|
||||||
// saveAs from FileSaver will download the file
|
|
||||||
saveAs(blob, "example.docx");
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
## Version 3 and below
|
|
||||||
|
|
||||||
### File System Packer
|
|
||||||
|
|
||||||
```ts
|
|
||||||
const docx = require("docx");
|
|
||||||
|
|
||||||
const doc = new docx.Document();
|
|
||||||
const exporter = new docx.LocalPacker(doc);
|
|
||||||
exporter.pack("My Document");
|
|
||||||
// Word Document is in file system
|
|
||||||
```
|
|
||||||
|
|
||||||
### Buffer Packer
|
|
||||||
|
|
||||||
```ts
|
|
||||||
const docx = require("docx");
|
|
||||||
|
|
||||||
const doc = new docx.Document();
|
|
||||||
const exporter = new docx.BufferPacker(doc);
|
|
||||||
const buffer = exporter.pack();
|
|
||||||
```
|
|
||||||
|
|
||||||
### Stream Packer
|
|
||||||
|
|
||||||
Creates a `node` `Readable` stream
|
|
||||||
|
|
||||||
```ts
|
|
||||||
const docx = require("docx");
|
|
||||||
|
|
||||||
const doc = new docx.Document();
|
|
||||||
const exporter = new docx.StreamPacker(doc);
|
|
||||||
const stream = exporter.pack();
|
|
||||||
```
|
|
||||||
|
|
||||||
### Express Packer
|
|
||||||
|
|
||||||
The old express packer is now deprecated and may disappear soon, so you should upgrade.
|
|
||||||
|
|
||||||
The reason for this is because it means this project needs to know about and use `express`, which for a Word document generator, does not sound right. Seperation of concerns.
|
|
||||||
|
|
||||||
It will still be usable (for now), but it is ill advised.
|
|
||||||
|
|
||||||
I used the express exporter in my [website](http://www.dolan.bio).
|
|
||||||
|
|
||||||
The recommended way is to use the `StreamPacker` and handle the `express` magic outside of the library:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
const docx = require("docx");
|
|
||||||
|
|
||||||
const doc = new docx.Document();
|
|
||||||
const exporter = new docx.StreamPacker(doc);
|
|
||||||
|
|
||||||
const stream = exporter.pack();
|
|
||||||
|
|
||||||
// Express' response object
|
|
||||||
res.attachment("yourfile.xlsx");
|
|
||||||
stream.pipe(res);
|
|
||||||
```
|
|
||||||
|
|
||||||
where `res` is the response object obtained through the Express router. It is that simple. The file will begin downloading in the browser.
|
|
||||||
|
|
||||||
### PDF Exporting
|
|
||||||
|
|
||||||
You can export your word document as a PDF file like so:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
const exporter = new docx.LocalPacker(doc);
|
|
||||||
exporter.packPdf("My Document");
|
|
||||||
|
|
||||||
// Express
|
|
||||||
const exporter = new docx.ExpressPacker(doc, res);
|
|
||||||
exporter.packPdf("My Document");
|
|
||||||
```
|
|
||||||
|
40
package-lock.json
generated
40
package-lock.json
generated
@ -197,7 +197,7 @@
|
|||||||
},
|
},
|
||||||
"@sinonjs/formatio": {
|
"@sinonjs/formatio": {
|
||||||
"version": "2.0.0",
|
"version": "2.0.0",
|
||||||
"resolved": "https://registry.npmjs.org/@sinonjs/formatio/-/formatio-2.0.0.tgz",
|
"resolved": "http://registry.npmjs.org/@sinonjs/formatio/-/formatio-2.0.0.tgz",
|
||||||
"integrity": "sha512-ls6CAMA6/5gG+O/IdsBcblvnd8qcO/l1TYoNeAzp3wcISOxlPXQEus0mLcdwazEkWjaBdaJ3TaxmNgCLWwvWzg==",
|
"integrity": "sha512-ls6CAMA6/5gG+O/IdsBcblvnd8qcO/l1TYoNeAzp3wcISOxlPXQEus0mLcdwazEkWjaBdaJ3TaxmNgCLWwvWzg==",
|
||||||
"dev": true,
|
"dev": true,
|
||||||
"requires": {
|
"requires": {
|
||||||
@ -718,7 +718,7 @@
|
|||||||
},
|
},
|
||||||
"util": {
|
"util": {
|
||||||
"version": "0.10.3",
|
"version": "0.10.3",
|
||||||
"resolved": "https://registry.npmjs.org/util/-/util-0.10.3.tgz",
|
"resolved": "http://registry.npmjs.org/util/-/util-0.10.3.tgz",
|
||||||
"integrity": "sha1-evsa/lCAUkZInj23/g7TeTNqwPk=",
|
"integrity": "sha1-evsa/lCAUkZInj23/g7TeTNqwPk=",
|
||||||
"dev": true,
|
"dev": true,
|
||||||
"requires": {
|
"requires": {
|
||||||
@ -747,7 +747,7 @@
|
|||||||
},
|
},
|
||||||
"async": {
|
"async": {
|
||||||
"version": "0.9.2",
|
"version": "0.9.2",
|
||||||
"resolved": "https://registry.npmjs.org/async/-/async-0.9.2.tgz",
|
"resolved": "http://registry.npmjs.org/async/-/async-0.9.2.tgz",
|
||||||
"integrity": "sha1-rqdNXmHB+JlhO/ZL2mbUx48v0X0=",
|
"integrity": "sha1-rqdNXmHB+JlhO/ZL2mbUx48v0X0=",
|
||||||
"dev": true
|
"dev": true
|
||||||
},
|
},
|
||||||
@ -821,7 +821,7 @@
|
|||||||
},
|
},
|
||||||
"chalk": {
|
"chalk": {
|
||||||
"version": "1.1.3",
|
"version": "1.1.3",
|
||||||
"resolved": "https://registry.npmjs.org/chalk/-/chalk-1.1.3.tgz",
|
"resolved": "http://registry.npmjs.org/chalk/-/chalk-1.1.3.tgz",
|
||||||
"integrity": "sha1-qBFcVeSnAv5NFQq9OHKCKn4J/Jg=",
|
"integrity": "sha1-qBFcVeSnAv5NFQq9OHKCKn4J/Jg=",
|
||||||
"dev": true,
|
"dev": true,
|
||||||
"requires": {
|
"requires": {
|
||||||
@ -1568,7 +1568,7 @@
|
|||||||
},
|
},
|
||||||
"commander": {
|
"commander": {
|
||||||
"version": "2.15.1",
|
"version": "2.15.1",
|
||||||
"resolved": "https://registry.npmjs.org/commander/-/commander-2.15.1.tgz",
|
"resolved": "http://registry.npmjs.org/commander/-/commander-2.15.1.tgz",
|
||||||
"integrity": "sha512-VlfT9F3V0v+jr4yxPc5gg9s62/fIVWsd2Bk2iD435um1NlGMYdVCq+MjcXnhYq2icNOizHr1kK+5TI6H0Hy0ag==",
|
"integrity": "sha512-VlfT9F3V0v+jr4yxPc5gg9s62/fIVWsd2Bk2iD435um1NlGMYdVCq+MjcXnhYq2icNOizHr1kK+5TI6H0Hy0ag==",
|
||||||
"dev": true
|
"dev": true
|
||||||
},
|
},
|
||||||
@ -2702,7 +2702,7 @@
|
|||||||
},
|
},
|
||||||
"fast-deep-equal": {
|
"fast-deep-equal": {
|
||||||
"version": "1.1.0",
|
"version": "1.1.0",
|
||||||
"resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-1.1.0.tgz",
|
"resolved": "http://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-1.1.0.tgz",
|
||||||
"integrity": "sha1-wFNHeBfIa1HaqFPIHgWbcz0CNhQ=",
|
"integrity": "sha1-wFNHeBfIa1HaqFPIHgWbcz0CNhQ=",
|
||||||
"dev": true
|
"dev": true
|
||||||
},
|
},
|
||||||
@ -4420,7 +4420,7 @@
|
|||||||
},
|
},
|
||||||
"jsesc": {
|
"jsesc": {
|
||||||
"version": "1.3.0",
|
"version": "1.3.0",
|
||||||
"resolved": "https://registry.npmjs.org/jsesc/-/jsesc-1.3.0.tgz",
|
"resolved": "http://registry.npmjs.org/jsesc/-/jsesc-1.3.0.tgz",
|
||||||
"integrity": "sha1-RsP+yMGJKxKwgz25vHYiF226s0s=",
|
"integrity": "sha1-RsP+yMGJKxKwgz25vHYiF226s0s=",
|
||||||
"dev": true
|
"dev": true
|
||||||
},
|
},
|
||||||
@ -4681,7 +4681,7 @@
|
|||||||
},
|
},
|
||||||
"load-json-file": {
|
"load-json-file": {
|
||||||
"version": "1.1.0",
|
"version": "1.1.0",
|
||||||
"resolved": "https://registry.npmjs.org/load-json-file/-/load-json-file-1.1.0.tgz",
|
"resolved": "http://registry.npmjs.org/load-json-file/-/load-json-file-1.1.0.tgz",
|
||||||
"integrity": "sha1-lWkFcI1YtLq0wiYbBPWfMcmTdMA=",
|
"integrity": "sha1-lWkFcI1YtLq0wiYbBPWfMcmTdMA=",
|
||||||
"dev": true,
|
"dev": true,
|
||||||
"requires": {
|
"requires": {
|
||||||
@ -5028,7 +5028,7 @@
|
|||||||
},
|
},
|
||||||
"mkdirp": {
|
"mkdirp": {
|
||||||
"version": "0.5.1",
|
"version": "0.5.1",
|
||||||
"resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.1.tgz",
|
"resolved": "http://registry.npmjs.org/mkdirp/-/mkdirp-0.5.1.tgz",
|
||||||
"integrity": "sha1-MAV0OOrGz3+MR2fzhkjWaX11yQM=",
|
"integrity": "sha1-MAV0OOrGz3+MR2fzhkjWaX11yQM=",
|
||||||
"dev": true,
|
"dev": true,
|
||||||
"requires": {
|
"requires": {
|
||||||
@ -5667,7 +5667,7 @@
|
|||||||
},
|
},
|
||||||
"os-locale": {
|
"os-locale": {
|
||||||
"version": "1.4.0",
|
"version": "1.4.0",
|
||||||
"resolved": "https://registry.npmjs.org/os-locale/-/os-locale-1.4.0.tgz",
|
"resolved": "http://registry.npmjs.org/os-locale/-/os-locale-1.4.0.tgz",
|
||||||
"integrity": "sha1-IPnxeuKe00XoveWDsT0gCYA8FNk=",
|
"integrity": "sha1-IPnxeuKe00XoveWDsT0gCYA8FNk=",
|
||||||
"dev": true,
|
"dev": true,
|
||||||
"requires": {
|
"requires": {
|
||||||
@ -5870,7 +5870,7 @@
|
|||||||
},
|
},
|
||||||
"path-is-absolute": {
|
"path-is-absolute": {
|
||||||
"version": "1.0.1",
|
"version": "1.0.1",
|
||||||
"resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz",
|
"resolved": "http://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz",
|
||||||
"integrity": "sha1-F0uSaHNVNP+8es5r9TpanhtcX18=",
|
"integrity": "sha1-F0uSaHNVNP+8es5r9TpanhtcX18=",
|
||||||
"dev": true
|
"dev": true
|
||||||
},
|
},
|
||||||
@ -5947,7 +5947,7 @@
|
|||||||
},
|
},
|
||||||
"pify": {
|
"pify": {
|
||||||
"version": "2.3.0",
|
"version": "2.3.0",
|
||||||
"resolved": "https://registry.npmjs.org/pify/-/pify-2.3.0.tgz",
|
"resolved": "http://registry.npmjs.org/pify/-/pify-2.3.0.tgz",
|
||||||
"integrity": "sha1-7RQaasBDqEnqWISY59yosVMw6Qw=",
|
"integrity": "sha1-7RQaasBDqEnqWISY59yosVMw6Qw=",
|
||||||
"dev": true
|
"dev": true
|
||||||
},
|
},
|
||||||
@ -7204,7 +7204,7 @@
|
|||||||
},
|
},
|
||||||
"strip-ansi": {
|
"strip-ansi": {
|
||||||
"version": "3.0.1",
|
"version": "3.0.1",
|
||||||
"resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-3.0.1.tgz",
|
"resolved": "http://registry.npmjs.org/strip-ansi/-/strip-ansi-3.0.1.tgz",
|
||||||
"integrity": "sha1-ajhfuIU9lS1f8F0Oiq+UJ43GPc8=",
|
"integrity": "sha1-ajhfuIU9lS1f8F0Oiq+UJ43GPc8=",
|
||||||
"dev": true,
|
"dev": true,
|
||||||
"requires": {
|
"requires": {
|
||||||
@ -7756,7 +7756,7 @@
|
|||||||
},
|
},
|
||||||
"yargs": {
|
"yargs": {
|
||||||
"version": "3.10.0",
|
"version": "3.10.0",
|
||||||
"resolved": "https://registry.npmjs.org/yargs/-/yargs-3.10.0.tgz",
|
"resolved": "http://registry.npmjs.org/yargs/-/yargs-3.10.0.tgz",
|
||||||
"integrity": "sha1-9+572FfdfB0tOMDnTvvWgdFDH9E=",
|
"integrity": "sha1-9+572FfdfB0tOMDnTvvWgdFDH9E=",
|
||||||
"dev": true,
|
"dev": true,
|
||||||
"requires": {
|
"requires": {
|
||||||
@ -8181,7 +8181,7 @@
|
|||||||
},
|
},
|
||||||
"load-json-file": {
|
"load-json-file": {
|
||||||
"version": "2.0.0",
|
"version": "2.0.0",
|
||||||
"resolved": "https://registry.npmjs.org/load-json-file/-/load-json-file-2.0.0.tgz",
|
"resolved": "http://registry.npmjs.org/load-json-file/-/load-json-file-2.0.0.tgz",
|
||||||
"integrity": "sha1-eUfkIUmvgNaWy/eXvKq8/h/inKg=",
|
"integrity": "sha1-eUfkIUmvgNaWy/eXvKq8/h/inKg=",
|
||||||
"dev": true,
|
"dev": true,
|
||||||
"requires": {
|
"requires": {
|
||||||
@ -8397,13 +8397,13 @@
|
|||||||
"dependencies": {
|
"dependencies": {
|
||||||
"async": {
|
"async": {
|
||||||
"version": "1.0.0",
|
"version": "1.0.0",
|
||||||
"resolved": "https://registry.npmjs.org/async/-/async-1.0.0.tgz",
|
"resolved": "http://registry.npmjs.org/async/-/async-1.0.0.tgz",
|
||||||
"integrity": "sha1-+PwEyjoTeErenhZBr5hXjPvWR6k=",
|
"integrity": "sha1-+PwEyjoTeErenhZBr5hXjPvWR6k=",
|
||||||
"dev": true
|
"dev": true
|
||||||
},
|
},
|
||||||
"colors": {
|
"colors": {
|
||||||
"version": "1.0.3",
|
"version": "1.0.3",
|
||||||
"resolved": "https://registry.npmjs.org/colors/-/colors-1.0.3.tgz",
|
"resolved": "http://registry.npmjs.org/colors/-/colors-1.0.3.tgz",
|
||||||
"integrity": "sha1-BDP0TYCWgP3rYO0mDxsMJi6CpAs=",
|
"integrity": "sha1-BDP0TYCWgP3rYO0mDxsMJi6CpAs=",
|
||||||
"dev": true
|
"dev": true
|
||||||
},
|
},
|
||||||
@ -8417,7 +8417,7 @@
|
|||||||
},
|
},
|
||||||
"wrap-ansi": {
|
"wrap-ansi": {
|
||||||
"version": "2.1.0",
|
"version": "2.1.0",
|
||||||
"resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-2.1.0.tgz",
|
"resolved": "http://registry.npmjs.org/wrap-ansi/-/wrap-ansi-2.1.0.tgz",
|
||||||
"integrity": "sha1-2Pw9KE3QV5T+hJc8rs3Rz4JP3YU=",
|
"integrity": "sha1-2Pw9KE3QV5T+hJc8rs3Rz4JP3YU=",
|
||||||
"dev": true,
|
"dev": true,
|
||||||
"requires": {
|
"requires": {
|
||||||
@ -8550,7 +8550,7 @@
|
|||||||
},
|
},
|
||||||
"yargs": {
|
"yargs": {
|
||||||
"version": "4.8.1",
|
"version": "4.8.1",
|
||||||
"resolved": "https://registry.npmjs.org/yargs/-/yargs-4.8.1.tgz",
|
"resolved": "http://registry.npmjs.org/yargs/-/yargs-4.8.1.tgz",
|
||||||
"integrity": "sha1-wMQpJMpKqmsObaFznfshZDn53cA=",
|
"integrity": "sha1-wMQpJMpKqmsObaFznfshZDn53cA=",
|
||||||
"dev": true,
|
"dev": true,
|
||||||
"requires": {
|
"requires": {
|
||||||
@ -8594,7 +8594,7 @@
|
|||||||
},
|
},
|
||||||
"yargs-parser": {
|
"yargs-parser": {
|
||||||
"version": "2.4.1",
|
"version": "2.4.1",
|
||||||
"resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-2.4.1.tgz",
|
"resolved": "http://registry.npmjs.org/yargs-parser/-/yargs-parser-2.4.1.tgz",
|
||||||
"integrity": "sha1-hVaN488VD/SfpRgl8DqMiA3cxcQ=",
|
"integrity": "sha1-hVaN488VD/SfpRgl8DqMiA3cxcQ=",
|
||||||
"dev": true,
|
"dev": true,
|
||||||
"requires": {
|
"requires": {
|
||||||
|
Reference in New Issue
Block a user