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

Merge pull request #1120 from curvenote/feat/children-hyperlink

Browse Source 
ExternalHyperlink with multiple children
This commit is contained in:
Dolan
2021-09-01 04:37:45 +01:00
committed by GitHub
parent 366cd2b4b1 727e741b08
commit 90bb670de6
8 changed files with 179 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
demo/21-bookmarks.ts
View File

@ -18,10 +18,12 @@ const doc = new Document({
new Paragraph({ new Paragraph({
children: [ children: [
new InternalHyperlink({ new InternalHyperlink({
child: new TextRun({ children: [
text: "Click here!", new TextRun({
style: "Hyperlink", text: "Click here!",
}), style: "Hyperlink",
}),
],
anchor: "myAnchorId", anchor: "myAnchorId",
}), }),
], ],
@ -47,19 +49,23 @@ const doc = new Document({
new Paragraph({ new Paragraph({
children: [ children: [
new InternalHyperlink({ new InternalHyperlink({
child: new TextRun({ children: [
text: "Anchor Text", new TextRun({
style: "Hyperlink", text: "Styled",
}), bold: true,
style: "Hyperlink",
}),
new TextRun({
text: " Anchor Text",
style: "Hyperlink",
}),
],
anchor: "myAnchorId", anchor: "myAnchorId",
}), }),
], ],
}), }),
new Paragraph({ new Paragraph({
children: [ children: [new TextRun("The bookmark can be seen on page "), new PageRef("myAnchorId")],
new TextRun("The bookmark can be seen on page "),
new PageRef("myAnchorId"),
]
}), }),
], ],
}, },

101
demo/35-hyperlinks.ts
View File

@ -11,10 +11,12 @@ const doc = new Document({
children: [ children: [
new TextRun("Click here for the "), new TextRun("Click here for the "),
new ExternalHyperlink({ new ExternalHyperlink({
child: new TextRun({ children: [
text: "Footnotes external hyperlink", new TextRun({
style: "Hyperlink", text: "Footnotes external hyperlink",
}), style: "Hyperlink",
}),
],
link: "http://www.example.com", link: "http://www.example.com",
}), }),
], ],
@ -31,10 +33,12 @@ const doc = new Document({
children: [ children: [
new TextRun("Click here for the "), new TextRun("Click here for the "),
new ExternalHyperlink({ new ExternalHyperlink({
child: new TextRun({ children: [
text: "Footer external hyperlink", new TextRun({
style: "Hyperlink", text: "Footer external hyperlink",
}), style: "Hyperlink",
}),
],
link: "http://www.example.com", link: "http://www.example.com",
}), }),
], ],
@ -49,10 +53,12 @@ const doc = new Document({
children: [ children: [
new TextRun("Click here for the "), new TextRun("Click here for the "),
new ExternalHyperlink({ new ExternalHyperlink({
child: new TextRun({ children: [
text: "Header external hyperlink", new TextRun({
style: "Hyperlink", text: "Header external hyperlink",
}), style: "Hyperlink",
}),
],
link: "http://www.google.com", link: "http://www.google.com",
}), }),
], ],
@ -64,10 +70,12 @@ const doc = new Document({
new Paragraph({ new Paragraph({
children: [ children: [
new ExternalHyperlink({ new ExternalHyperlink({
child: new TextRun({ children: [
text: "Anchor Text", new TextRun({
style: "Hyperlink", text: "Anchor Text",
}), style: "Hyperlink",
}),
],
link: "http://www.example.com", link: "http://www.example.com",
}), }),
new FootnoteReferenceRun(1), new FootnoteReferenceRun(1),
@ -76,24 +84,63 @@ const doc = new Document({
new Paragraph({ new Paragraph({
children: [ children: [
new ExternalHyperlink({ new ExternalHyperlink({
child: new ImageRun({ children: [
data: fs.readFileSync("./demo/images/image1.jpeg"), new ImageRun({
transformation: { data: fs.readFileSync("./demo/images/image1.jpeg"),
width: 100, transformation: {
height: 100, width: 100,
}, height: 100,
}), },
}),
],
link: "http://www.google.com", link: "http://www.google.com",
}), }),
new ExternalHyperlink({ new ExternalHyperlink({
child: new TextRun({ children: [
text: "BBC News Link", new TextRun({
style: "Hyperlink", text: "BBC News Link",
}), style: "Hyperlink",
}),
],
link: "https://www.bbc.co.uk/news", link: "https://www.bbc.co.uk/news",
}), }),
], ],
}), }),
new Paragraph({
children: [
new TextRun({
text: "This is a hyperlink with formatting: ",
}),
new ExternalHyperlink({
children: [
new TextRun({
text: "A ",
style: "Hyperlink",
}),
new TextRun({
text: "single ",
bold: true,
style: "Hyperlink",
}),
new TextRun({
text: "link",
doubleStrike: true,
style: "Hyperlink",
}),
new TextRun({
text: "1",
superScript: true,
style: "Hyperlink",
}),
new TextRun({
text: "!",
style: "Hyperlink",
}),
],
link: "http://www.example.com",
}),
],
}),
], ],
}, },
], ],

1
docs/_sidebar.md
View File

@ -15,6 +15,7 @@
* [Image](usage/images.md) * [Image](usage/images.md)
* [Headers & Footers](usage/headers-and-footers.md) * [Headers & Footers](usage/headers-and-footers.md)
* [Bullet Points](usage/bullet-points.md) * [Bullet Points](usage/bullet-points.md)
* [Hyperlinks](usage/hyperlinks.md)
* [Numbering](usage/numbering.md) * [Numbering](usage/numbering.md)
* [Tables](usage/tables.md) * [Tables](usage/tables.md)
* [Tab Stops](usage/tab-stops.md) * [Tab Stops](usage/tab-stops.md)

86
docs/usage/hyperlinks.md
View File

@ -1,58 +1,98 @@
# Hyperlinks # Hyperlinks
!> Hyperlinks require an understanding of [Paragraphs](usage/paragraph.md) and [Text](usage/text.md).
There are two types of hyperlinks: internal (pointing to a bookmark inside the document) and external (pointing to an external url). There are two types of hyperlinks: internal (pointing to a bookmark inside the document) and external (pointing to an external url).
## Internal ## Internal
To create an internal hyperlink you need first to create a bookmark (the paragraph that will be the destination of the hyperlink) with `doc.createBookmark(anchor, text)`. To create an internal hyperlink you need first to create a `Bookmark`, which contains the content that will be the destination of the hyperlink.
A bookmark is composed of an anchor (an identifier) and the text displayed. After creating a bookmark just add it to a paragraph with `paragraph.addBookmark(bookmark)` A bookmark is composed of an anchor (an identifier) and the text displayed. After creating a bookmark just add it to a paragraph. For example, creating a bookmarked heading:
For example:
```ts ```ts
const paragraph = this.doc.createParagraph(); const chapter1 = new Paragraph({
const bookmark = this.doc.createBookmark('anchorForChapter1', 'This is chapter1'); heading: HeadingLevel.HEADING_1,
paragraph.addBookmark(bookmark); children: [
new Bookmark({
id: "anchorForChapter1",
children: [
new TextRun("Chapter 1"),
],
}),
],
})
``` ```
Then you can create an hyperlink pointing to that bookmark with `doc.createInternalHyperLink(anchor,text)`: Then you can create an hyperlink pointing to that bookmark with an `InternalHyperLink`:
```ts ```ts
const paragraph = this.doc.createParagraph(); const link = new InternalHyperlink({
const link = this.doc.createInternalHyperLink('anchorForChapter1', 'This is a link to chapter1'); children: [
paragraph.addHyperLink(link); new TextRun({
text: "See Chapter 1",
style: "Hyperlink",
}),
],
anchor: "anchorForChapter1",
})
``` ```
You can also get the page number of the bookmark by creating a page reference to it: You can also get the page number of the bookmark by creating a page reference to it:
```ts ```ts
new Paragraph({ const paragraph = new Paragraph({
children: [ children: [
new TextRun("The chapter1 can be seen on page "), new TextRun("Chapter 1 can be seen on page "),
new PageRef("anchorForChapter1"), new PageRef("anchorForChapter1"),
] ],
}) });
``` ```
## External ## External
To create an external hyperlink you just need to specify the url and the text of the link, then add it to a paragraph with `doc.createHyperlink(url, text)`: To create an external hyperlink you just need to specify the url and the text of the link, then add it to a paragraph:
```ts ```ts
const paragraph = this.doc.createParagraph(); const paragraph = new Paragraph({
const link = this.doc.createHyperlink('https://docx.js.org', 'This is an external link'); children: [
paragraph.addHyperLink(link); new ExternalHyperlink({
children: [
new TextRun({
text: "This is an external link!",
style: "Hyperlink",
}),
],
link: "https://docx.js.org",
}),
],
});
``` ```
## Styling an hyperlink ## Styling hyperlinks
It is possible to set the style of the text of an hyperlink. This can be done applying run formatting on `TextRun` property of the hyperlink. It is possible to set the style of the text of both internal and external hyperlinks. This can be done applying run formatting on any of the `TextRun` children of the hyperlink. Use the `style: "Hyperlink"` property to show the default link styles, which can be combined with any other style.
Example: Example:
```ts ```ts
const link = this.doc.createHyperlink('https://docx.js.org', 'This is an external link'); const styledLink = new ExternalHyperlink({
link.TextRun.bold().italics() children: [
new TextRun({
text: "This is a ",
style: "Hyperlink",
}),
new TextRun({
text: "bold",
bold: true,
style: "Hyperlink",
}),
new TextRun({
text: " link!",
style: "Hyperlink",
}),
],
link: "https://docx.js.org",
});
``` ```

24
src/file/paragraph/links/hyperlink.spec.ts
View File

@ -10,10 +10,12 @@ describe("ConcreteHyperlink", () => {
beforeEach(() => { beforeEach(() => {
hyperlink = new ConcreteHyperlink( hyperlink = new ConcreteHyperlink(
new TextRun({ [
text: "https://example.com", new TextRun({
style: "Hyperlink", text: "https://example.com",
}), style: "Hyperlink",
}),
],
"superid", "superid",
); );
}); });
@ -42,10 +44,12 @@ describe("ConcreteHyperlink", () => {
describe("with optional anchor parameter", () => { describe("with optional anchor parameter", () => {
beforeEach(() => { beforeEach(() => {
hyperlink = new ConcreteHyperlink( hyperlink = new ConcreteHyperlink(
new TextRun({ [
text: "Anchor Text", new TextRun({
style: "Hyperlink", text: "Anchor Text",
}), style: "Hyperlink",
}),
],
"superid2", "superid2",
"anchor", "anchor",
); );
@ -78,7 +82,7 @@ describe("ExternalHyperlink", () => {
describe("#constructor()", () => { describe("#constructor()", () => {
it("should create", () => { it("should create", () => {
const externalHyperlink = new ExternalHyperlink({ const externalHyperlink = new ExternalHyperlink({
child: new TextRun("test"), children: [new TextRun("test")],
link: "http://www.google.com", link: "http://www.google.com",
}); });
@ -91,7 +95,7 @@ describe("InternalHyperlink", () => {
describe("#constructor()", () => { describe("#constructor()", () => {
it("should create", () => { it("should create", () => {
const internalHyperlink = new InternalHyperlink({ const internalHyperlink = new InternalHyperlink({
child: new TextRun("test"), children: [new TextRun("test")],
anchor: "test-id", anchor: "test-id",
}); });

12
src/file/paragraph/links/hyperlink.ts
View File

@ -13,7 +13,7 @@ export enum HyperlinkType {
export class ConcreteHyperlink extends XmlComponent { export class ConcreteHyperlink extends XmlComponent {
public readonly linkId: string; public readonly linkId: string;
constructor(child: ParagraphChild, relationshipId: string, anchor?: string) { constructor(children: ParagraphChild[], relationshipId: string, anchor?: string) {
super("w:hyperlink"); super("w:hyperlink");
this.linkId = relationshipId; this.linkId = relationshipId;
@ -26,16 +26,18 @@ export class ConcreteHyperlink extends XmlComponent {
const attributes = new HyperlinkAttributes(props); const attributes = new HyperlinkAttributes(props);
this.root.push(attributes); this.root.push(attributes);
this.root.push(child); children.forEach((child) => {
this.root.push(child);
});
} }
} }
export class InternalHyperlink extends ConcreteHyperlink { export class InternalHyperlink extends ConcreteHyperlink {
constructor(options: { readonly child: ParagraphChild; readonly anchor: string }) { constructor(options: { readonly children: ParagraphChild[]; readonly anchor: string }) {
super(options.child, uniqueId(), options.anchor); super(options.children, uniqueId(), options.anchor);
} }
} }
export class ExternalHyperlink { export class ExternalHyperlink {
constructor(public readonly options: { readonly child: ParagraphChild; readonly link: string }) {} constructor(public readonly options: { readonly children: ParagraphChild[]; readonly link: string }) {}
} }

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

@ -927,7 +927,7 @@ describe("Paragraph", () => {
const paragraph = new Paragraph({ const paragraph = new Paragraph({
children: [ children: [
new ExternalHyperlink({ new ExternalHyperlink({
child: new TextRun("test"), children: [new TextRun("test")],
link: "http://www.google.com", link: "http://www.google.com",
}), }),
], ],

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

@ -75,7 +75,7 @@ export class Paragraph extends XmlComponent {
for (const element of this.root) { for (const element of this.root) {
if (element instanceof ExternalHyperlink) { if (element instanceof ExternalHyperlink) {
const index = this.root.indexOf(element); const index = this.root.indexOf(element);
const concreteHyperlink = new ConcreteHyperlink(element.options.child, uniqueId()); const concreteHyperlink = new ConcreteHyperlink(element.options.children, uniqueId());
context.viewWrapper.Relationships.createRelationship( context.viewWrapper.Relationships.createRelationship(
concreteHyperlink.linkId, concreteHyperlink.linkId,
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink", "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink",