From 502db14bba87291ed0dabd05c4300a296a1b369a Mon Sep 17 00:00:00 2001 From: Dolan Date: Thu, 24 Dec 2020 03:37:43 +0000 Subject: [PATCH] Add Convenience functions --- demo/11-declaritive-styles-2.ts | 3 +- demo/2-declaritive-styles.ts | 7 ++-- demo/27-declaritive-styles-3.ts | 4 +- demo/29-numbered-lists.ts | 6 +-- demo/3-numbering-and-bullet-points.ts | 8 ++-- demo/32-merge-and-shade-table-cells.ts | 39 ++++++++++++------- demo/57-add-parent-numbered-lists.ts | 6 +-- docs/_sidebar.md | 3 ++ docs/usage/convenience-functions.md | 22 +++++++++++ src/convenience-functions.spec.ts | 18 +++++++++ src/convenience-functions.ts | 8 ++++ .../section-properties.spec.ts | 11 +++--- .../section-properties/section-properties.ts | 9 +++-- src/file/numbering/numbering.ts | 19 ++++----- src/index.ts | 1 + 15 files changed, 115 insertions(+), 49 deletions(-) create mode 100644 docs/usage/convenience-functions.md create mode 100644 src/convenience-functions.spec.ts create mode 100644 src/convenience-functions.ts diff --git a/demo/11-declaritive-styles-2.ts b/demo/11-declaritive-styles-2.ts index 5fe9e16ae6..2f4ed78098 100644 --- a/demo/11-declaritive-styles-2.ts +++ b/demo/11-declaritive-styles-2.ts @@ -3,6 +3,7 @@ import * as fs from "fs"; import { AlignmentType, + convertInchesToTwip, Document, Footer, HeadingLevel, @@ -110,7 +111,7 @@ const doc = new Document({ }, paragraph: { spacing: { line: 276 }, - indent: { left: 720 }, + indent: { left: convertInchesToTwip(0.5) }, }, }, { diff --git a/demo/2-declaritive-styles.ts b/demo/2-declaritive-styles.ts index b96056166e..a7b7c4953b 100644 --- a/demo/2-declaritive-styles.ts +++ b/demo/2-declaritive-styles.ts @@ -1,7 +1,7 @@ // Example on how to customise the look at feel using Styles // Import from 'docx' rather than '../build' if you install from npm import * as fs from "fs"; -import { AlignmentType, Document, HeadingLevel, Packer, Paragraph, TextRun, UnderlineType } from "../build"; +import { AlignmentType, convertInchesToTwip, Document, HeadingLevel, Packer, Paragraph, TextRun, UnderlineType } from "../build"; const doc = new Document({ creator: "Clippy", @@ -56,7 +56,7 @@ const doc = new Document({ }, paragraph: { indent: { - left: 720, + left: convertInchesToTwip(0.5), }, spacing: { line: 276, @@ -168,8 +168,7 @@ doc.addSection({ text: "Strong Style", }), new TextRun({ - text: - " - Very strong.", + text: " - Very strong.", }), ], }), diff --git a/demo/27-declaritive-styles-3.ts b/demo/27-declaritive-styles-3.ts index 8419467799..8737c69101 100644 --- a/demo/27-declaritive-styles-3.ts +++ b/demo/27-declaritive-styles-3.ts @@ -1,7 +1,7 @@ // Custom styles using JavaScript configuration // Import from 'docx' rather than '../build' if you install from npm import * as fs from "fs"; -import { Document, HeadingLevel, Packer, Paragraph, UnderlineType } from "../build"; +import { Document, convertInchesToTwip, HeadingLevel, Packer, Paragraph, UnderlineType } from "../build"; const doc = new Document({ styles: { @@ -17,7 +17,7 @@ const doc = new Document({ }, paragraph: { indent: { - left: 720, + left: convertInchesToTwip(0.5), }, spacing: { line: 276, diff --git a/demo/29-numbered-lists.ts b/demo/29-numbered-lists.ts index 5cd3966015..5337db4438 100644 --- a/demo/29-numbered-lists.ts +++ b/demo/29-numbered-lists.ts @@ -1,7 +1,7 @@ // Numbered lists // Import from 'docx' rather than '../build' if you install from npm import * as fs from "fs"; -import { AlignmentType, Document, Packer, Paragraph } from "../build"; +import { AlignmentType, convertInchesToTwip, Document, Packer, Paragraph } from "../build"; const doc = new Document({ numbering: { @@ -15,7 +15,7 @@ const doc = new Document({ alignment: AlignmentType.START, style: { paragraph: { - indent: { left: 720, hanging: 260 }, + indent: { left: convertInchesToTwip(0.5), hanging: convertInchesToTwip(0.18) }, }, }, }, @@ -31,7 +31,7 @@ const doc = new Document({ alignment: AlignmentType.START, style: { paragraph: { - indent: { left: 720, hanging: 260 }, + indent: { left: convertInchesToTwip(0.5), hanging: convertInchesToTwip(0.18) }, }, }, }, diff --git a/demo/3-numbering-and-bullet-points.ts b/demo/3-numbering-and-bullet-points.ts index 58c0a4f5a6..6a4155452d 100644 --- a/demo/3-numbering-and-bullet-points.ts +++ b/demo/3-numbering-and-bullet-points.ts @@ -1,7 +1,7 @@ // Numbering and bullet points example // Import from 'docx' rather than '../build' if you install from npm import * as fs from "fs"; -import { AlignmentType, Document, Packer, Paragraph } from "../build"; +import { AlignmentType, convertInchesToTwip, Document, Packer, Paragraph } from "../build"; const doc = new Document({ numbering: { @@ -16,7 +16,7 @@ const doc = new Document({ alignment: AlignmentType.START, style: { paragraph: { - indent: { left: 720, hanging: 260 }, + indent: { left: convertInchesToTwip(0.5), hanging: convertInchesToTwip(0.18) }, }, }, }, @@ -27,7 +27,7 @@ const doc = new Document({ alignment: AlignmentType.START, style: { paragraph: { - indent: { left: 1440, hanging: 980 }, + indent: { left: convertInchesToTwip(1), hanging: convertInchesToTwip(0.68) }, }, }, }, @@ -38,7 +38,7 @@ const doc = new Document({ alignment: AlignmentType.START, style: { paragraph: { - indent: { left: 2160, hanging: 1700 }, + indent: { left: convertInchesToTwip(1.5), hanging: convertInchesToTwip(1.18) }, }, }, }, diff --git a/demo/32-merge-and-shade-table-cells.ts b/demo/32-merge-and-shade-table-cells.ts index f12350988e..284b456e05 100644 --- a/demo/32-merge-and-shade-table-cells.ts +++ b/demo/32-merge-and-shade-table-cells.ts @@ -2,7 +2,20 @@ // Also includes an example on how to center tables // Import from 'docx' rather than '../build' if you install from npm import * as fs from "fs"; -import { AlignmentType, BorderStyle, Document, HeadingLevel, Packer, Paragraph, ShadingType, Table, TableCell, TableRow, WidthType } from "../build"; +import { + AlignmentType, + BorderStyle, + convertInchesToTwip, + Document, + HeadingLevel, + Packer, + Paragraph, + ShadingType, + Table, + TableCell, + TableRow, + WidthType, +} from "../build"; const doc = new Document(); @@ -37,10 +50,10 @@ const table2 = new Table({ new TableCell({ children: [new Paragraph("World")], margins: { - top: 1000, - bottom: 1000, - left: 1000, - right: 1000, + top: convertInchesToTwip(0.69), + bottom: convertInchesToTwip(0.69), + left: convertInchesToTwip(0.69), + right: convertInchesToTwip(0.69), }, columnSpan: 3, }), @@ -64,7 +77,7 @@ const table2 = new Table({ size: 100, type: WidthType.AUTO, }, - columnWidths: [1000, 1000, 1000], + columnWidths: [convertInchesToTwip(0.69), convertInchesToTwip(0.69), convertInchesToTwip(0.69)], }); const table3 = new Table({ @@ -119,14 +132,14 @@ const table3 = new Table({ }), ], width: { - size: 7000, + size: convertInchesToTwip(4.86), type: WidthType.DXA, }, margins: { - top: 400, - bottom: 400, - right: 400, - left: 400, + top: convertInchesToTwip(0.27), + bottom: convertInchesToTwip(0.27), + right: convertInchesToTwip(0.27), + left: convertInchesToTwip(0.27), }, }); @@ -355,9 +368,7 @@ const table8 = new Table({ ], }), new TableRow({ - children: [ - new TableCell({ children: [new Paragraph("4,1")] }), - ], + children: [new TableCell({ children: [new Paragraph("4,1")] })], }), ], width: { diff --git a/demo/57-add-parent-numbered-lists.ts b/demo/57-add-parent-numbered-lists.ts index 1e12ebc75c..2cf31a9e6b 100644 --- a/demo/57-add-parent-numbered-lists.ts +++ b/demo/57-add-parent-numbered-lists.ts @@ -1,7 +1,7 @@ // Numbered lists - Add parent number in sub number // Import from 'docx' rather than '../build' if you install from npm import * as fs from "fs"; -import { AlignmentType, Document, HeadingLevel, Packer, Paragraph } from "../build"; +import { AlignmentType, convertInchesToTwip, Document, HeadingLevel, Packer, Paragraph } from "../build"; const doc = new Document({ numbering: { @@ -15,7 +15,7 @@ const doc = new Document({ alignment: AlignmentType.START, style: { paragraph: { - indent: { left: 720, hanging: 260 }, + indent: { left: convertInchesToTwip(0.5), hanging: 260 }, }, }, }, @@ -26,7 +26,7 @@ const doc = new Document({ alignment: AlignmentType.START, style: { paragraph: { - indent: { left: 1.25 * 720, hanging: 1.25 * 260 }, + indent: { left: 1.25 * convertInchesToTwip(0.5), hanging: 1.25 * 260 }, }, run: { bold: true, diff --git a/docs/_sidebar.md b/docs/_sidebar.md index bcdb03c55f..2538e975c7 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -28,5 +28,8 @@ * Exporting * [Packers](usage/packers.md) +* Utility + + * [Convenience functions](usage/convenience-functions.md) * [Contribution Guidelines](contribution-guidelines.md) diff --git a/docs/usage/convenience-functions.md b/docs/usage/convenience-functions.md new file mode 100644 index 0000000000..76236ca6c4 --- /dev/null +++ b/docs/usage/convenience-functions.md @@ -0,0 +1,22 @@ +# Convenience functions + +OOXML and this library mainly uses a unit called twentieths of a point or `twip` for short. a twip is a typographical measurement, defined as 1/20 of a typographical point. One twip is 1/1440 inch, or 17.64 μm. This unit is not intuitive for many users, so some functions were created to help + +More info here: https://en.wikipedia.org/wiki/Twip + +## Convert Inches to Twip + +```ts +import { convertInchesToTwip } from "docx"; + +const twip = convertInchesToTwip(1); // returns 1440 +const twip = convertInchesToTwip(0.5); // returns 720 +``` + +## Convert Millimeters to Twip + +```ts +import { convertMillimetersToTwip } from "docx"; + +const twip = convertMillimetersToTwip(50); // returns 2834 +``` diff --git a/src/convenience-functions.spec.ts b/src/convenience-functions.spec.ts new file mode 100644 index 0000000000..3333fdd2d0 --- /dev/null +++ b/src/convenience-functions.spec.ts @@ -0,0 +1,18 @@ +import { expect } from "chai"; +import { convertInchesToTwip, convertMillimetersToTwip } from "./convenience-functions"; + +describe("Utility", () => { + describe("#convertMillimetersToTwip", () => { + it("should call the underlying header's addChildElement for Paragraph", () => { + expect(convertMillimetersToTwip(1000)).to.equal(56692); + }); + }); + + describe("#convertInchesToTwip", () => { + it("should call the underlying header's addChildElement", () => { + expect(convertInchesToTwip(1)).to.equal(1440); + expect(convertInchesToTwip(0.5)).to.equal(720); + expect(convertInchesToTwip(0.25)).to.equal(360); + }); + }); +}); diff --git a/src/convenience-functions.ts b/src/convenience-functions.ts new file mode 100644 index 0000000000..6fe110b72b --- /dev/null +++ b/src/convenience-functions.ts @@ -0,0 +1,8 @@ +// Twip - twentieths of a point +export const convertMillimetersToTwip = (millimeters: number): number => { + return Math.floor((millimeters / 25.4) * 72 * 20); +}; + +export const convertInchesToTwip = (inches: number): number => { + return Math.floor(inches * 72 * 20); +}; diff --git a/src/file/document/body/section-properties/section-properties.spec.ts b/src/file/document/body/section-properties/section-properties.spec.ts index 70fc567b83..8a55699eb5 100644 --- a/src/file/document/body/section-properties/section-properties.spec.ts +++ b/src/file/document/body/section-properties/section-properties.spec.ts @@ -1,5 +1,6 @@ import { expect } from "chai"; +import { convertInchesToTwip } from "convenience-functions"; import { Formatter } from "export/formatter"; import { FooterWrapper } from "file/footer-wrapper"; import { HeaderWrapper } from "file/header-wrapper"; @@ -18,10 +19,10 @@ describe("SectionProperties", () => { const properties = new SectionProperties({ width: 11906, height: 16838, - top: 1440, - right: 1440, - bottom: 1440, - left: 1440, + top: convertInchesToTwip(1), + right: convertInchesToTwip(1), + bottom: convertInchesToTwip(1), + left: convertInchesToTwip(1), header: 708, footer: 708, gutter: 0, @@ -30,7 +31,7 @@ describe("SectionProperties", () => { space: 708, count: 1, }, - linePitch: 360, + linePitch: convertInchesToTwip(0.25), headers: { default: new HeaderWrapper(media, 100), }, diff --git a/src/file/document/body/section-properties/section-properties.ts b/src/file/document/body/section-properties/section-properties.ts index 37e09e4498..d497bb9131 100644 --- a/src/file/document/body/section-properties/section-properties.ts +++ b/src/file/document/body/section-properties/section-properties.ts @@ -1,4 +1,5 @@ // http://officeopenxml.com/WPsection.php +import { convertInchesToTwip } from "convenience-functions"; import { FooterWrapper } from "file/footer-wrapper"; import { HeaderWrapper } from "file/header-wrapper"; import { XmlComponent } from "file/xml-components"; @@ -64,10 +65,10 @@ export class SectionProperties extends XmlComponent { const { width = 11906, height = 16838, - top = 1440, - right = 1440, - bottom = 1440, - left = 1440, + top = convertInchesToTwip(1), + right = convertInchesToTwip(1), + bottom = convertInchesToTwip(1), + left = convertInchesToTwip(1), header = 708, footer = 708, gutter = 0, diff --git a/src/file/numbering/numbering.ts b/src/file/numbering/numbering.ts index a02caf6bef..99c5b4ea93 100644 --- a/src/file/numbering/numbering.ts +++ b/src/file/numbering/numbering.ts @@ -1,4 +1,5 @@ // http://officeopenxml.com/WPnumbering.php +import { convertInchesToTwip } from "convenience-functions"; import { AlignmentType } from "file/paragraph"; import { IXmlableObject, XmlComponent } from "file/xml-components"; @@ -55,7 +56,7 @@ export class Numbering extends XmlComponent { alignment: AlignmentType.LEFT, style: { paragraph: { - indent: { left: 720, hanging: 360 }, + indent: { left: convertInchesToTwip(0.5), hanging: convertInchesToTwip(0.25) }, }, }, }, @@ -66,7 +67,7 @@ export class Numbering extends XmlComponent { alignment: AlignmentType.LEFT, style: { paragraph: { - indent: { left: 1440, hanging: 360 }, + indent: { left: convertInchesToTwip(1), hanging: convertInchesToTwip(0.25) }, }, }, }, @@ -77,7 +78,7 @@ export class Numbering extends XmlComponent { alignment: AlignmentType.LEFT, style: { paragraph: { - indent: { left: 2160, hanging: 360 }, + indent: { left: 2160, hanging: convertInchesToTwip(0.25) }, }, }, }, @@ -88,7 +89,7 @@ export class Numbering extends XmlComponent { alignment: AlignmentType.LEFT, style: { paragraph: { - indent: { left: 2880, hanging: 360 }, + indent: { left: 2880, hanging: convertInchesToTwip(0.25) }, }, }, }, @@ -99,7 +100,7 @@ export class Numbering extends XmlComponent { alignment: AlignmentType.LEFT, style: { paragraph: { - indent: { left: 3600, hanging: 360 }, + indent: { left: 3600, hanging: convertInchesToTwip(0.25) }, }, }, }, @@ -110,7 +111,7 @@ export class Numbering extends XmlComponent { alignment: AlignmentType.LEFT, style: { paragraph: { - indent: { left: 4320, hanging: 360 }, + indent: { left: 4320, hanging: convertInchesToTwip(0.25) }, }, }, }, @@ -121,7 +122,7 @@ export class Numbering extends XmlComponent { alignment: AlignmentType.LEFT, style: { paragraph: { - indent: { left: 5040, hanging: 360 }, + indent: { left: 5040, hanging: convertInchesToTwip(0.25) }, }, }, }, @@ -132,7 +133,7 @@ export class Numbering extends XmlComponent { alignment: AlignmentType.LEFT, style: { paragraph: { - indent: { left: 5760, hanging: 360 }, + indent: { left: 5760, hanging: convertInchesToTwip(0.25) }, }, }, }, @@ -143,7 +144,7 @@ export class Numbering extends XmlComponent { alignment: AlignmentType.LEFT, style: { paragraph: { - indent: { left: 6480, hanging: 360 }, + indent: { left: 6480, hanging: convertInchesToTwip(0.25) }, }, }, }, diff --git a/src/index.ts b/src/index.ts index 1e35c87d30..a319e4dcfe 100644 --- a/src/index.ts +++ b/src/index.ts @@ -4,3 +4,4 @@ export { File as Document } from "./file"; export * from "./file"; export * from "./export"; export * from "./import-dotx"; +export * from "./convenience-functions";