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

Declarative hyperlinks, bookmarks, tab stops and page breaks

Browse Source
This commit is contained in:
Dolan
2019-09-30 22:56:21 +01:00
parent d2dded860d
commit 04b6d8e54a
20 changed files with 207 additions and 165 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
demo/10-my-cv.ts
View File

@ -1,7 +1,7 @@
// Generate a CV
// Import from 'docx' rather than '../build' if you install from npm
import * as fs from "fs";
import { AlignmentType, Document, HeadingLevel, Packer, Paragraph, TextRun } from "../build";
import { AlignmentType, Document, HeadingLevel, Packer, Paragraph, TabStopPosition, TextRun } from "../build";
// tslint:disable:no-shadowed-variable
@ -227,7 +227,9 @@ class DocumentCreator {
public createInstitutionHeader(institutionName: string, dateText: string): Paragraph {
return new Paragraph({
tabStop: {
maxRight: {},
right: {
position: TabStopPosition.MAX,
},
},
children: [
new TextRun({

6
demo/14-page-numbers.ts
View File

@ -1,7 +1,7 @@
// Page numbers
// Import from 'docx' rather than '../build' if you install from npm
import * as fs from "fs";
import { AlignmentType, Document, Header, Packer, Paragraph, TextRun } from "../build";
import { AlignmentType, Document, Header, Packer, PageBreak, Paragraph, TextRun } from "../build";
const doc = new Document();
@ -26,8 +26,8 @@ doc.addSection({
},
children: [
new Paragraph({
text: "First Page",
}).pageBreak(),
children: [new TextRun("First Page"), new PageBreak()],
}),
new Paragraph("Second Page"),
],
});

18
demo/2-declaritive-styles.ts
View File

@ -82,14 +82,16 @@ doc.addSection({
level: 0,
},
}),
new Paragraph({}).addRun(
new TextRun({
text: "Some monospaced content",
font: {
name: "Monospace",
},
}),
),
new Paragraph({
children: [
new TextRun({
text: "Some monospaced content",
font: {
name: "Monospace",
},
}),
],
}),
new Paragraph({
text: "An aside, in light gray italics and indented",
style: "aside",

12
demo/21-bookmarks.ts
View File

@ -2,6 +2,7 @@
// Import from 'docx' rather than '../build' if you install from npm
import * as fs from "fs";
import { Document, HeadingLevel, Packer, Paragraph } from "../build";
import { PageBreak } from "../build/file/paragraph";
const LOREM_IPSUM =
"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam mi velit, convallis convallis scelerisque nec, faucibus nec leo. Phasellus at posuere mauris, tempus dignissim velit. Integer et tortor dolor. Duis auctor efficitur mattis. Vivamus ut metus accumsan tellus auctor sollicitudin venenatis et nibh. Cras quis massa ac metus fringilla venenatis. Proin rutrum mauris purus, ut suscipit magna consectetur id. Integer consectetur sollicitudin ante, vitae faucibus neque efficitur in. Praesent ultricies nibh lectus. Mauris pharetra id odio eget iaculis. Duis dictum, risus id pellentesque rutrum, lorem quam malesuada massa, quis ullamcorper turpis urna a diam. Cras vulputate metus vel massa porta ullamcorper. Etiam porta condimentum nulla nec tristique. Sed nulla urna, pharetra non tortor sed, sollicitudin molestie diam. Maecenas enim leo, feugiat eget vehicula id, sollicitudin vitae ante.";
@ -22,11 +23,16 @@ doc.addSection({
children: [
new Paragraph({
heading: HeadingLevel.HEADING_1,
}).addBookmark(bookmark),
children: [bookmark],
}),
new Paragraph("\n"),
new Paragraph(LOREM_IPSUM),
new Paragraph({}).pageBreak(),
new Paragraph({}).addHyperLink(hyperlink),
new Paragraph({
children: [new PageBreak()],
}),
new Paragraph({
children: [hyperlink],
}),
],
});

8
demo/35-hyperlinks.ts
View File

@ -4,12 +4,14 @@ import * as fs from "fs";
import { Document, Packer, Paragraph } from "../build";
const doc = new Document();
const paragraph = new Paragraph({});
const link = doc.createHyperlink("http://www.example.com", "Hyperlink");
paragraph.addHyperLink(link);
doc.addSection({
children: [paragraph],
children: [
new Paragraph({
children: [link],
}),
],
});
Packer.toBuffer(doc).then((buffer) => {

9
docs/usage/paragraph.md
View File

@ -244,10 +244,15 @@ The above example will create a heading with a page break directly under it.
## Page Break
To move to a new page (insert a page break), simply add `.pageBreak()` on a paragraph:
To move to a new page (insert a page break):
```ts
const paragraph = new docx.Paragraph("Amazing Heading").pageBreak();
const paragraph = new docx.Paragraph({
children: [
new TextRun("Amazing Heading"),
new PageBreak(),
]
});
```
The above example will create a heading and start a new page immediately afterwards.

78
docs/usage/tab-stops.md
View File

@ -2,7 +2,7 @@
> Tab stops are useful, if you are unclear of what they are, [here is a link explaining](https://en.wikipedia.org/wiki/Tab_stop). It enables side by side text which is nicely laid out without the need for tables, or constantly pressing space bar.
!> **Note**: At the moment, the unit of measurement for a tab stop is counter intuitive for a human. It is using OpenXMLs own measuring system. For example, 2268 roughly translates to 3cm. Therefore in the future, I may consider changing it to percentages or even cm.
!> **Note**: The unit of measurement for a tab stop is in [DXA](https://stackoverflow.com/questions/14360183/default-wordml-unit-measurement-pixel-or-point-or-inches)
![Word 2013 Tabs](http://www.teachucomp.com/wp-content/uploads/blog-4-22-2015-UsingTabStopsInWord-1024x577.png "Word 2013 Tab Stops")
@ -11,44 +11,86 @@ Simply call the relevant methods on the paragraph listed below. Then just add a
## Example
```ts
const paragraph = new docx.Paragraph().maxRightTabStop();
const leftText = new docx.TextRun("Hey everyone").bold();
const rightText = new docx.TextRun("11th November 2015").tab();
paragraph.addRun(leftText);
paragraph.addRun(rightText);
const paragraph = new Paragraph({
children: [new TextRun("Hey everyone").bold(), new TextRun("11th November 1999").tab()],
tabStop: {
right: {
position: TabStopPosition.MAX,
},
},
});
```
The example above will create a left aligned text, and a right aligned text on the same line. The laymans approach to this problem would be to either use text boxes or tables. YUK!
The example above will create a left aligned text, and a right aligned text on the same line. The laymans approach to this problem would be to either use text boxes or tables. Not ideal!
```ts
const paragraph = new docx.Paragraph();
paragraph.maxRightTabStop();
paragraph.leftTabStop(1000);
const text = new docx.TextRun("Second tab stop here I come!").tab().tab();
paragraph.addRun(text);
const paragraph = new Paragraph({
children: [new TextRun("Second tab stop here I come!").tab().tab()],
tabStop: {
right: {
position: TabStopPosition.MAX,
},
left: {
position: 1000,
},
},
});
```
The above shows the use of two tab stops, and how to select/use it.
## Left Tab Stop
```ts
paragraph.leftTabStop(2268);
const paragraph = new Paragraph({
tabStop: {
left: {
position: 2268,
},
},
});
```
2268 is the distance from the left side.
## Center Tab Stop
```ts
paragraph.centerTabStop(2268);
const paragraph = new Paragraph({
tabStop: {
center: {
position: 2268,
},
},
});
```
2268 is the distance from the left side.
2268 is the distance from the center.
## Right Tab Stop
```ts
paragraph.rightTabStop(2268);
const paragraph = new Paragraph({
tabStop: {
right: {
position: 2268,
},
},
});
```
2268 is the distance from the left side.
2268 is the distance fro0oum the left side.
## Max Right Tab Stop
```ts
paragraph.maxRightTabStop();
const paragraph = new Paragraph({
tabStop: {
right: {
position: TabStopPosition.MAX,
},
},
});
```
This will create a tab stop on the very edge of the right hand side. Handy for right aligning and left aligning text on the same line.

24
docs/usage/table-of-contents.md
View File

@ -47,30 +47,6 @@ Here is the list of all options that you can use to generate your tables of cont
## Examples
```ts
// Let's define the options for generate a TOC for heading 1-5 and MySpectacularStyle,
// making the entries be hyperlinks for the paragraph
const toc = new TableOfContents("Summary", {
hyperlink: true,
headingStyleRange: "1-5",
stylesWithLevels: [new StyleLevel("MySpectacularStyle", 1)],
});
doc.addTableOfContents(toc);
doc.add(new Paragraph("Header #1").heading1().pageBreakBefore());
doc.add(new Paragraph("I'm a little text, very nicely written.'"));
doc.add(new Paragraph("Header #2").heading1().pageBreakBefore());
doc.add(new Paragraph("I'm another text very nicely written.'"));
doc.add(new Paragraph("Header #2.1").heading2());
doc.add(new Paragraph("I'm another text very nicely written.'"));
doc.add(new Paragraph("My Spectacular Style #1").style("MySpectacularStyle").pageBreakBefore());
```
### Complete example
[Example](https://raw.githubusercontent.com/dolanmiu/docx/master/demo/28-table-of-contents.ts ':include')
_Source: https://github.com/dolanmiu/docx/blob/master/demo/28-table-of-contents.ts_

55
src/export/formatter.spec.ts
View File

@ -28,15 +28,52 @@ describe("Formatter", () => {
});
it("should format simple paragraph with bold text", () => {
const paragraph = new Paragraph("");
paragraph.addRun(
new TextRun({
text: "test",
bold: true,
}),
);
const newJson = formatter.format(paragraph);
assert.isDefined(newJson["w:p"][1]["w:r"][0]["w:rPr"][0]["w:b"]._attr["w:val"]);
const paragraph = new Paragraph({
children: [
new TextRun({
text: "test",
bold: true,
}),
],
});
const tree = formatter.format(paragraph);
expect(tree).to.deep.equal({
"w:p": [
{
"w:r": [
{
"w:rPr": [
{
"w:b": {
_attr: {
"w:val": true,
},
},
},
{
"w:bCs": {
_attr: {
"w:val": true,
},
},
},
],
},
{
"w:t": [
{
_attr: {
"xml:space": "preserve",
},
},
"test",
],
},
],
},
],
});
});
it("should format attributes (rsidSect)", () => {

6
src/file/footnotes/footnotes.ts
View File

@ -44,7 +44,8 @@ export class FootNotes extends XmlComponent {
line: 240,
lineRule: "auto",
},
}).addRun(new SeperatorRun()),
children: [new SeperatorRun()],
}),
);
this.root.push(begin);
@ -56,7 +57,8 @@ export class FootNotes extends XmlComponent {
line: 240,
lineRule: "auto",
},
}).addRun(new ContinuationSeperatorRun()),
children: [new ContinuationSeperatorRun()],
}),
);
this.root.push(spacing);
}

8
src/file/numbering/level.ts
View File

@ -8,8 +8,9 @@ import {
KeepLines,
KeepNext,
LeftTabStop,
MaxRightTabStop,
RightTabStop,
Spacing,
TabStopPosition,
ThematicBreak,
} from "../paragraph/formatting";
import { ParagraphProperties } from "../paragraph/properties";
@ -235,9 +236,8 @@ export class LevelBase extends XmlComponent {
return this;
}
public maxRightTabStop(): Level {
this.addParagraphProperty(new MaxRightTabStop());
return this;
public rightTabStop(position: number): Level {
return this.addParagraphProperty(new RightTabStop(position));
}
public leftTabStop(position: number): Level {

3
src/file/numbering/numbering.spec.ts
View File

@ -8,6 +8,7 @@ import { Num } from "./num";
import { Numbering } from "./numbering";
import { EMPTY_OBJECT } from "file/xml-components";
import { TabStopPosition } from "../paragraph";
describe("Numbering", () => {
let numbering: Numbering;
@ -202,7 +203,7 @@ describe("AbstractNumbering", () => {
it("#maxRightTabStop", () => {
const abstractNumbering = new AbstractNumbering(1);
const level = abstractNumbering.createLevel(0, "lowerRoman", "%0.").maxRightTabStop();
const level = abstractNumbering.createLevel(0, "lowerRoman", "%0.").rightTabStop(TabStopPosition.MAX);
const tree = new Formatter().format(level);
expect(tree["w:lvl"]).to.include({
"w:pPr": [

27
src/file/paragraph/formatting/tab-stop.spec.ts
View File

@ -2,7 +2,7 @@ import { assert } from "chai";
import { Utility } from "tests/utility";
import { LeaderType, LeftTabStop, MaxRightTabStop, RightTabStop } from "./tab-stop";
import { LeaderType, LeftTabStop, RightTabStop } from "./tab-stop";
describe("LeftTabStop", () => {
let tabStop: LeftTabStop;
@ -52,28 +52,3 @@ describe("RightTabStop", () => {
});
});
});
describe("MaxRightTabStop", () => {
let tabStop: MaxRightTabStop;
beforeEach(() => {
tabStop = new MaxRightTabStop();
});
describe("#constructor()", () => {
it("should create a Tab Stop with correct attributes", () => {
const newJson = Utility.jsonify(tabStop);
const attributes = {
val: "right",
pos: 9026,
};
assert.equal(JSON.stringify(newJson.root[0].root[0].root), JSON.stringify(attributes));
});
it("should create a Tab Stop with w:tab", () => {
const newJson = Utility.jsonify(tabStop);
assert.equal(newJson.root[0].rootKey, "w:tab");
});
});
});

10
src/file/paragraph/formatting/tab-stop.ts
View File

@ -28,6 +28,10 @@ export enum LeaderType {
UNDERSCORE = "underscore",
}
export enum TabStopPosition {
MAX = 9026,
}
export class TabAttributes extends XmlAttributeComponent<{
readonly val: TabValue;
readonly pos: string | number;
@ -49,12 +53,6 @@ export class TabStopItem extends XmlComponent {
}
}
export class MaxRightTabStop extends TabStop {
constructor(leader?: LeaderType) {
super(new TabStopItem(TabValue.RIGHT, 9026, leader));
}
}
export class LeftTabStop extends TabStop {
constructor(position: number, leader?: LeaderType) {
super(new TabStopItem(TabValue.LEFT, position, leader));

13
src/file/paragraph/paragraph.spec.ts
View File

@ -4,7 +4,7 @@ import { Formatter } from "export/formatter";
import { EMPTY_OBJECT } from "file/xml-components";
import { Numbering } from "../numbering";
import { AlignmentType, HeadingLevel, LeaderType } from "./formatting";
import { AlignmentType, HeadingLevel, LeaderType, PageBreak, TabStopPosition } from "./formatting";
import { Paragraph } from "./paragraph";
describe("Paragraph", () => {
@ -254,10 +254,12 @@ describe("Paragraph", () => {
});
describe("#maxRightTabStop()", () => {
it("should add maxRightTabStop to JSON", () => {
it("should add right tab stop to JSON", () => {
const paragraph = new Paragraph({
tabStop: {
maxRight: {},
right: {
position: TabStopPosition.MAX,
},
},
});
const tree = new Formatter().format(paragraph);
@ -492,8 +494,9 @@ describe("Paragraph", () => {
describe("#pageBreak()", () => {
it("should add page break to JSON", () => {
const paragraph = new Paragraph({});
paragraph.pageBreak();
const paragraph = new Paragraph({
children: [new PageBreak()],
});
const tree = new Formatter().format(paragraph);
expect(tree).to.deep.equal({
"w:p": [

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

@ -11,14 +11,14 @@ import { KeepLines, KeepNext } from "./formatting/keep";
import { PageBreak, PageBreakBefore } from "./formatting/page-break";
import { ContextualSpacing, ISpacingProperties, Spacing } from "./formatting/spacing";
import { HeadingLevel, Style } from "./formatting/style";
import { CenterTabStop, LeaderType, LeftTabStop, MaxRightTabStop, RightTabStop } from "./formatting/tab-stop";
import { CenterTabStop, LeaderType, LeftTabStop, RightTabStop, TabStopPosition } from "./formatting/tab-stop";
import { NumberProperties } from "./formatting/unordered-list";
import { Bookmark, Hyperlink, OutlineLevel } from "./links";
import { ParagraphProperties } from "./properties";
import { PictureRun, Run, SequentialIdentifier, TextRun } from "./run";
interface ITabStopOptions {
readonly position: number;
readonly position: number | TabStopPosition;
readonly leader?: LeaderType;
}
@ -39,9 +39,6 @@ export interface IParagraphOptions {
readonly tabStop?: {
readonly left?: ITabStopOptions;
readonly right?: ITabStopOptions;
readonly maxRight?: {
readonly leader?: LeaderType;
};
readonly center?: ITabStopOptions;
};
readonly style?: string;
@ -53,7 +50,7 @@ export interface IParagraphOptions {
readonly level: number;
readonly custom?: boolean;
};
readonly children?: Array<TextRun | PictureRun | Hyperlink>;
readonly children?: Array<TextRun | PictureRun | Hyperlink | Bookmark | PageBreak>;
}
export class Paragraph extends XmlComponent {
@ -139,10 +136,6 @@ export class Paragraph extends XmlComponent {
this.properties.push(new RightTabStop(options.tabStop.right.position, options.tabStop.right.leader));
}
if (options.tabStop.maxRight) {
this.properties.push(new MaxRightTabStop(options.tabStop.maxRight.leader));
}
if (options.tabStop.center) {
this.properties.push(new CenterTabStop(options.tabStop.center.position, options.tabStop.center.leader));
}
@ -166,34 +159,18 @@ export class Paragraph extends XmlComponent {
if (options.children) {
for (const child of options.children) {
if (child instanceof Bookmark) {
this.root.push(child.start);
this.root.push(child.text);
this.root.push(child.end);
continue;
}
this.root.push(child);
}
}
}
public addRun(run: Run): Paragraph {
this.root.push(run);
return this;
}
public addHyperLink(hyperlink: Hyperlink): Paragraph {
this.root.push(hyperlink);
return this;
}
public addBookmark(bookmark: Bookmark): Paragraph {
// Bookmarks by spec have three components, a start, text, and end
this.root.push(bookmark.start);
this.root.push(bookmark.text);
this.root.push(bookmark.end);
return this;
}
public pageBreak(): Paragraph {
this.root.push(new PageBreak());
return this;
}
public referenceFootnote(id: number): Paragraph {
this.root.push(new FootnoteReferenceRun(id));
return this;

8
src/file/paragraph/run/run.ts
View File

@ -2,6 +2,7 @@
import { ShadingType } from "file/table";
import { XmlComponent } from "file/xml-components";
import { FieldInstruction } from "file/table-of-contents/field-instruction";
import { Break } from "./break";
import { Caps, SmallCaps } from "./caps";
import { Begin, End, Separate } from "./field";
@ -56,6 +57,7 @@ export interface IRunOptions {
readonly fill: string;
readonly color: string;
};
readonly children?: Array<Begin | FieldInstruction | Separate | End>;
}
export class Run extends XmlComponent {
@ -134,6 +136,12 @@ export class Run extends XmlComponent {
this.properties.push(new Shading(options.shading.type, options.shading.fill, options.shading.color));
this.properties.push(new ShadowComplexScript(options.shading.type, options.shading.fill, options.shading.color));
}
if (options.children) {
for (const child of options.children) {
this.root.push(child);
}
}
}
public break(): Run {

6
src/file/styles/style/paragraph-style.spec.ts
View File

@ -1,11 +1,11 @@
import { expect } from "chai";
import { Formatter } from "export/formatter";
import { TabStopPosition } from "file/paragraph";
import { EMPTY_OBJECT } from "file/xml-components";
import { ParagraphStyle } from "./paragraph-style";
import { EMPTY_OBJECT } from "file/xml-components";
describe("ParagraphStyle", () => {
describe("#constructor", () => {
it("should set the style type to paragraph and use the given style id", () => {
@ -198,7 +198,7 @@ describe("ParagraphStyle", () => {
});
it("#maxRightTabStop", () => {
const style = new ParagraphStyle("myStyleId").maxRightTabStop();
const style = new ParagraphStyle("myStyleId").rightTabStop(TabStopPosition.MAX);
const tree = new Formatter().format(style);
expect(tree).to.deep.equal({
"w:style": [

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

@ -6,12 +6,12 @@ import {
KeepLines,
KeepNext,
LeftTabStop,
MaxRightTabStop,
OutlineLevel,
ParagraphProperties,
Spacing,
ThematicBreak,
} from "file/paragraph";
import { RightTabStop } from "file/paragraph/formatting";
import * as formatting from "file/paragraph/run/formatting";
import { RunProperties } from "file/paragraph/run/properties";
import { XmlComponent } from "file/xml-components";
@ -144,8 +144,8 @@ export class ParagraphStyle extends Style {
return this.addParagraphProperty(new ThematicBreak());
}
public maxRightTabStop(): ParagraphStyle {
return this.addParagraphProperty(new MaxRightTabStop());
public rightTabStop(position: number): ParagraphStyle {
return this.addParagraphProperty(new RightTabStop(position));
}
public leftTabStop(position: number): ParagraphStyle {

26
src/file/table-of-contents/table-of-contents.ts
View File

@ -16,18 +16,24 @@ export class TableOfContents extends XmlComponent {
const content = new StructuredDocumentTagContent();
const beginParagraph = new Paragraph({});
const beginRun = new Run({});
beginRun.addChildElement(new Begin(true));
beginRun.addChildElement(new FieldInstruction(properties));
beginRun.addChildElement(new Separate());
beginParagraph.addRun(beginRun);
const beginParagraph = new Paragraph({
children: [
new Run({
children: [new Begin(true), new FieldInstruction(properties), new Separate()],
}),
],
});
content.addChildElement(beginParagraph);
const endParagraph = new Paragraph({});
const endRun = new Run({});
endRun.addChildElement(new End());
endParagraph.addRun(endRun);
const endParagraph = new Paragraph({
children: [
new Run({
children: [new End()],
}),
],
});
content.addChildElement(endParagraph);
this.root.push(content);