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

Merge pull request #735 from dolanmiu/feat/convenience-functions

Browse Source 
Add Convenience functions
This commit is contained in:
Dolan
2020-12-24 03:44:54 +00:00
committed by GitHub
parent ef12ada5d7 502db14bba
commit 86f8259b33
15 changed files with 115 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
demo/11-declaritive-styles-2.ts
View File

@ -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) },
},
},
{

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

@ -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.",
}),
],
}),

4
demo/27-declaritive-styles-3.ts
View File

@ -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,

6
demo/29-numbered-lists.ts
View File

@ -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) },
},
},
},

8
demo/3-numbering-and-bullet-points.ts
View File

@ -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) },
},
},
},

39
demo/32-merge-and-shade-table-cells.ts
View File

@ -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: {

6
demo/57-add-parent-numbered-lists.ts
View File

@ -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,

3
docs/_sidebar.md
View File

@ -28,5 +28,8 @@
* Exporting
* [Packers](usage/packers.md)
* Utility
* [Convenience functions](usage/convenience-functions.md)
* [Contribution Guidelines](contribution-guidelines.md)

22
docs/usage/convenience-functions.md Normal file
View File

@ -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
```

18
src/convenience-functions.spec.ts Normal file
View File

@ -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);
});
});
});

8
src/convenience-functions.ts Normal file
View File

@ -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);
};

11
src/file/document/body/section-properties/section-properties.spec.ts
View File

@ -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),
},

9
src/file/document/body/section-properties/section-properties.ts
View File

@ -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,

19
src/file/numbering/numbering.ts
View File

@ -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) },
},
},
},

1
src/index.ts
View File

@ -4,3 +4,4 @@ export { File as Document } from "./file";
export * from "./file";
export * from "./export";
export * from "./import-dotx";
export * from "./convenience-functions";