+ 
-
+
@@ -22,29 +22,47 @@ Then you can `require` or `import` as usual: let docx = require("docx"); ``` -```js +```ts import * as docx from "docx"; +// or +import { ... } from "docx"; ``` ## Basic Usage ```js -var fs = require("fs"); -var docx = require("docx"); +import * as fs from "fs"; +import { Document, Packer, Paragraph, TextRun } from "docx"; // Create document -var doc = new docx.Document(); +const doc = new Document(); -// Add some content in the document -var paragraph = new docx.Paragraph("Some cool text here."); -// Add more text into the paragraph if you wish -paragraph.addRun(new docx.TextRun("Lorem Ipsum Foo Bar")); -doc.add(paragraph); +// Documents contain sections, you can have multiple sections per document, go here to learn more about sections +// This simple example will only contain one section +doc.addSection({ + properties: {}, + 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 -var packer = new docx.Packer(); +const packer = new Packer(); + 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. diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 558029dbf6..9e329b6448 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -9,6 +9,7 @@ * Usage * [Document](usage/document.md) + * [Sections](usage/sections.md) * [Paragraph](usage/paragraph.md) * [Text](usage/text.md) * [Image](usage/images.md) diff --git a/docs/usage/document.md b/docs/usage/document.md index 175e4ecad1..56f4826355 100644 --- a/docs/usage/document.md +++ b/docs/usage/document.md @@ -33,7 +33,7 @@ const doc = new docx.Document({ 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. -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. \ No newline at end of file +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. diff --git a/docs/usage/headers-and-footers.md b/docs/usage/headers-and-footers.md index 22951abdee..541214da3f 100644 --- a/docs/usage/headers-and-footers.md +++ b/docs/usage/headers-and-footers.md @@ -1,5 +1,7 @@ # Headers and Footers +!> Headers and Footers requires an understanding of [Sections](usage/sections.md). + ## Example Creating Headers and footers is simple. Access the `Header` and `Footer` by doing so like this: diff --git a/docs/usage/images.md b/docs/usage/images.md index 8f4c34643c..b108347df4 100644 --- a/docs/usage/images.md +++ b/docs/usage/images.md @@ -3,7 +3,7 @@ To create a `floating` image on top of text: ```ts -doc.createImage(fs.readFileSync("./demo/images/pizza.gif"), 200, 200, { +Media.addImage(doc, fs.readFileSync("./demo/images/pizza.gif"), 200, 200, { floating: { horizontalPosition: { 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: ```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: @@ -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`: ```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`: @@ -141,7 +141,7 @@ wrap: { For example: ```ts -doc.createImage(fs.readFileSync("./demo/images/pizza.gif"), 200, 200, { +Media.addImage(doc, fs.readFileSync("./demo/images/pizza.gif"), 200, 200, { floating: { horizontalPosition: { offset: 2014400, @@ -184,7 +184,7 @@ margins: { For example: ```ts -doc.createImage(fs.readFileSync("./demo/images/pizza.gif"), 200, 200, { +Media.addImage(doc, fs.readFileSync("./demo/images/pizza.gif"), 200, 200, { floating: { horizontalPosition: { offset: 2014400, diff --git a/docs/usage/paragraph.md b/docs/usage/paragraph.md index 28f815e4b2..b5af10778c 100644 --- a/docs/usage/paragraph.md +++ b/docs/usage/paragraph.md @@ -2,28 +2,170 @@ > 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 -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 -var text = new docx.TextRun("Lorem Ipsum Foo Bar"); -var paragraph = new docx.Paragraph(); -paragraph.addRun(text); +var paragraph = new Paragraph({ + children: [new TextRun("Lorem Ipsum Foo Bar"), new TextRun("Hello World")], +}); ``` +### Explicit + ```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 -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 @@ -32,20 +174,15 @@ To create styles, please refer to the styling Wiki: https://github.com/dolanmiu/  -### Heading1 - Heading5 +### Headings and titles ```js -paragraph.heading1(); -paragraph.heading2(); -paragraph.heading3(); -paragraph.heading4(); -paragraph.heading5(); -``` +import { HeadingLevel, Paragraph } from "docx"; -### Title - -```js -paragraph.title(); +const paragraph = new Paragraph({ + text: "Hello World", + heading: HeadingLevel.TITLE, +}); ``` ## Text Alignment @@ -71,7 +208,11 @@ paragraph.justified(); ### Example ```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`. diff --git a/docs/usage/sections.md b/docs/usage/sections.md new file mode 100644 index 0000000000..f0046692d6 --- /dev/null +++ b/docs/usage/sections.md @@ -0,0 +1,2 @@ +# Sections + diff --git a/docs/usage/text.md b/docs/usage/text.md index faa2bdf2d5..ed02dad742 100644 --- a/docs/usage/text.md +++ b/docs/usage/text.md @@ -1,10 +1,15 @@ # 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 -var text = new docx.TextRun("My awesome text here for my university dissertation"); -paragraph.addRun(text); +import { Paragraph, Text } from "docx"; + +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. diff --git a/src/file/paragraph/paragraph.ts b/src/file/paragraph/paragraph.ts index 74aff05bf5..3f39ba68bc 100644 --- a/src/file/paragraph/paragraph.ts +++ b/src/file/paragraph/paragraph.ts @@ -27,7 +27,6 @@ export interface IParagraphOptions { readonly text?: string; readonly border?: IBorderOptions; readonly spacing?: ISpacingProperties; - readonly runs?: Run[]; readonly outlineLevel?: number; readonly alignment?: AlignmentType; readonly heading?: HeadingLevel; @@ -166,12 +165,6 @@ export class Paragraph extends XmlComponent { 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) { for (const child of options.children) { this.root.push(child);