Adding some documentation
This commit is contained in:
Dolan
@ -1,5 +1,5 @@
|
||||
<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 align="center">
|
||||
@ -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.
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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.
|
||||
@ -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:
|
||||
|
||||
@ -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,
|
||||
|
||||
@ -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`.
|
||||
|
||||
2
docs/usage/sections.md
Normal file
2
docs/usage/sections.md
Normal file
@ -0,0 +1,2 @@
|
||||
# Sections
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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);
|
||||
|
||||
Reference in New Issue
Block a user