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

Update documentation

Browse Source
This commit is contained in:
Dolan
2019-10-09 02:03:39 +01:00
parent 10ab3c70bf
commit 0d4c7a5fc0
2 changed files with 138 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

227
docs/usage/styling-with-js.md
View File

@ -3,112 +3,147 @@
## Example
```ts
const para = new Paragraph("To whom it may concern:").heading2().center();
const para = new Paragraph({
text: "To whom it may concern:",
heading: HeadingLevel.HEADING_2,
alignment: AlignmentType.CENTER,
});
const name = new TextRun("Name:")
.bold()
.font("Calibri")
.allCaps();
const name = new TextRun({
text: "Name:",
bold: true,
font: "Calibri",
allCaps: true,
});
```
## Available methods
## Available Options
* For run formatting:
* `.bold()`, `.italics()`, `.smallCaps()`, `.allCaps()`, `.strike()`, `.doubleStrike()`, `.subScript()`, `.superScript()`: Set the formatting property to true
* `.underline(style="single", color=null)`: Set the underline style and color
* `.color(color)`: Set the text color, using 6 hex characters for RRGGBB (no leading `#`)
* `.size(halfPts)`: Set the font size, measured in half-points
* `.font(name)`: Set the run's font
* `.style(name)`: Apply a named run style
* `.characterSpacing(value)`: Set the character spacing adjustment (in TWIPs)
* For paragraph formatting:
* `.heading1()`, `.heading2()`, `.heading3()`, `.heading4()`, `.heading5()`, `.title()`: apply the appropriate style to the paragraph
* `.left()`, `.center()`, `.right()`, `.justified()`: set the paragraph's alignment
* `.thematicBreak()`, `.pageBreak()`: Insert a thick rule or a page break beneath the paragraph
* `.leftTabStop(position)`: Add a left tab stop (measured in TWIPs from the left)
* `.maxRightTabStop()`: Add a right tab stop at the far right
* `.bullet()`: Use the default bullet style
* `.setNumbering(numbering, indentLevel)`: Use a custom numbering format for the paragraph
* `.style(name)`: Apply a named paragraph style
* `.indent(start, hanging=0)`: Set the paragraph's indent level (in TWIPs)
* `.spacing({before=0, after=0, line=0})`: Set the line and before/after on the paragraph. Before/after is measured in TWIPs, line is measured in 240ths of a line
### Run formatting
Paragraph styles have all the run formatting methods, except `style()`, and `.left()`, `.center()`, `.right()`, `.justified()`, `.thematicBreak()`, `.leftTabStop(position)`, `.maxRightTabStop()`, `.indent(start, hanging=0)`, and `.spacing({before=0, after=0, line=0})` methods.
- `bold`, `italics`, `smallCaps`, `allCaps`, `strike`, `doubleStrike`, `subScript`, `superScript`: Set the formatting property to true
- `underline(style="single", color=null)`: Set the underline style and color
- `color(color)`: Set the text color, using 6 hex characters for RRGGBB (no leading `#`)
- `size(halfPts)`: Set the font size, measured in half-points
- `font(name)`: Set the run's font
- `style(name)`: Apply a named run style
- `characterSpacing(value)`: Set the character spacing adjustment (in TWIPs)
### Paragraph formatting
- `heading1`, `heading2`, `heading3`, `heading4`, `heading5`, `title`: apply the appropriate style to the paragraph
- `left`, `center`, `right`, `justified`: set the paragraph's alignment
- `thematicBreak`, `pageBreak`: Insert a thick rule or a page break beneath the paragraph
- `leftTabStop(position)`: Add a left tab stop (measured in TWIPs from the left)
- `maxRightTabStop`: Add a right tab stop at the far right
- `bullet`: Use the default bullet style
- `setNumbering(numbering, indentLevel)`: Use a custom numbering format for the paragraph
- `style(name)`: Apply a named paragraph style
- `indent(start, hanging=0)`: Set the paragraph's indent level (in TWIPs)
- `spacing({before=0, after=0, line=0})`: Set the line and before/after on the paragraph. Before/after is measured in TWIPs, line is measured in 240ths of a line
Paragraph styles have all the run formatting methods, except `style()`, and `left()`, `center()`, `right()`, `justified()`, `thematicBreak()`, `leftTabStop(position)`, `maxRightTabStop()`, `indent(start, hanging=0)`, and `spacing({before=0, after=0, line=0})` methods.
## Detailed guide
There are 4 items in DOCX that can be styled:
There are 4 items in `docx` that can be styled:
* Characters: Attributes that can change within a paragraph. e.g., bold, italics, etc.
* Paragraphs: Attributes like indent, text alignment, line spacing, etc.
* Tables: Border styles, table formats, etc.
* List items: These are the numbers and bullets that are automatically inserted
- Characters: Attributes that can change within a paragraph. e.g., bold, italics, etc.
- Paragraphs: Attributes like indent, text alignment, line spacing, etc.
- Tables: Border styles, table formats, etc.
- List items: These are the numbers and bullets that are automatically inserted
There are a few different ways of styling this content in DOCX, which somewhat resemble the HTML/CSS approach. In order of greatest to lowest priority:
There are a few different ways of styling this content in `docx`, which somewhat resemble the HTML/CSS approach. In order of greatest to lowest priority:
1. Direct formatting (AKA inline formatting)
2. Centrally defined styles (similar to external CSS)
1. Direct formatting (inline formatting)
2. Declaritive Styles (similar to external CSS)
3. Document defaults (similar to a `*` rule in CSS)
Unlike CSS, less specific rules don't _necessarily_ override parent rules. The rules are a bit wonky, but if you're interested, see the [advanced formatting section](#Advanced formatting).
### Direct formatting (AKA inline formatting)
### Direct formatting (inline formatting)
This is the type of formatting that your uncle uses when he types out documents: _N ... a ... m ... e ... :_ Then he grabs the mouse, highlights _Name:_ and moves over to the **B** for bold. This manner of formatting results in markup that is similar to writing `<span style="bold: true">Name:</span>` if you were typing out HTML. DOCX (the format) allows you to specify this for any of the four types of items. `docx` (the library) only supports this type of formatting for paragraphs and characters, using a _fluent_ api. Thus you could do:
This is the type of formatting that your uncle uses when he types out documents: _N ... a ... m ... e ... :_ Then he grabs the mouse, highlights _Name:_ and moves over to the **B** for bold. This manner of formatting results in markup that is similar to writing `<span style="bold: true">Name:</span>` if you were typing out HTML. `docx` (the format) allows you to specify this for any of the four types of items. `docx` (the library) only supports this type of formatting for paragraphs and characters, using a _fluent_ api. Thus you could do:
```ts
const name = new TextRun("Name:")
.bold()
.font("Calibri")
.allCaps();
const name = new TextRun({
text: "Name:",
bold: true,
font: "Calibri",
allCaps: true,
});
```
Or for paragraph formatting:
```ts
const para = new Paragraph("To whom it may concern:").heading2().center();
const para = new Paragraph({
text: "To whom it may concern:",
heading: HeadingLevel.HEADING_2,
alignment: AlignmentType.CENTER,
});
```
### Centrally defined styles (similar to external CSS)
### Declaritive Styles (similar to external CSS)
DOCX files contain a styles section separate from the main content, much like how HTML includes CSS files. Unlike CSS, DOCX distinguishes between styles meant for tables (which show up in the table formatting toolbar), styles for lists (which show up under bullets and numbering), and styles for runs and paragraphs, which show up as dropdowns offering standard styles, like "Heading 1", "Caption", or any custom styles defined in that document. <!-- TODO: add pictures of the panes -->. `docx` allows you to define these styles using a fluent interface as well.
`docx` files contain a styles section separate from the main content, much like how HTML includes CSS files. Unlike CSS, `docx` distinguishes between styles meant for tables (which show up in the table formatting toolbar), styles for lists (which show up under bullets and numbering), and styles for runs and paragraphs, which show up as dropdowns offering standard styles, like "Heading 1", "Caption", or any custom styles defined in that document. <!-- TODO: add pictures of the panes -->. `docx` allows you to define these styles using a fluent interface as well.
There are three parts to using custom styles with `docx`:
To add styles, define your custom styles in the `document`:
1. Create a container object for the style definitions:
```ts
const myStyles = new docx.Styles();
```
2. Define your custom styles, similar to the way you would format a paragraph or run
```ts
// The first argument is an ID you use to apply the style to paragraphs
// The second argument is a human-friendly name to show in the UI
myStyles
.createParagraphStyle("myWonkyStyle", "My Wonky Style")
.basedOn("Normal")
.next("Normal")
.color("999999")
.italics()
.indent(720) // 720 TWIP === 720 / 20 pt === .5 in
.spacing({ line: 276 }); // 276 / 240 = 1.15x line spacing
myStyles
.createParagraphStyle("Heading2", "Heading 2")
.basedOn("Normal")
.next("Normal")
.quickFormat()
.size(26) // 26 half-points === 13pt font
.bold()
.underline("double", "FF0000")
.spacing({ before: 240, after: 120 }); // TWIP for both
```
3. When you generate your document, make sure to pass the `styles` container to the `Packer`:
```ts
Packer.pack(myOutStream);
```
```ts
// The first argument is an ID you use to apply the style to paragraphs
// The second argument is a human-friendly name to show in the UI
const doc = new Document({
creator: "Clippy",
title: "Sample Document",
description: "A brief example of using docx",
styles: {
paragraphStyles: [
{
id: "myWonkyStyle",
name: "My Wonky Style",
basedOn: "Normal",
next: "Normal",
quickFormat: true,
run: {
italics: true,
color: "999999",
},
paragraph: {
spacing: {
line: 276,
},
indent: {
left: 720,
},
},
},
{
id: "Heading2",
name: "Heading 2",
basedOn: "Normal",
next: "Normal",
quickFormat: true,
run: {
size: 26
bold: true,
color: "999999",
{
type: UnderlineType.DOUBLE,
color: "FF0000",
},
},
paragraph: {
spacing: {
before: 240,
after: 120
},
},
},
]
}
});
```
**Note**: If you are using the `.headingX` or `.title` methods of paragraphs, you must make sure to define `HeadingX` or `Title` styles for these. Otherwise they'll show up unstyled :(. If you are using the `.bullet` or `.setNumbering` methods, you need to define a `ListParagraph` style or the numbers may not show up.
@ -144,19 +179,29 @@ To determine the value of a styling property, you must first identify whether it
The following properties are treated in a special manner; they're called toggle properties:
* Bold
* All caps
* Small caps
* Italics
* Single strike-through
* Hidden
* Imprint
* Emboss
* Character outline
* Character shadow
- Bold
- All caps
- Small caps
- Italics
- Single strike-through
- Hidden
- Imprint
- Emboss
- Character outline
- Character shadow
For these properties, the rules state the following conflict resolution in case the property is specified at multiple points for the same item:
* Direct formatting trumps all if specified (either true or false)
* Otherwise, if the property is true in document defaults, the property is set to true
* Otherwise, the property's value is an XOR of its effective table, paragraph, and character values. (So specifying bold `true` on a table style and a paragraph style would result in non-bold text if a paragraph inside the table had that style)
- Direct formatting trumps all if specified (either true or false)
- Otherwise, if the property is true in document defaults, the property is set to true
- Otherwise, the property's value is an XOR of its effective table, paragraph, and character values. (So specifying bold `true` on a table style and a paragraph style would result in non-bold text if a paragraph inside the table had that style)
## Examples
### Declaritive styles
Importing Images from file system path
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/2-declaritive-styles.ts ':include')
_Source: https://github.com/dolanmiu/docx/blob/master/demo/2-declaritive-styles.ts_

4
src/file/styles/style/paragraph-style.ts
View File

@ -11,7 +11,7 @@ import {
Spacing,
ThematicBreak,
} from "file/paragraph";
import { RightTabStop } from "file/paragraph/formatting";
import { IIndentAttributesProperties, RightTabStop } from "file/paragraph/formatting";
import * as formatting from "file/paragraph/run/formatting";
import { RunProperties } from "file/paragraph/run/properties";
import { UnderlineType } from "file/paragraph/run/underline";
@ -57,7 +57,7 @@ export interface IBaseParagraphStyleOptions {
readonly thematicBreak?: boolean;
readonly rightTabStop?: number;
readonly leftTabStop?: number;
readonly indent?: object;
readonly indent?: IIndentAttributesProperties;
readonly spacing?: ISpacingProperties;
readonly keepNext?: boolean;
readonly keepLines?: boolean;