smartyellow/docx-js
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Adding some documentation

Browse Source
This commit is contained in:
Dolan
2019-08-03 13:42:24 +01:00
parent 9938a8bcc0
commit c2c05b0140
9 changed files with 212 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
docs/README.md
View File

@ -1,5 +1,5 @@
<p align="center"> <p align="center">
<img alt="clippy the assistant" src="https://i.imgur.com/pwCV6L8.png"> <img alt="clippy the assistant" src="https://i.imgur.com/37uBGhO.gif">
</p> </p>
<p align="center"> <p align="center">
@ -22,29 +22,47 @@ Then you can `require` or `import` as usual:
let docx = require("docx"); let docx = require("docx");
``` ```
```js ```ts
import * as docx from "docx"; import * as docx from "docx";
// or
import { ... } from "docx";
``` ```
## Basic Usage ## Basic Usage
```js ```js
var fs = require("fs"); import * as fs from "fs";
var docx = require("docx"); import { Document, Packer, Paragraph, TextRun } from "docx";
// Create document // Create document
var doc = new docx.Document(); const doc = new Document();
// Add some content in the document // Documents contain sections, you can have multiple sections per document, go here to learn more about sections
var paragraph = new docx.Paragraph("Some cool text here."); // This simple example will only contain one section
// Add more text into the paragraph if you wish doc.addSection({
paragraph.addRun(new docx.TextRun("Lorem Ipsum Foo Bar")); properties: {},
doc.add(paragraph); children: [
new Paragraph({
children: [
new TextRun("Hello World"),
new TextRun({
text: "Foo Bar",
bold: true,
}),
new TextRun({
text: "Github is the best",
bold: true,
}).tab(),
],
}),
],
});
// Used to export the file into a .docx file // Used to export the file into a .docx file
var packer = new docx.Packer(); const packer = new Packer();
packer.toBuffer(doc).then((buffer) => { packer.toBuffer(doc).then((buffer) => {
fs.writeFileSync("My First Document.docx", buffer); fs.writeFileSync("My Document.docx", 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.

1
docs/_sidebar.md
View File

@ -9,6 +9,7 @@
* Usage * Usage
* [Document](usage/document.md) * [Document](usage/document.md)
* [Sections](usage/sections.md)
* [Paragraph](usage/paragraph.md) * [Paragraph](usage/paragraph.md)
* [Text](usage/text.md) * [Text](usage/text.md)
* [Image](usage/images.md) * [Image](usage/images.md)

4
docs/usage/document.md
View File

@ -33,7 +33,7 @@ const doc = new docx.Document({
You can mix and match whatever properties you want, or provide no properties. You can mix and match whatever properties you want, or provide no properties.
### units for positioning ### Units for positioning
Various parts of the API require positioning arguments. The units are "20ths of a point" from the [OOXML](http://officeopenxml.com/index.php) specification. Various parts of the API require positioning arguments. The units are "20ths of a point" from the [OOXML](http://officeopenxml.com/index.php) specification.
See [Lars Corneliussen's blog post](https://startbigthinksmall.wordpress.com/2010/01/04/points-inches-and-emus-measuring-units-in-office-open-xml/) for more information and how to convert units. See [Lars Corneliussen's blog post](https://startbigthinksmall.wordpress.com/2010/01/04/points-inches-and-emus-measuring-units-in-office-open-xml/) for more information and how to convert units.

2
docs/usage/headers-and-footers.md
View File

@ -1,5 +1,7 @@
# Headers and Footers # Headers and Footers
!> Headers and Footers requires an understanding of [Sections](usage/sections.md).
## Example ## Example
Creating Headers and footers is simple. Access the `Header` and `Footer` by doing so like this: Creating Headers and footers is simple. Access the `Header` and `Footer` by doing so like this:

10
docs/usage/images.md
View File

@ -3,7 +3,7 @@
To create a `floating` image on top of text: To create a `floating` image on top of text:
```ts ```ts
doc.createImage(fs.readFileSync("./demo/images/pizza.gif"), 200, 200, { Media.addImage(doc, fs.readFileSync("./demo/images/pizza.gif"), 200, 200, {
floating: { floating: {
horizontalPosition: { horizontalPosition: {
offset: 1014400, offset: 1014400,
@ -18,7 +18,7 @@ doc.createImage(fs.readFileSync("./demo/images/pizza.gif"), 200, 200, {
By default with no arguments, its an `inline` image: By default with no arguments, its an `inline` image:
```ts ```ts
doc.createImage(fs.readFileSync("./demo/images/parrots.bmp")); Media.addImage(doc, fs.readFileSync("./demo/images/parrots.bmp"));
``` ```
You can also create images manually and add them later: You can also create images manually and add them later:
@ -35,7 +35,7 @@ Adding images can be done in two ways:
1. Call the `createImage` method to add the image directly into the `document`: 1. Call the `createImage` method to add the image directly into the `document`:
```js ```js
doc.createImage([IMAGE_BUFFER], [WIDTH], [HEIGHT], [POSITION_OPTIONS]); Media.addImage(doc, [IMAGE_BUFFER], [WIDTH], [HEIGHT], [POSITION_OPTIONS]);
``` ```
2. Create an `image` first, then add it into the `document`: 2. Create an `image` first, then add it into the `document`:
@ -141,7 +141,7 @@ wrap: {
For example: For example:
```ts ```ts
doc.createImage(fs.readFileSync("./demo/images/pizza.gif"), 200, 200, { Media.addImage(doc, fs.readFileSync("./demo/images/pizza.gif"), 200, 200, {
floating: { floating: {
horizontalPosition: { horizontalPosition: {
offset: 2014400, offset: 2014400,
@ -184,7 +184,7 @@ margins: {
For example: For example:
```ts ```ts
doc.createImage(fs.readFileSync("./demo/images/pizza.gif"), 200, 200, { Media.addImage(doc, fs.readFileSync("./demo/images/pizza.gif"), 200, 200, {
floating: { floating: {
horizontalPosition: { horizontalPosition: {
offset: 2014400, offset: 2014400,

183
docs/usage/paragraph.md
View File

@ -2,28 +2,170 @@
> Everything (text, images, graphs etc) in OpenXML is organised in paragraphs. > Everything (text, images, graphs etc) in OpenXML is organised in paragraphs.
## Example !> Paragraphs requires an understanding of [Sections](usage/sections.md).
You can add more text to the paragraph by doing this: You can create `Paragraphs` in the following ways:
### Shorthand
```js ```js
var paragraph = new docx.Paragraph(), import { Paragraph } from "docx";
var paragraph = new Paragraph("Short hand Hello World");
``` ```
### Children Method
This method is useful for adding different `text` with different styles or adding `images` inline.
```js ```js
var text = new docx.TextRun("Lorem Ipsum Foo Bar"); var paragraph = new Paragraph({
var paragraph = new docx.Paragraph(); children: [new TextRun("Lorem Ipsum Foo Bar"), new TextRun("Hello World")],
paragraph.addRun(text); });
``` ```
### Explicit
```js ```js
var paragraph = new docx.Paragraph("Short hand notation for adding text."); var paragraph = new Paragraph({
text: "Short hand notation for adding text.",
});
``` ```
After you create the paragraph, you must add the paragraph into the `document`: After you create the paragraph, you must add the paragraph into the `document's section`. Learn more about `sections` here:
```js ```js
doc.add(paragraph); doc.addSection({
children: [paragraph],
});
```
Or the preferred convension, define the paragraph inside the section and remove the usage of variables:
```js
doc.addSection({
children: [
new Paragraph({
children: [new TextRun("Lorem Ipsum Foo Bar"), new TextRun("Hello World")],
}),
],
});
```
## Options
This is the list of options for a paragraph. A detailed explanation is below:
| Property | Type | Mandatory? | Possible Values |
| ------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------- |
| [text](#text) | `string` | Optional | |
| [heading](#heading) | `HeadingLevel` | Optional | `HEADING_1`, `HEADING_2`, `HEADING_3`, `HEADING_4`, `HEADING_5`, `HEADING_6`, `TITLE` |
| [border](#border) | `IBorderOptions` | Optional | `top`, `bottom`, `left`, `right`. Each of these are of type IBorderPropertyOptions. Click here for Example |
| [spacing](#spacing) | `ISpacingProperties` | Optional | See below for ISpacingProperties |
| outlineLevel | `number` | Optional | |
| alignment | `AlignmentType` | Optional | |
| heading | `HeadingLevel` | Optional | |
| bidirectional | `boolean` | Optional | |
| thematicBreak | `boolean` | Optional | |
| pageBreakBefore | `boolean` | Optional | |
| contextualSpacing | `boolean` | Optional | |
| indent | `IIndentAttributesProperties` | Optional | |
| keepLines | `boolean` | Optional | |
| keepNext | `boolean` | Optional | |
| children | `(TextRun or PictureRun or Hyperlink)[]` | Optional | |
| style | `string` | Optional | |
| tabStop | `{ left?: ITabStopOptions; right?: ITabStopOptions; maxRight?: { leader: LeaderType; }; center?: ITabStopOptions }` | Optional | |
| bullet | `{ level: number }` | Optional | |
| numbering | `{ num: Num; level: number; custom?: boolean }` | Optional | |
## Text
This is the text in a paragraph. You can also add text by using the `Paragraph` shorthand (mentioned above) or adding `children`.
**Example:**
```ts
const paragraph = new Paragraph({
text: "Hello World",
});
```
## Heading
**Example:**
Setting a Heading 1 paragraph with "Hello World" as it's text:
```ts
const paragraph = new Paragraph({
text: "Hello World",
heading: HeadingLevel.HEADING_1,
});
```
## Border
Add borders to a `Paragraph`. Good for making the `Paragraph` stand out
#### IBorderPropertyOptions
`top`, `bottom`, `left`, `right` of the border
| Property | Type | Notes |
| -------- | -------- | -------- |
| color | `string` | Required |
| space | `number` | Required |
| value | `string` | Required |
| size | `number` | Required |
**Example:**
Add border on the top and the bottom of the paragraph
```ts
const paragraph = new Paragraph({
text: "I have borders on my top and bottom sides!",
border: {
top: {
color: "auto",
space: 1,
value: "single",
size: 6,
},
bottom: {
color: "auto",
space: 1,
value: "single",
size: 6,
},
},
});
```
## Spacing
Adding spacing between paragraphs
### ISpacingProperties
| Property | Type | Notes |
| -------- | -------- | -------- |
| after | `number` | Optional |
| before | `number` | Optional |
| line | `number` | Optional |
| lineRule | `string` | Optional |
**Example:**
Add spacing before the paragraph:
```ts
const paragraph = new Paragraph({
text: "line with contextual spacing",
spacing: {
before: 200,
},
});
``` ```
## Styles ## Styles
@ -32,20 +174,15 @@ To create styles, please refer to the styling Wiki: https://github.com/dolanmiu/
![Word 2013 Styles menu](http://content.gcflearnfree.org/topics/233/style_apply_choose.png "Word 2013 Styles menu") ![Word 2013 Styles menu](http://content.gcflearnfree.org/topics/233/style_apply_choose.png "Word 2013 Styles menu")
### Heading1 - Heading5 ### Headings and titles
```js ```js
paragraph.heading1(); import { HeadingLevel, Paragraph } from "docx";
paragraph.heading2();
paragraph.heading3();
paragraph.heading4();
paragraph.heading5();
```
### Title const paragraph = new Paragraph({
text: "Hello World",
```js heading: HeadingLevel.TITLE,
paragraph.title(); });
``` ```
## Text Alignment ## Text Alignment
@ -71,7 +208,11 @@ paragraph.justified();
### Example ### Example
```js ```js
paragraph.heading1().center(); const paragraph = new Paragraph({
text: "Hello World",
heading: HeadingLevel.HEADING_1,
alignment: AlignmentType.CENTER,
});
``` ```
The above will create a `heading 1` which is `centered`. The above will create a `heading 1` which is `centered`.

2
docs/usage/sections.md Normal file
View File

@ -0,0 +1,2 @@
# Sections

11
docs/usage/text.md
View File

@ -1,10 +1,15 @@
# Text # Text
Paragraphs need `text run` objects. To create text: You can add multiple `text runs` in `Paragraphs`. This is the most verbose way of writing a `Paragraph` but it is also the most flexible:
```js ```js
var text = new docx.TextRun("My awesome text here for my university dissertation"); import { Paragraph, Text } from "docx";
paragraph.addRun(text);
const paragraph = new Paragraph({
children: [
new TextRun("My awesome text here for my university dissertation"),
],
});
``` ```
Text objects have methods inside which changes the way the text is displayed. Text objects have methods inside which changes the way the text is displayed.

7
src/file/paragraph/paragraph.ts
View File

@ -27,7 +27,6 @@ export interface IParagraphOptions {
readonly text?: string; readonly text?: string;
readonly border?: IBorderOptions; readonly border?: IBorderOptions;
readonly spacing?: ISpacingProperties; readonly spacing?: ISpacingProperties;
readonly runs?: Run[];
readonly outlineLevel?: number; readonly outlineLevel?: number;
readonly alignment?: AlignmentType; readonly alignment?: AlignmentType;
readonly heading?: HeadingLevel; readonly heading?: HeadingLevel;
@ -166,12 +165,6 @@ export class Paragraph extends XmlComponent {
this.properties.push(new NumberProperties(options.numbering.num.id, options.numbering.level)); this.properties.push(new NumberProperties(options.numbering.num.id, options.numbering.level));
} }
if (options.runs) {
for (const run of options.runs) {
this.root.push(run);
}
}
if (options.children) { if (options.children) {
for (const child of options.children) { for (const child of options.children) {
this.root.push(child); this.root.push(child);