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

Merge pull request #821 from dolanmiu/feat/text-frame

Browse Source 
#269 Text Frame (Text Box)
This commit is contained in:
Dolan
2021-03-14 18:17:44 +00:00
committed by GitHub
parent 2fa8df7cf4 cc32a7b2d3
commit 18ce200cdb
21 changed files with 444 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
.nycrc
View File

@ -1,9 +1,9 @@
{
"check-coverage": true,
"lines": 98.66,
"functions": 97.06,
"branches": 95.51,
"statements": 98.67,
"lines": 98.67,
"functions": 97.08,
"branches": 95.6,
"statements": 98.68,
"include": [
"src/**/*.ts"
],

71
demo/61-text-frame.ts Normal file
View File

@ -0,0 +1,71 @@
// Text Frame (Text Box) example
// Import from 'docx' rather than '../build' if you install from npm
import * as fs from "fs";
import { Document, FrameAnchorType, HorizontalPositionAlign, Packer, Paragraph, TextRun, VerticalPositionAlign } from "../build";
const doc = new Document();
doc.addSection({
properties: {},
children: [
new Paragraph({
frame: {
position: {
x: 1000,
y: 3000,
},
width: 4000,
height: 1000,
anchor: {
horizontal: FrameAnchorType.MARGIN,
vertical: FrameAnchorType.MARGIN,
},
alignment: {
x: HorizontalPositionAlign.CENTER,
y: VerticalPositionAlign.TOP,
},
},
border: {
top: {
color: "auto",
space: 1,
value: "single",
size: 6,
},
bottom: {
color: "auto",
space: 1,
value: "single",
size: 6,
},
left: {
color: "auto",
space: 1,
value: "single",
size: 6,
},
right: {
color: "auto",
space: 1,
value: "single",
size: 6,
},
},
children: [
new TextRun("Hello World"),
new TextRun({
text: "Foo Bar",
bold: true,
}),
new TextRun({
text: "\tGithub is the best",
bold: true,
}),
],
}),
],
});
Packer.toBuffer(doc).then((buffer) => {
fs.writeFileSync("My Document.docx", buffer);
});

4
docs/_coverpage.md
View File

@ -3,8 +3,8 @@
> Easily generate .docx files with JS/TS. Works for Node and on the Browser. :100:
- Simple, declarative API
- 50+ usage examples
- Battle tested, mature, 97%+ coverage
- 60+ usage examples
- Battle tested, mature, 98%+ coverage
[GitHub](https://github.com/dolanmiu/docx)
[Get Started](#Welcome)

1
docs/_sidebar.md
View File

@ -22,6 +22,7 @@
* [Page Numbers](usage/page-numbers.md)
* [Change Tracking](usage/change-tracking.md)
* [Math](usage/math.md)
* [Text Frames](usage/text-frames.md)
* Styling
* [Styling with JS](usage/styling-with-js.md)
* [Styling with XML](usage/styling-with-xml.md)

1
docs/usage/bullet-points.md
View File

@ -1,5 +1,6 @@
# Bullet Points
!> Bullet Points requires an understanding of [Paragraphs](usage/paragraph.md).
## Example
To make a bullet point, simply make a paragraph into a bullet point:

23
docs/usage/paragraph.md
View File

@ -32,7 +32,7 @@ const paragraph = new Paragraph({
});
```
After you create the paragraph, you must add the paragraph into the `document's section`. Learn more about `sections` here:
After you create the paragraph, you must add the paragraph into a `section`:
```ts
doc.addSection({
@ -74,9 +74,11 @@ This is the list of options for a paragraph. A detailed explanation is below:
| keepNext | `boolean` | Optional | |
| children | `(TextRun or PictureRun or Hyperlink)[]` | Optional | |
| style | `string` | Optional | |
| tabStop | `{ left?: ITabStopOptions; right?: ITabStopOptions; maxRight?: { leader: LeaderType; }; center?: ITabStopOptions }` | Optional | |
| bullet | `{ level: number }` | Optional | |
| numbering | `{ num: ConcreteNumbering; level: number; custom?: boolean }` | Optional | |
| [tabStop](usage/tab-stops) | `{ left?: ITabStopOptions; right?: ITabStopOptions; maxRight?: { leader: LeaderType; }; center?: ITabStopOptions }` | Optional | |
| [bullet](usage/bullet-points) | `{ level: number }` | Optional | |
| [numbering](usage/numbering) | `{ num: ConcreteNumbering; level: number; custom?: boolean }` | Optional | |
| [widowControl](#widow-control) | `boolean` | Optional | |
| [frame](usage/text-frames.md) | `IFrameOptions` | Optional | |
## Text
@ -157,6 +159,17 @@ const paragraph = new Paragraph({
});
```
## Widow Control
Allow First/Last Line to Display on a Separate Page
```ts
const paragraph = new Paragraph({
text: "shading",
widowControl: true,
});
```
## Spacing
Adding spacing between paragraphs
@ -195,7 +208,7 @@ const paragraph = new Paragraph({
## Styles
To create styles, please refer to the styling Wiki: https://github.com/dolanmiu/docx/wiki/Styling
To create styles, please refer to the [styling documentation](usage/styling-with-js)
![Word 2013 Styles menu](http://content.gcflearnfree.org/topics/233/style_apply_choose.png "Word 2013 Styles menu")

69
docs/usage/text-frames.md Normal file
View File

@ -0,0 +1,69 @@
# Text Frames
Also known as `Text Boxes`
!> Text Frames requires an understanding of [Paragraphs](usage/paragraph.md).
> Text frames are paragraphs of text in a document which are positioned in a separate region or frame in the document, and can be positioned with a specific size and position relative to non-frame paragraphs in the current document.
## Intro
To make a `Text Frame`, simply add the `frame` property on a paragraph. `Borders` can be applied to frame simply by adding the `border` attribute.
```ts
new Paragraph({
frame: {
position: {
x: 1000,
y: 3000,
},
width: 4000,
height: 1000,
anchor: {
horizontal: FrameAnchorType.MARGIN,
vertical: FrameAnchorType.MARGIN,
},
alignment: {
x: HorizontalPositionAlign.CENTER,
y: VerticalPositionAlign.TOP,
},
},
border: {
top: {
color: "auto",
space: 1,
value: "single",
size: 6,
},
bottom: {
color: "auto",
space: 1,
value: "single",
size: 6,
},
left: {
color: "auto",
space: 1,
value: "single",
size: 6,
},
right: {
color: "auto",
space: 1,
value: "single",
size: 6,
},
},
children: [
new TextRun("Hello World"),
new TextRun({
text: "Foo Bar",
bold: true,
}),
new TextRun({
text: "\tGithub is the best",
bold: true,
}),
],
});
```

2
src/file/drawing/floating/align.spec.ts
View File

@ -1,9 +1,9 @@
import { expect } from "chai";
import { Formatter } from "export/formatter";
import { VerticalPositionAlign } from "file/shared/alignment";
import { Align } from "./align";
import { VerticalPositionAlign } from "./floating-position";
describe("Align", () => {
describe("#constructor()", () => {

2
src/file/drawing/floating/align.ts
View File

@ -1,6 +1,6 @@
// http://officeopenxml.com/drwPicFloating-position.php
import { HorizontalPositionAlign, VerticalPositionAlign } from "file/shared/alignment";
import { XmlComponent } from "file/xml-components";
import { HorizontalPositionAlign, VerticalPositionAlign } from "./floating-position";
export class Align extends XmlComponent {
constructor(value: HorizontalPositionAlign | VerticalPositionAlign) {

18
src/file/drawing/floating/floating-position.ts
View File

@ -1,5 +1,7 @@
// http://officeopenxml.com/drwPicFloating-position.php
// http://officeopenxml.com/drwPicFloating.php
import { HorizontalPositionAlign, VerticalPositionAlign } from "file/shared/alignment";
import { ITextWrapping } from "../text-wrap";
export enum HorizontalPositionRelativeFrom {
@ -24,22 +26,6 @@ export enum VerticalPositionRelativeFrom {
TOP_MARGIN = "topMargin",
}
export enum HorizontalPositionAlign {
CENTER = "center",
INSIDE = "inside",
LEFT = "left",
OUTSIDE = "outside",
RIGHT = "right",
}
export enum VerticalPositionAlign {
BOTTOM = "bottom",
CENTER = "center",
INSIDE = "inside",
OUTSIDE = "outside",
TOP = "top",
}
export interface IHorizontalPositionOptions {
readonly relative?: HorizontalPositionRelativeFrom;
readonly align?: HorizontalPositionAlign;

3
src/file/drawing/floating/horizontal-position.spec.ts
View File

@ -1,8 +1,9 @@
import { expect } from "chai";
import { Formatter } from "export/formatter";
import { HorizontalPositionAlign } from "file/shared/alignment";
import { HorizontalPositionAlign, HorizontalPositionRelativeFrom } from "./floating-position";
import { HorizontalPositionRelativeFrom } from "./floating-position";
import { HorizontalPosition } from "./horizontal-position";
describe("HorizontalPosition", () => {

3
src/file/drawing/floating/vertical-position.spec.ts
View File

@ -1,8 +1,9 @@
import { expect } from "chai";
import { Formatter } from "export/formatter";
import { VerticalPositionAlign } from "file/shared/alignment";
import { VerticalPositionAlign, VerticalPositionRelativeFrom } from "./floating-position";
import { VerticalPositionRelativeFrom } from "./floating-position";
import { VerticalPosition } from "./vertical-position";
describe("VerticalPosition", () => {

1
src/file/index.ts
View File

@ -14,3 +14,4 @@ export * from "./footer-wrapper";
export * from "./header";
export * from "./footnotes";
export * from "./track-revision";
export * from "./shared";

86
src/file/paragraph/frame/frame-properties.spec.ts Normal file
View File

@ -0,0 +1,86 @@
import { expect } from "chai";
import { Formatter } from "export/formatter";
import { HorizontalPositionAlign, VerticalPositionAlign } from "file/shared";
import { FrameAnchorType, FrameProperties } from "./frame-properties";
describe("FrameProperties", () => {
describe("#constructor()", () => {
it("should create", () => {
const currentFrameProperties = new FrameProperties({
position: {
x: 1000,
y: 3000,
},
width: 4000,
height: 1000,
anchor: {
horizontal: FrameAnchorType.MARGIN,
vertical: FrameAnchorType.MARGIN,
},
alignment: {
x: HorizontalPositionAlign.CENTER,
y: VerticalPositionAlign.TOP,
},
});
const tree = new Formatter().format(currentFrameProperties);
expect(tree).to.deep.equal({
"w:framePr": {
_attr: {
"w:h": 1000,
"w:hAnchor": "margin",
"w:vAnchor": "margin",
"w:w": 4000,
"w:x": 1000,
"w:xAlign": "center",
"w:y": 3000,
"w:yAlign": "top",
},
},
});
});
it("should create with the space attribute", () => {
const currentFrameProperties = new FrameProperties({
position: {
x: 1000,
y: 3000,
},
width: 4000,
height: 1000,
anchor: {
horizontal: FrameAnchorType.MARGIN,
vertical: FrameAnchorType.MARGIN,
},
alignment: {
x: HorizontalPositionAlign.CENTER,
y: VerticalPositionAlign.TOP,
},
space: {
horizontal: 100,
vertical: 200,
},
});
const tree = new Formatter().format(currentFrameProperties);
expect(tree).to.deep.equal({
"w:framePr": {
_attr: {
"w:h": 1000,
"w:hAnchor": "margin",
"w:vAnchor": "margin",
"w:w": 4000,
"w:x": 1000,
"w:xAlign": "center",
"w:y": 3000,
"w:yAlign": "top",
"w:hSpace": 100,
"w:vSpace": 200,
},
},
});
});
});
});

111
src/file/paragraph/frame/frame-properties.ts Normal file
View File

@ -0,0 +1,111 @@
// http://officeopenxml.com/WPparagraph-textFrames.php
import { HorizontalPositionAlign, VerticalPositionAlign } from "file/shared/alignment";
import { XmlAttributeComponent, XmlComponent } from "file/xml-components";
export enum DropCapType {
NONE = "none",
DROP = "drop",
MARGIN = "margin",
}
export enum FrameAnchorType {
MARGIN = "margin",
PAGE = "page",
TEXT = "text",
}
export enum FrameWrap {
AROUND = "around",
AUTO = "auto",
NONE = "none",
NOT_BESIDE = "notBeside",
THROUGH = "through",
TIGHT = "tight",
}
export interface IFrameOptions {
readonly anchorLock?: boolean;
readonly dropCap?: DropCapType;
readonly width: number;
readonly height: number;
readonly position: {
readonly x: number;
readonly y: number;
};
readonly wrap?: FrameWrap;
readonly lines?: number;
readonly anchor: {
readonly horizontal: FrameAnchorType;
readonly vertical: FrameAnchorType;
};
readonly space?: {
readonly horizontal: number;
readonly vertical: number;
};
readonly rule?: number;
readonly alignment: {
readonly x: HorizontalPositionAlign;
readonly y: VerticalPositionAlign;
};
}
export class FramePropertiesAttributes extends XmlAttributeComponent<{
readonly anchorLock?: boolean;
readonly dropCap?: DropCapType;
readonly width: number;
readonly height: number;
readonly x: number;
readonly y: number;
readonly wrap?: FrameWrap;
readonly lines?: number;
readonly anchorHorizontal?: FrameAnchorType;
readonly anchorVertical?: FrameAnchorType;
readonly spaceHorizontal?: number;
readonly spaceVertical?: number;
readonly rule?: number;
readonly alignmentX?: HorizontalPositionAlign;
readonly alignmentY?: VerticalPositionAlign;
}> {
protected readonly xmlKeys = {
anchorLock: "w:anchorLock",
dropCap: "w:dropCap",
width: "w:w",
height: "w:h",
x: "w:x",
y: "w:y",
anchorHorizontal: "w:hAnchor",
anchorVertical: "w:vAnchor",
spaceHorizontal: "w:hSpace",
spaceVertical: "w:vSpace",
rule: "w:hRule",
alignmentX: "w:xAlign",
alignmentY: "w:yAlign",
lines: "w:lines",
wrap: "w:wrap",
};
}
export class FrameProperties extends XmlComponent {
constructor(options: IFrameOptions) {
super("w:framePr");
this.root.push(
new FramePropertiesAttributes({
anchorLock: options.anchorLock,
dropCap: options.dropCap,
width: options.width,
height: options.height,
x: options.position.x,
y: options.position.y,
anchorHorizontal: options.anchor.horizontal,
anchorVertical: options.anchor.vertical,
spaceHorizontal: options.space?.horizontal,
spaceVertical: options.space?.vertical,
rule: options.rule,
alignmentX: options.alignment.x,
alignmentY: options.alignment.y,
lines: options.lines,
wrap: options.wrap,
}),
);
}
}

1
src/file/paragraph/frame/index.ts Normal file
View File

@ -0,0 +1 @@
export * from "./frame-properties";

1
src/file/paragraph/index.ts
View File

@ -4,3 +4,4 @@ export * from "./properties";
export * from "./run";
export * from "./links";
export * from "./math";
export * from "./frame";

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

@ -7,8 +7,10 @@ import { EMPTY_OBJECT } from "file/xml-components";
import { IViewWrapper } from "../document-wrapper";
import { File } from "../file";
import { HorizontalPositionAlign, VerticalPositionAlign } from "../shared";
import { ShadingType } from "../table/shading";
import { AlignmentType, HeadingLevel, LeaderType, PageBreak, TabStopPosition, TabStopType } from "./formatting";
import { FrameAnchorType } from "./frame";
import { Bookmark, ExternalHyperlink } from "./links";
import { Paragraph } from "./paragraph";
import { TextRun } from "./run";
@ -859,6 +861,52 @@ describe("Paragraph", () => {
});
});
describe("#frame", () => {
it("should set frame attribute", () => {
const paragraph = new Paragraph({
frame: {
position: {
x: 1000,
y: 3000,
},
width: 4000,
height: 1000,
anchor: {
horizontal: FrameAnchorType.MARGIN,
vertical: FrameAnchorType.MARGIN,
},
alignment: {
x: HorizontalPositionAlign.CENTER,
y: VerticalPositionAlign.TOP,
},
},
});
const tree = new Formatter().format(paragraph);
expect(tree).to.deep.equal({
"w:p": [
{
"w:pPr": [
{
"w:framePr": {
_attr: {
"w:h": 1000,
"w:hAnchor": "margin",
"w:vAnchor": "margin",
"w:w": 4000,
"w:x": 1000,
"w:xAlign": "center",
"w:y": 3000,
"w:yAlign": "top",
},
},
},
],
},
],
});
});
});
describe("#prepForXml", () => {
it("should set Internal Hyperlink", () => {
const paragraph = new Paragraph({

6
src/file/paragraph/properties.ts
View File

@ -13,6 +13,7 @@ import { HeadingLevel, Style } from "./formatting/style";
import { LeaderType, TabStop, TabStopPosition, TabStopType } from "./formatting/tab-stop";
import { NumberProperties } from "./formatting/unordered-list";
import { WidowControl } from "./formatting/widow-control";
import { FrameProperties, IFrameOptions } from "./frame/frame-properties";
import { OutlineLevel } from "./links";
import { Shading } from "./run/formatting";
@ -55,6 +56,7 @@ export interface IParagraphPropertiesOptions extends IParagraphStylePropertiesOp
readonly color: string;
};
readonly widowControl?: boolean;
readonly frame?: IFrameOptions;
}
export class ParagraphProperties extends IgnoreIfEmptyXmlComponent {
@ -159,6 +161,10 @@ export class ParagraphProperties extends IgnoreIfEmptyXmlComponent {
if (options.widowControl) {
this.push(new WidowControl(options.widowControl));
}
if (options.frame) {
this.push(new FrameProperties(options.frame));
}
}
public push(item: XmlComponent): void {

15
src/file/shared/alignment.ts Normal file
View File

@ -0,0 +1,15 @@
export enum HorizontalPositionAlign {
CENTER = "center",
INSIDE = "inside",
LEFT = "left",
OUTSIDE = "outside",
RIGHT = "right",
}
export enum VerticalPositionAlign {
BOTTOM = "bottom",
CENTER = "center",
INSIDE = "inside",
OUTSIDE = "outside",
TOP = "top",
}

1
src/file/shared/index.ts Normal file
View File

@ -0,0 +1 @@
export * from "./alignment";