### MathSubScript Example
Source: https://docx.js.org/api/classes/MathSubScript.html
Example of how to create a MathSubScript instance for 'x' with subscript '1'.
```APIDOC
## Example
```javascript
// x with subscript 1
new MathSubScript({
children: [new MathRun("x")],
subScript: [new MathRun("1")],
});
```
```
--------------------------------
### Document Creation Example
Source: https://docx.js.org/api/modules.html
This example demonstrates how to create a simple Word document with a paragraph and text, then export it to a buffer.
```APIDOC
## Document Creation and Export
### Description
This example shows how to instantiate the `Document` class, add content like paragraphs and text runs, and then export the document to a buffer using the `Packer` class.
### Usage
```javascript
import { Document, Paragraph, TextRun, Packer } from "docx";
// Create a document instance
const doc = new Document({
sections: [{
children: [
new Paragraph({
children: [
new TextRun({ text: "Hello World", bold: true }),
],
}),
],
}],
});
// Export the document to a buffer
const buffer = await Packer.toBuffer(doc);
```
### Classes Used
- `Document`: The main class for creating a Word document.
- `Paragraph`: Represents a paragraph in the document.
- `TextRun`: Represents a run of text with specific formatting.
- `Packer`: Utility class for exporting the document.
```
--------------------------------
### OnOffElement Example Usage
Source: https://docx.js.org/api/classes/OnOffElement.html
Examples demonstrating how to create OnOffElement instances for enabling or explicitly disabling a property.
```APIDOC
## Example Usage
### Bold enabled (w:val omitted when true)
```javascript
new OnOffElement("w:b", true);
// Generates:
```
### Bold explicitly disabled
```javascript
new OnOffElement("w:b", false);
// Generates:
```
```
--------------------------------
### MathSum Example
Source: https://docx.js.org/api/classes/MathSum.html
Example of how to create a MathSum instance to represent 'Sum from i=1 to n of x'.
```APIDOC
## Example
```
// Sum from i=1 to n
new MathSum({
children: [new MathRun("x")],
subScript: [new MathRun("i=1")],
superScript: [new MathRun("n")],
});
```
```
--------------------------------
### MathRadical Examples
Source: https://docx.js.org/api/classes/MathRadical.html
Examples demonstrating how to create MathRadical instances for square roots and cube roots.
```APIDOC
## Example
```
// Square root of x
new MathRadical({ children: [new MathRun("x")] });
// Cube root of x
new MathRadical({
children: [new MathRun("x")],
degree: [new MathRun("3")],
});
```
```
--------------------------------
### Install docx Package
Source: https://docx.js.org/
Install the docx package using npm. This is the first step to using the library in your project.
```bash
npm install --save docx
```
--------------------------------
### Textbox Example Usage
Source: https://docx.js.org/api/classes/Textbox.html
Illustrates how to create and configure Textbox instances with different content and styling.
```APIDOC
#### Example
```
// Simple textbox with text
new Textbox({
children: [new TextRun("Hello World")],
style: {
width: "3in",
height: "1in"
}
});
// Positioned textbox with wrapping
new Textbox({
children: [
new TextRun({ text: "Floating Text", bold: true }),
new TextRun({ text: " in a textbox", break: 1 })
],
style: {
width: "2.5in",
height: "1.5in",
position: "absolute",
left: "1in",
top: "2in",
wrapStyle: "square"
}
});
```
```
--------------------------------
### MathLimitLower Example
Source: https://docx.js.org/api/classes/MathLimitLower.html
Example demonstrating how to create a MathLimitLower instance to represent 'lim' with 'x→0' underneath.
```APIDOC
## Example
```javascript
// lim with x→0 underneath
new MathLimitLower({
children: [new MathRun("lim")],
limit: [new MathRun("x→0")],
});
```
```
--------------------------------
### MathSubSuperScript Example
Source: https://docx.js.org/api/classes/MathSubSuperScript.html
Example of how to create a MathSubSuperScript instance to represent 'x' with subscript 'i' and superscript '2'.
```APIDOC
## Example
```javascript
// x with subscript i and superscript 2
new MathSubSuperScript({
children: [new MathRun("x")],
subScript: [new MathRun("i")],
superScript: [new MathRun("2")],
});
```
```
--------------------------------
### TextRun Examples
Source: https://docx.js.org/api/classes/TextRun.html
Illustrates how to create TextRun instances with simple text and with formatting options like bold.
```APIDOC
## Example Usage
### Simple text
```javascript
// Simple text
new TextRun("Hello World");
```
### Formatted text
```javascript
// Formatted text
new TextRun({ text: "Bold Text", bold: true });
```
```
--------------------------------
### EmptyElement Example
Source: https://docx.js.org/api/classes/EmptyElement.html
Example of how to create an EmptyElement and the resulting XML.
```APIDOC
## Example
```javascript
new EmptyElement("w:noProof");
// Generates:
```
```
--------------------------------
### PositionalTab Example
Source: https://docx.js.org/api/classes/PositionalTab.html
Example demonstrating how to create a PositionalTab with specific alignment, relative positioning, and leader.
```APIDOC
## Example
```
// Create a centered positional tab
new PositionalTab({
alignment: PositionalTabAlignment.CENTER,
relativeTo: PositionalTabRelativeTo.MARGIN,
leader: PositionalTabLeader.DOT,
});
```
```
--------------------------------
### Header Example
Source: https://docx.js.org/api/classes/Header.html
Example of creating a Header with a Paragraph containing text.
```APIDOC
## Example
```javascript
const header = new Header({
children: [
new Paragraph({ children: [new TextRun("Company Name")] }),
],
});
```
```
--------------------------------
### SymbolRun Example
Source: https://docx.js.org/api/classes/SymbolRun.html
Example of how to create a new SymbolRun instance with a character code and symbol font.
```APIDOC
## Example
```javascript
new SymbolRun({
char: "F04A",
symbolfont: "Wingdings",
});
```
```
--------------------------------
### Page Size Attributes Example
Source: https://docx.js.org/api/types/IPageSizeAttributes.html
This example shows how to set the width and height for pages in a document section using twips (twentieths of a point).
```xml
```
--------------------------------
### Page Size with Orientation Example
Source: https://docx.js.org/api/types/IPageSizeAttributes.html
This example demonstrates setting page dimensions and explicitly defining the orientation as landscape. Even though width is greater than height, landscape orientation ensures it's printed with the correct aspect ratio.
```xml
```
--------------------------------
### MathSuperScript Example
Source: https://docx.js.org/api/classes/MathSuperScript.html
Example of how to create a superscript expression for 'x squared'.
```APIDOC
## Example
```
// x squared
new MathSuperScript({
children: [new MathRun("x")],
superScript: [new MathRun("2")],
});
```
```
--------------------------------
### MathIntegral Example
Source: https://docx.js.org/api/classes/MathIntegral.html
Demonstrates how to create a definite integral from 0 to 1 with the function f(x) dx.
```APIDOC
// Definite integral from 0 to 1
new MathIntegral({
children: [new MathRun("f(x) dx")],
subScript: [new MathRun("0")],
superScript: [new MathRun("1")],
});
```
--------------------------------
### ParagraphProperties Examples
Source: https://docx.js.org/api/classes/ParagraphProperties.html
Illustrates various ways to instantiate and configure ParagraphProperties with different formatting options.
```APIDOC
### Example Usage:
```javascript
// Basic paragraph with alignment
new ParagraphProperties({
alignment: AlignmentType.CENTER,
});
// Formatted paragraph with spacing and indentation
new ParagraphProperties({
alignment: AlignmentType.JUSTIFIED,
spacing: { before: 200, after: 200, line: 360 },
indent: { left: 720, right: 720 },
});
// Heading with outline level
new ParagraphProperties({
heading: HeadingLevel.HEADING_1,
outlineLevel: 0,
keepNext: true,
});
// Numbered list item
new ParagraphProperties({
numbering: {
reference: "my-numbering",
level: 0,
instance: 0,
},
});
// Paragraph with borders and shading
new ParagraphProperties({
border: {
top: { style: BorderStyle.SINGLE, size: 6, color: "000000" },
bottom: { style: BorderStyle.SINGLE, size: 6, color: "000000" },
},
shading: { fill: "EEEEEE" },
});
```
```
--------------------------------
### Example Usage
Source: https://docx.js.org/api/classes/StyleForParagraph.html
Demonstrates how to create a custom paragraph style using the StyleForParagraph class.
```APIDOC
#### Example
```typescript
// Create a custom heading style
new StyleForParagraph({
id: "CustomHeading",
name: "Custom Heading",
basedOn: "Normal",
paragraph: {
spacing: { before: 240, after: 120 },
alignment: AlignmentType.LEFT
},
run: {
size: 28,
bold: true,
color: "2E74B5"
}
});
```
```
--------------------------------
### NumberFormat Examples
Source: https://docx.js.org/api/variables/NumberFormat.html
Demonstrates the usage of different NumberFormat constants for various numeral and text representations.
```javascript
// Arabic numerals (1, 2, 3)
NumberFormat.DECIMAL;
```
```javascript
// Roman numerals (I, II, III)
NumberFormat.UPPER_ROMAN;
```
```javascript
// Letters (a, b, c)
NumberFormat.LOWER_LETTER;
```
--------------------------------
### Example Usage
Source: https://docx.js.org/api/classes/PageBorders.html
Demonstrates how to add page borders to all pages of a document section using the PageBorders class and related enums.
```APIDOC
#### Example
```javascript
// Add page borders to all pages
new PageBorders({
pageBorders: {
display: PageBorderDisplay.ALL_PAGES,
offsetFrom: PageBorderOffsetFrom.PAGE,
zOrder: PageBorderZOrder.FRONT
},
pageBorderTop: { style: BorderStyle.SINGLE, size: 24, color: "000000" },
pageBorderBottom: { style: BorderStyle.SINGLE, size: 24, color: "000000" }
});
```
```
--------------------------------
### start Property
Source: https://docx.js.org/api/types/ILineNumberAttributes.html
Sets the initial value for line numbering whenever it restarts, as determined by the `restart` attribute.
```APIDOC
### `Optional` `Readonly`start
start?: number
## Line Numbering Starting Value
Specifies the starting value used for the first line whenever the line numbering is restarted by use of the `restart` attribute.
### Example
```xml
```
The `start` attribute specifies that line numbers shall be counted starting from the number 3.
The possible values for this attribute are defined by the ST_DecimalNumber simple type (§2.18.16).
```
--------------------------------
### Generate a Basic Word Document
Source: https://docx.js.org/
Create a simple Word document with a "Hello World" text and bold text using the docx library. This example demonstrates basic document structure and text formatting. The generated document is saved as 'My Document.docx'.
```javascript
import * as fs from "fs";
import { Document, Packer, Paragraph, TextRun } from "docx";
const doc = new Document({
sections: [
{
children: [
new Paragraph({
children: [
new TextRun("Hello World"),
new TextRun({
text: " - Bold text",
bold: true,
}),
],
}),
],
},
],
});
Packer.toBuffer(doc).then((buffer) => {
fs.writeFileSync("My Document.docx", buffer);
});
```
--------------------------------
### IXmlableObject Structure Example
Source: https://docx.js.org/api/interfaces/IXmlableObject.html
Illustrates the typical structure of an object implementing IXmlableObject, showing how to define an XML element with attributes and child content.
```json
{
"w:elementName": {
_attr: { "w:attribute": "value" },
// child elements or text
}
}
```
--------------------------------
### Instantiate BookmarkStart
Source: https://docx.js.org/api/classes/BookmarkStart.html
Creates a new BookmarkStart element with a given name and link ID. This is used to define the start of a bookmarked section in the document.
```typescript
new BookmarkStart("myBookmark", 1);
```
--------------------------------
### Export Document to Various Formats (Node.js & Browser)
Source: https://docx.js.org/api/classes/Packer.html
Demonstrates exporting a document to a buffer in Node.js or a blob in the browser. Includes an example of prettifying the XML output.
```javascript
// Export to buffer (Node.js)
const buffer = await Packer.toBuffer(doc);
// Export to blob (browser)
const blob = await Packer.toBlob(doc);
// Export with prettified XML
const buffer = await Packer.toBuffer(doc, PrettifyType.WITH_2_BLANKS);
```
--------------------------------
### Patch Document with Custom Delimiters
Source: https://docx.js.org/api/functions/patchDocument.html
This example demonstrates how to use custom start and end delimiters for placeholders when patching a document. The 'templateBuffer' and 'patches' object should be defined.
```typescript
const buffer = await patchDocument({
outputType: "nodebuffer",
data: templateBuffer,
patches: { ... },
placeholderDelimiters: { start: "<<", end: ">>" },
});
```
--------------------------------
### Create Section Type - Docx
Source: https://docx.js.org/api/functions/createSectionType.html
Use this function to create different types of section breaks. For example, create a continuous section or a section that starts on the next odd page.
```typescript
// Create a continuous section (no page break)
createSectionType(SectionType.CONTINUOUS);
// Create a section that starts on next odd page
createSectionType(SectionType.ODD_PAGE);
```
--------------------------------
### Set Line Number Starting Value (start)
Source: https://docx.js.org/api/types/ILineNumberAttributes.html
Determines the starting value for line numbering when it is restarted. This attribute works in conjunction with the 'restart' attribute.
```xml
```
--------------------------------
### Bookmark Constructor
Source: https://docx.js.org/api/classes/Bookmark.html
Initializes a new Bookmark instance. You can provide an ID and content to be bookmarked.
```APIDOC
## constructor
* new Bookmark(options: IBookmarkOptions): Bookmark
### Parameters
* options: IBookmarkOptions
### Returns Bookmark
```
--------------------------------
### ThematicBreak Usage Example
Source: https://docx.js.org/api/classes/ThematicBreak.html
Example of how to use ThematicBreak within a Paragraph.
```APIDOC
## Example
```
new Paragraph({
thematicBreak: true,
children: [new TextRun("Paragraph with horizontal rule below")],
});
```
```
--------------------------------
### constructor
Source: https://docx.js.org/api/classes/WpgGroupRun.html
Initializes a new instance of the WpgGroupRun class.
```APIDOC
## constructor
* new WpgGroupRun(options: IWpgGroupOptions): WpgGroupRun
#### Parameters
* options: IWpgGroupOptions
#### Returns WpgGroupRun
```
--------------------------------
### BookmarkStart Constructor
Source: https://docx.js.org/api/classes/BookmarkStart.html
Initializes a new instance of the BookmarkStart class.
```APIDOC
## constructor
* new BookmarkStart(id: string, linkId: number): BookmarkStart
### Parameters
* id: string
* linkId: number
### Returns BookmarkStart
```
--------------------------------
### FootnoteReferenceRun Example
Source: https://docx.js.org/api/classes/FootnoteReferenceRun.html
Example of how to add a footnote reference to a paragraph using the FootnoteReferenceRun class.
```APIDOC
## Example
```javascript
// Add a footnote reference in a paragraph
new Paragraph({
children: [
new TextRun("This text has a footnote"),
new FootnoteReferenceRun(1),
],
});
```
```
--------------------------------
### Media Class Constructor
Source: https://docx.js.org/api/classes/Media.html
Initializes a new instance of the Media class to manage document media.
```APIDOC
## new Media()
### Description
Initializes a new instance of the Media class.
### Method
constructor
### Returns
Media - A new Media instance.
```
--------------------------------
### Create a Simple Document
Source: https://docx.js.org/api/classes/File.html
Instantiate a new Document with basic content for a single section.
```javascript
const doc = new Document({
sections: [{
children: [
new Paragraph("Hello World"),
],
}],
});
```
--------------------------------
### PageBreak Example
Source: https://docx.js.org/api/classes/PageBreak.html
Demonstrates how to use the PageBreak class within a Paragraph. This example shows creating a new paragraph with a page break as one of its children.
```APIDOC
## Example
```javascript
new Paragraph({
children: [new PageBreak()],
});
```
```
--------------------------------
### constructor
Source: https://docx.js.org/api/classes/RunProperties.html
Initializes a new instance of the RunProperties class.
```APIDOC
## constructor
* new RunProperties(options?: IRunPropertiesOptions): RunProperties
#### Parameters
* `Optional`options: IRunPropertiesOptions
#### Returns RunProperties
```
--------------------------------
### Create Page Number Type with Custom Start and Format
Source: https://docx.js.org/api/functions/createPageNumberType.html
Use this function to set a custom starting page number and a specific numbering format, such as lowercase Roman numerals, for a document section. Ensure the NumberFormat enum is imported.
```typescript
// Start page numbering at 5 with lowercase roman numerals
createPageNumberType({
start: 5,
formatType: NumberFormat.LOWER_ROMAN
});
```
--------------------------------
### BookmarkEnd Constructor
Source: https://docx.js.org/api/classes/BookmarkEnd.html
Initializes a new instance of the BookmarkEnd class.
```APIDOC
## new BookmarkEnd(linkId: number): BookmarkEnd
### Description
Initializes a new instance of the BookmarkEnd class.
### Parameters
* **linkId** (number) - The ID that links this bookmark end to its corresponding bookmark start.
### Returns
* BookmarkEnd - A new BookmarkEnd instance.
```
--------------------------------
### AbstractNumbering.id Property
Source: https://docx.js.org/api/classes/AbstractNumbering.html
Gets the unique identifier for this abstract numbering definition.
```APIDOC
## id
* id: number
### Description
The unique identifier for this abstract numbering definition.
```
--------------------------------
### Create XML Element with Attributes and Children
Source: https://docx.js.org/api/classes/BuilderElement.html
Instantiate BuilderElement with specific attributes and child elements. The first example shows how to define attributes like 'before' and 'after' for a 'w:spacing' element. The second example demonstrates creating a 'w:pPr' element with a 'w:pStyle' child element.
```typescript
// Element with attributes
new BuilderElement({
name: "w:spacing",
attributes: {
before: { key: "w:before", value: 240 },
after: { key: "w:after", value: 120 }
}
});
// Generates:
```
```typescript
// Element with children
new BuilderElement({
name: "w:pPr",
children: [
new StringValueElement("w:pStyle", "Heading1")
]
});
```
--------------------------------
### Bookmark Properties
Source: https://docx.js.org/api/classes/Bookmark.html
Provides access to the children, end marker, and start marker of the bookmark.
```APIDOC
## Properties
### `Readonly`children
children: readonly ParagraphChild[]
### `Readonly`end
end: BookmarkEnd
### `Readonly`start
start: BookmarkStart
```
--------------------------------
### constructor
Source: https://docx.js.org/api/classes/HpsMeasureElement.html
Creates an HpsMeasureElement.
```APIDOC
## constructor
* new HpsMeasureElement(
name: string,
val:
| number
| `${number}mm`
| `${number}cm`
| `${number}in`
| `${number}pt`
| `${number}pc`
| `${number}pi`,
): HpsMeasureElement
Creates an HpsMeasureElement.
### Parameters
* name: string
The XML element name
* val:
| number
| `${number}mm`
| `${number}cm`
| `${number}in`
| `${number}pt`
| `${number}pc`
| `${number}pi`
The measurement value (number in half-points or string with units)
### Returns HpsMeasureElement
#### Example
```
// Font size of 24 half-points (12pt)
new HpsMeasureElement("w:sz", 24);
// Generates:
// Using explicit units
new HpsMeasureElement("w:sz", "12pt");
```
```
--------------------------------
### CarriageReturn Constructor
Source: https://docx.js.org/api/classes/CarriageReturn.html
Initializes a new instance of the CarriageReturn class. No specific setup is required.
```typescript
new CarriageReturn(): CarriageReturn
```
--------------------------------
### prepForXml Method
Source: https://docx.js.org/api/classes/MathSubSuperScript.html
Prepares the MathSubSuperScript component and its children for XML serialization. This method is crucial for converting the component tree into an XML structure compatible with the 'xml' library.
```APIDOC
## prepForXml
* prepForXml(context: IContext): IXmlableObject | undefined
### Description
Prepares this component and its children for XML serialization. This method is called by the Formatter to convert the component tree into an object structure compatible with the xml library (https://www.npmjs.com/package/xml). It recursively processes all children and handles special cases like attribute-only elements and empty elements. The method can be overridden by subclasses to customize XML representation or execute side effects during serialization (e.g., creating relationships).
### Parameters
* **context**: IContext
The serialization context containing document state.
### Returns
IXmlableObject | undefined
The XML-serializable object, or undefined to exclude from output.
### Example
```javascript
// Override to add custom serialization logic
prepForXml(context: IContext): IXmlableObject | undefined {
// Custom logic here
return super.prepForXml(context);
}
```
```
--------------------------------
### prepForXml Method
Source: https://docx.js.org/api/classes/AnnotationReference.html
Prepares this component and its children for XML serialization.
```APIDOC
## prepForXml
### Description
Prepares this component and its children for XML serialization. This method is called by the Formatter to convert the component tree into an object structure compatible with the xml library. It recursively processes all children and handles special cases like attribute-only elements and empty elements. The method can be overridden by subclasses to customize XML representation or execute side effects during serialization (e.g., creating relationships).
### Signature
`prepForXml(context: IContext): IXmlableObject | undefined`
### Parameters
#### context
- `context` (IContext) - Required - The serialization context containing document state.
### Returns
- `IXmlableObject | undefined`: The XML-serializable object, or undefined to exclude from output.
### Example
```typescript
// Override to add custom serialization logic
prepForXml(context: IContext): IXmlableObject | undefined {
// Custom logic here
return super.prepForXml(context);
}
```
```
--------------------------------
### prepForXml Method
Source: https://docx.js.org/api/classes/Styles.html
Prepares the Styles component and its children for XML serialization. This method is crucial for converting the component tree into a format compatible with the 'xml' library.
```APIDOC
## prepForXml
* prepForXml(context: IContext): IXmlableObject | undefined
### Description
Prepares this component and its children for XML serialization. This method is called by the Formatter to convert the component tree into an object structure compatible with the xml library. It recursively processes all children and handles special cases like attribute-only elements and empty elements. The method can be overridden by subclasses to customize XML representation or execute side effects during serialization (e.g., creating relationships).
### Parameters
* context: IContext
The serialization context containing document state.
### Returns
IXmlableObject | undefined
The XML-serializable object, or undefined to exclude from output.
### Example
```
// Override to add custom serialization logic
prepForXml(context: IContext): IXmlableObject | undefined {
// Custom logic here
return super.prepForXml(context);
}
```
```
--------------------------------
### Create and Export a Word Document
Source: https://docx.js.org/api/modules.html
This snippet demonstrates how to create a simple Word document with a 'Hello World' text and export it to a buffer. It requires importing Document, Paragraph, TextRun, and Packer from the 'docx' library.
```typescript
import { Document, Paragraph, TextRun, Packer } from "docx";
// Create a document
const doc = new Document({
sections: [{
children: [
new Paragraph({
children: [
new TextRun({ text: "Hello World", bold: true }),
],
}),
],
}],
});
// Export to buffer
const buffer = await Packer.toBuffer(doc);
```
--------------------------------
### UniversalMeasure Type Examples
Source: https://docx.js.org/api/types/UniversalMeasure.html
Demonstrates the usage of the UniversalMeasure type with positive and negative values, including decimal points.
```typescript
const measure: UniversalMeasure = "10.5mm";
```
```typescript
const negative: UniversalMeasure = "-5pt";
```
--------------------------------
### SequentialIdentifier Usage Examples
Source: https://docx.js.org/api/classes/SequentialIdentifier.html
Demonstrates how to create SequentialIdentifier instances for different numbering purposes within a WordprocessingML document.
```APIDOC
## Example Usage
```javascript
// Create a figure number sequence
const figureIdentifier = new SequentialIdentifier("Figure");
// Create a table number sequence
const tableIdentifier = new SequentialIdentifier("Table");
// Create an equation number sequence
const equationIdentifier = new SequentialIdentifier("Equation");
```
```
--------------------------------
### docPropertiesUniqueNumericIdGen
Source: https://docx.js.org/api/functions/docPropertiesUniqueNumericIdGen.html
Creates a unique numeric ID generator for document properties. The generator produces sequential IDs starting from 1.
```APIDOC
## Function docPropertiesUniqueNumericIdGen
### Description
Creates a unique numeric ID generator for document properties.
### Returns
`UniqueNumericIdCreator`: A function that generates sequential IDs starting from 1.
### Example
```javascript
const idGen = docPropertiesUniqueNumericIdGen();
const id = idGen(); // Returns 1
```
```
--------------------------------
### Instantiate CommentRangeStart
Source: https://docx.js.org/api/classes/CommentRangeStart.html
Creates a new instance of CommentRangeStart with a specified ID. This ID links the start of the comment range to its end.
```typescript
new CommentRangeStart(0);
```
--------------------------------
### prepForXml Method
Source: https://docx.js.org/api/classes/StringContainer.html
Prepares this component and its children for XML serialization, converting them into a structure compatible with the 'xml' library.
```APIDOC
## prepForXml
### Description
Prepares this component and its children for XML serialization.
This method is called by the Formatter to convert the component tree into an object structure compatible with the xml library (https://www.npmjs.com/package/xml). It recursively processes all children and handles special cases like attribute-only elements and empty elements.
The method can be overridden by subclasses to customize XML representation or execute side effects during serialization (e.g., creating relationships).
### Signature
`prepForXml(context: IContext): IXmlableObject | undefined`
### Parameters
* **context** (IContext) - Required - The serialization context containing document state.
### Returns
* IXmlableObject | undefined - The XML-serializable object, or undefined to exclude from output.
### Example
```javascript
// Override to add custom serialization logic
prepForXml(context: IContext): IXmlableObject | undefined {
// Custom logic here
return super.prepForXml(context);
}
```
```
--------------------------------
### prepForXml Method
Source: https://docx.js.org/api/classes/TDirection.html
Prepares the component and its children for XML serialization, converting the component tree into an object structure compatible with the 'xml' library.
```APIDOC
## prepForXml
### Description
Prepares this component and its children for XML serialization.
### Parameters
#### Parameters
- **context** (IContext) - Required - The serialization context containing document state
### Returns
IXmlableObject | undefined - The XML-serializable object, or undefined to exclude from output
### Example
```javascript
// Override to add custom serialization logic
prepForXml(context: IContext): IXmlableObject | undefined {
// Custom logic here
return super.prepForXml(context);
}
```
```
--------------------------------
### Instantiate CommentRangeEnd
Source: https://docx.js.org/api/classes/CommentRangeEnd.html
Creates a new CommentRangeEnd object with a specified ID. This ID links the end of the comment range to its start.
```typescript
new CommentRangeEnd(0);
```
--------------------------------
### constructor
Source: https://docx.js.org/api/classes/MathFunctionProperties.html
Initializes a new instance of the MathFunctionProperties class.
```APIDOC
## constructor
* new MathFunctionProperties(): MathFunctionProperties
#### Returns MathFunctionProperties
```
--------------------------------
### OutputType Usage Example
Source: https://docx.js.org/api/types/OutputType.html
Demonstrates how to use the OutputType type alias to specify the desired output format when generating a document.
```APIDOC
## Type Alias OutputType
OutputType: keyof OutputByType
Valid output type identifiers. Use these string literals to specify the desired output format when generating documents.
### Example
```typescript
const outputType: OutputType = "base64";
const doc = await packer.generate(document, { type: outputType });
```
```
--------------------------------
### prepForXml Method
Source: https://docx.js.org/api/classes/MathRadical.html
Prepares the MathRadical component and its children for XML serialization. This method is crucial for converting the component tree into an XML-compatible object structure.
```APIDOC
## prepForXml
* prepForXml(context: IContext): IXmlableObject | undefined
Prepares this component and its children for XML serialization.
This method is called by the Formatter to convert the component tree into an object structure compatible with the xml library (https://www.npmjs.com/package/xml). It recursively processes all children and handles special cases like attribute-only elements and empty elements.
The method can be overridden by subclasses to customize XML representation or execute side effects during serialization (e.g., creating relationships).
#### Parameters
* context: IContext
The serialization context containing document state
#### Returns IXmlableObject | undefined
The XML-serializable object, or undefined to exclude from output
#### Example
```
// Override to add custom serialization logic
prepForXml(context: IContext): IXmlableObject | undefined {
// Custom logic here
return super.prepForXml(context);
}
```
```
--------------------------------
### prepForXml Method
Source: https://docx.js.org/api/classes/MathDenominator.html
Prepares the MathDenominator component and its children for XML serialization. This method is crucial for converting the component tree into a format compatible with the 'xml' npm package.
```APIDOC
## prepForXml
* prepForXml(context: IContext): IXmlableObject | undefined
### Description
Prepares this component and its children for XML serialization.
This method is called by the Formatter to convert the component tree into an object structure compatible with the xml library (https://www.npmjs.com/package/xml). It recursively processes all children and handles special cases like attribute-only elements and empty elements.
The method can be overridden by subclasses to customize XML representation or execute side effects during serialization (e.g., creating relationships).
### Parameters
* context: IContext
The serialization context containing document state
### Returns IXmlableObject | undefined
The XML-serializable object, or undefined to exclude from output
### Example
```typescript
// Override to add custom serialization logic
prepForXml(context: IContext): IXmlableObject | undefined {
// Custom logic here
return super.prepForXml(context);
}
```
```
--------------------------------
### IPageNumberTypeAttributes Type Alias
Source: https://docx.js.org/api/types/IPageNumberTypeAttributes.html
Defines the structure for page numbering configurations, including format type, separator, and starting page number.
```APIDOC
## Type Alias IPageNumberTypeAttributes
Options for configuring page numbering.
type IPageNumberTypeAttributes = {
formatType?: typeof NumberFormat[keyof typeof NumberFormat];
separator?: typeof PageNumberSeparator[keyof typeof PageNumberSeparator];
start?: number;
}
### Properties
#### `Optional` `Readonly` formatType
`formatType?: typeof NumberFormat[keyof typeof NumberFormat]`
Number format (decimal, roman, letter, etc.)
#### `Optional` `Readonly` separator
`separator?: typeof PageNumberSeparator[keyof typeof PageNumberSeparator]`
Separator between chapter and page number
#### `Optional` `Readonly` start
`start?: number`
Starting page number for the section
```
--------------------------------
### restart Property
Source: https://docx.js.org/api/types/ILineNumberAttributes.html
Determines when line numbering should reset. It specifies the point at which line numbering restarts to the value defined by the `start` attribute.
```APIDOC
### `Optional` `Readonly`restart
restart?: typeof LineNumberRestartFormat[keyof typeof LineNumberRestartFormat]
## Line Numbering Restart Setting
Specifies when the line numbering in this section shall be reset to the line number specified by the `start` attribute's value.
The line numbering increments for each line (even if it is not displayed) until it reaches the restart point specified by this element.
### Example
```xml
...
```
The value of `newPage` specifies that the line numbers shall restart at the top of each page to the value specified by the `start` attribute. In this case, `newPage` is the default, so this value could have been omitted entirely.
The possible values for this attribute are defined by the ST_LineNumberRestart simple type (§2.18.54).
```
--------------------------------
### prepForXml Method
Source: https://docx.js.org/api/classes/Border.html
Prepares the component for XML serialization, excluding it if empty.
```APIDOC
## prepForXml
* prepForXml(context: IContext): IXmlableObject | undefined
Prepares the component for XML serialization, excluding it if empty.
### Parameters
* context: IContext
The serialization context
### Returns IXmlableObject | undefined
The XML-serializable object, or undefined if empty
```
--------------------------------
### VerticalMergeRevisionType Constants
Source: https://docx.js.org/api/variables/VerticalMergeRevisionType.html
Defines the types for vertical merge revisions, indicating whether a cell continues a vertical merge or starts a new one.
```APIDOC
## VerticalMergeRevisionType
Vertical merge revision types.
### Type Declaration
* ##### `Readonly` CONTINUE: "cont"
Cell that is merged with upper one.
* ##### `Readonly` RESTART: "rest"
Cell that is starting the vertical merge.
```
--------------------------------
### prepForXml Method
Source: https://docx.js.org/api/classes/SequentialIdentifier.html
Prepares this component and its children for XML serialization. This method is crucial for converting the component tree into a format compatible with the 'xml' library, handling custom serialization logic and relationships.
```APIDOC
## prepForXml
* prepForXml(context: IContext): IXmlableObject | undefined
### Description
Prepares this component and its children for XML serialization. This method is called by the Formatter to convert the component tree into an object structure compatible with the xml library (https://www.npmjs.com/package/xml). It recursively processes all children and handles special cases like attribute-only elements and empty elements.
The method can be overridden by subclasses to customize XML representation or execute side effects during serialization (e.g., creating relationships).
### Parameters
* context: IContext - The serialization context containing document state.
### Returns
IXmlableObject | undefined - The XML-serializable object, or undefined to exclude from output.
### Example
```javascript
// Override to add custom serialization logic
prepForXml(context: IContext): IXmlableObject | undefined {
// Custom logic here
return super.prepForXml(context);
}
```
```
--------------------------------
### Create and Link to a Bookmark - Docx
Source: https://docx.js.org/api/classes/InternalHyperlink.html
Demonstrates how to create a bookmark and then create an internal hyperlink that points to it. Ensure the bookmark ID matches the anchor name.
```typescript
// Create a bookmark
new Bookmark({
id: "section1",
children: [new TextRun("Section 1")],
});
// Link to the bookmark
new InternalHyperlink({
children: [new TextRun({ text: "Go to Section 1", style: "Hyperlink" })],
anchor: "section1",
});
```
--------------------------------
### Create a new LevelOverride
Source: https://docx.js.org/api/classes/LevelOverride.html
Instantiates a new LevelOverride object. Specify the level number to override (0-8) and an optional starting number for that level.
```typescript
new LevelOverride(levelNum: number, start?: number): LevelOverride
```
--------------------------------
### prepForXml Method
Source: https://docx.js.org/api/classes/MathLimitLower.html
Prepares the MathLimitLower component and its children for XML serialization. This method is crucial for converting the component tree into a format compatible with XML libraries.
```APIDOC
## prepForXml
* prepForXml(context: IContext): IXmlableObject | undefined
Prepares this component and its children for XML serialization.
This method is called by the Formatter to convert the component tree into an object structure compatible with the xml library (https://www.npmjs.com/package/xml). It recursively processes all children and handles special cases like attribute-only elements and empty elements.
The method can be overridden by subclasses to customize XML representation or execute side effects during serialization (e.g., creating relationships).
#### Parameters
* context: IContext
The serialization context containing document state
#### Returns IXmlableObject | undefined
The XML-serializable object, or undefined to exclude from output
#### Example
```javascript
// Override to add custom serialization logic
prepForXml(context: IContext): IXmlableObject | undefined {
// Custom logic here
return super.prepForXml(context);
}
```
```
--------------------------------
### prepForXml Method
Source: https://docx.js.org/api/classes/TextRun.html
Prepares the TextRun component and its children for XML serialization. This method can be overridden to customize the XML output or add custom serialization logic.
```APIDOC
## Methods
### prepForXml
* **prepForXml**(context: IContext): IXmlableObject | undefined
Prepares this component and its children for XML serialization.
This method is called by the Formatter to convert the component tree into an object structure compatible with the xml library. It recursively processes all children and handles special cases like attribute-only elements and empty elements.
The method can be overridden by subclasses to customize XML representation or execute side effects during serialization (e.g., creating relationships).
#### Parameters
* **context** (IContext) - The serialization context containing document state.
#### Returns
* IXmlableObject | undefined - The XML-serializable object, or undefined to exclude from output.
#### Example
```javascript
// Override to add custom serialization logic
prepForXml(context: IContext): IXmlableObject | undefined {
// Custom logic here
return super.prepForXml(context);
}
```
```
--------------------------------
### Override prepForXml Method
Source: https://docx.js.org/api/classes/CheckBox.html
Example of overriding the `prepForXml` method in a subclass to add custom serialization logic. This method is called during XML serialization.
```typescript
// Override to add custom serialization logic
prepForXml(context: IContext): IXmlableObject | undefined {
// Custom logic here
return super.prepForXml(context);
}
```
--------------------------------
### createPageNumberType
Source: https://docx.js.org/api/functions/createPageNumberType.html
Creates page numbering settings (pgNumType) for a document section. This element specifies the page numbering format and starting value for all pages in a section.
```APIDOC
## Function createPageNumberType
### Description
Creates page numbering settings (pgNumType) for a document section. This element specifies the page numbering format and starting value for all pages in a section.
### Parameters
#### __namedParameters: IPageNumberTypeAttributes
- **fmt** (ST_NumberFormat) - Optional - The format for page numbering. Defaults to 'decimal'.
- **start** (ST_DecimalNumber) - Optional - The starting number for page numbering.
- **chapStyle** (ST_DecimalNumber) - Optional - The style for chapter numbering.
- **chapSep** (ST_ChapterSep) - Optional - The separator for chapter numbering. Defaults to 'hyphen'.
### Returns
XmlComponent
### Example
```javascript
// Start page numbering at 5 with lowercase roman numerals
createPageNumberType({
start: 5,
formatType: NumberFormat.LOWER_ROMAN
});
```
```
--------------------------------
### constructor
Source: https://docx.js.org/api/classes/NoBreakHyphen.html
Initializes a new instance of the NoBreakHyphen class.
```APIDOC
## constructor
### Description
Initializes a new instance of the NoBreakHyphen class.
### Returns
- NoBreakHyphen: A new instance of the NoBreakHyphen class.
```
--------------------------------
### Textbox Constructor
Source: https://docx.js.org/api/classes/Textbox.html
Initializes a new Textbox instance. It accepts an options object for configuration.
```APIDOC
## constructor
* new Textbox(__namedParameters: ITextboxOptions): Textbox
#### Parameters
* __namedParameters: ITextboxOptions
#### Returns Textbox
```
--------------------------------
### VerticalMergeRevisionType Constants
Source: https://docx.js.org/api/variables/VerticalMergeRevisionType.html
Defines the types for vertical merging in tables. Use 'cont' to continue a merge with the upper cell, and 'rest' to start a new vertical merge.
```typescript
VerticalMergeRevisionType: { CONTINUE: "cont"; RESTART: "rest" } = ...
```
--------------------------------
### prepForXml(context: IContext)
Source: https://docx.js.org/api/classes/MathRadicalProperties.html
Prepares the MathRadicalProperties component and its children for XML serialization. This method is crucial for converting the component tree into a format compatible with the 'xml' library.
```APIDOC
## prepForXml
* prepForXml(context: IContext): IXmlableObject | undefined
### Description
Prepares this component and its children for XML serialization.
This method is called by the Formatter to convert the component tree into an object structure compatible with the xml library (https://www.npmjs.com/package/xml). It recursively processes all children and handles special cases like attribute-only elements and empty elements.
The method can be overridden by subclasses to customize XML representation or execute side effects during serialization (e.g., creating relationships).
### Parameters
* context: IContext - The serialization context containing document state
### Returns IXmlableObject | undefined - The XML-serializable object, or undefined to exclude from output
### Example
```typescript
// Override to add custom serialization logic
prepForXml(context: IContext): IXmlableObject | undefined {
// Custom logic here
return super.prepForXml(context);
}
```
```
--------------------------------
### prepForXml Method
Source: https://docx.js.org/api/classes/BaseXmlComponent.html
Prepares the component for XML serialization. Subclasses must implement this method.
```APIDOC
## prepForXml
### Description
Prepares this component for XML serialization. This method is called by the Formatter to convert the component into an object structure that can be serialized to XML. Subclasses must implement this to define their XML representation.
### Signature
`prepForXml(context: IContext): IXmlableObject | undefined`
### Parameters
* **context** (IContext) - The serialization context
### Returns
* **IXmlableObject | undefined** - The XML-serializable object, or undefined to exclude from output
```
--------------------------------
### Create a New Footer
Source: https://docx.js.org/api/classes/Footer.html
Instantiate a new Footer object with desired children elements. This example shows how to add text and the current page number to a footer.
```typescript
const footer = new Footer({
children: [
new Paragraph({ children: [new TextRun("Page "), PageNumber.CURRENT] }),
],
});
```
--------------------------------
### Create and Use a Unique Numeric ID Generator
Source: https://docx.js.org/api/functions/uniqueNumericIdCreator.html
Initialize the ID generator with an optional starting number. Each call to the returned function produces the next sequential number.
```javascript
const idGen = uniqueNumericIdCreator(10);
console.log(idGen()); // 11
console.log(idGen()); // 12
console.log(idGen()); // 13
```
--------------------------------
### Constructor
Source: https://docx.js.org/api/classes/ParagraphRunProperties.html
Initializes a new instance of the ParagraphRunProperties class.
```APIDOC
## new ParagraphRunProperties
### Description
Initializes a new instance of the ParagraphRunProperties class.
### Method Signature
`new ParagraphRunProperties(options?: IParagraphRunPropertiesOptions): ParagraphRunProperties`
### Parameters
* `options` (IParagraphRunPropertiesOptions) - Optional. Configuration options for the ParagraphRunProperties.
### Returns
ParagraphRunProperties - A new instance of ParagraphRunProperties.
```
--------------------------------
### Create Paragraph with Page Break Before
Source: https://docx.js.org/api/classes/PageBreakBefore.html
Instantiate a Paragraph with the `pageBreakBefore` option set to true to ensure it begins on a new page. This is useful for section starts or important content.
```javascript
new Paragraph({
pageBreakBefore: true,
children: [new TextRun("This text starts on a new page")],
});
```
--------------------------------
### MathLimit Constructor
Source: https://docx.js.org/api/classes/MathLimit.html
Initializes a new instance of the MathLimit class.
```APIDOC
## constructor
* new MathLimit(children: readonly MathComponent[]): MathLimit
#### Parameters
* children: readonly MathComponent[]
#### Returns MathLimit
```
--------------------------------
### Example linePitch Attribute Usage
Source: https://docx.js.org/api/types/IDocGridAttributesProperties.html
Demonstrates the 'linePitch' attribute within a document grid, defining the spacing for lines of text on a page. This value is specified in twentieths of a point.
```xml
```
--------------------------------
### prepForXml
Source: https://docx.js.org/api/classes/IgnoreIfEmptyXmlComponent.html
Prepares the component for XML serialization. If the component is empty and includeIfEmpty is false, it returns undefined, causing it to be excluded from the output.
```APIDOC
## prepForXml
* prepForXml(context: IContext): IXmlableObject | undefined
Prepares the component for XML serialization, excluding it if empty.
#### Parameters
* context: IContext
The serialization context
#### Returns IXmlableObject | undefined
The XML-serializable object, or undefined if empty
```
--------------------------------
### Using twipsMeasureValue with a Number
Source: https://docx.js.org/api/functions/twipsMeasureValue.html
Shows how to use twipsMeasureValue with a measurement value provided as a raw number, representing TWIPs. For example, 1440 TWIPs is equivalent to 1 inch.
```javascript
const width2 = twipsMeasureValue(1440); // 1 inch in TWIP
```
--------------------------------
### Constructor
Source: https://docx.js.org/api/classes/Paragraph.html
Initializes a new Paragraph instance. It can be created with a simple string or an options object for more complex configurations.
```APIDOC
## constructor
* new Paragraph(options: string | IParagraphOptions): Paragraph
### Parameters
* options: string | IParagraphOptions
### Returns Paragraph
```
--------------------------------
### Create Page Margins with 1 Inch Margins
Source: https://docx.js.org/api/functions/createPageMargin.html
This example demonstrates how to set all page margins to 1 inch. Note that 1440 twips is equivalent to 1 inch.
```typescript
// Create page margins with 1 inch margins (1440 twips = 1 inch)
createPageMargin(1440, 1440, 1440, 1440, 720, 720, 0);
```