Appearance
zeropdf / PdfFlow
Class: PdfFlow
Defined in: src/document.ts:1300
A cursor-based layout helper for writing report-style content. It manages vertical flow, spacing, page breaks, headings, paragraphs, links, images, and tables.
Constructors
Constructor
ts
new PdfFlow(
page,
embeddedFonts,
state,
parent?,
overflowHandler?,
fontFamilies?,
textDefaults?): PdfFlow;Defined in: src/document.ts:1309
Creates a cursor-based flow writer for a page and optional parent structure node.
Parameters
| Parameter | Type | Default value | Description |
|---|---|---|---|
page | InternalPageModel | undefined | The internal page model to write into. |
embeddedFonts | ReadonlyMap<string, ParsedTrueTypeFont> | undefined | The embedded font registry used for text layout. |
state | FlowState | undefined | The mutable flow state to use. |
parent | InternalStructureNode | undefined | undefined | The parent structure element whose child order should change. |
overflowHandler | (() => PdfFlow) | undefined | undefined | - |
fontFamilies | ReadonlyMap<string, FontFamilyFaces> | ... | - |
textDefaults? | TextDefaults | undefined | - |
Returns
PdfFlow
Accessors
columnCount
Get Signature
ts
get columnCount(): number;Defined in: src/document.ts:1366
Gets the total number of flow columns.
Returns
number
The flow column count.
columnIndex
Get Signature
ts
get columnIndex(): number;Defined in: src/document.ts:1357
Gets the zero-based active column index.
Returns
number
The current flow column index.
cursorY
Get Signature
ts
get cursorY(): number;Defined in: src/document.ts:1339
Gets the current vertical cursor position.
Returns
number
The current cursor y-coordinate.
remainingHeight
Get Signature
ts
get remainingHeight(): number;Defined in: src/document.ts:1348
Gets the remaining writable height above the bottom margin.
Returns
number
The remaining writable height.
Methods
advanceColumn()
ts
advanceColumn(): boolean;Defined in: src/document.ts:1375
Advances the flow cursor to the top of the next column on the same page.
Returns
boolean
Whether a next column was available.
bmp()
ts
bmp(data, options?): this;Defined in: src/document.ts:1706
Adds a BMP image at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
data | BinaryData | The binary image or font data. |
options | FlowImageOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
checkBox()
ts
checkBox(name, options): this;Defined in: src/document.ts:2558
Adds a checkbox form field at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
name | string | The fully-qualified field name. |
options | FlowCheckBoxOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
choiceField()
ts
choiceField(name, options): this;Defined in: src/document.ts:2602
Adds a choice form field at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
name | string | The fully-qualified field name. |
options | FlowChoiceFieldOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
circle()
ts
circle(
cx?,
cy?,
radius?,
style?): this;Defined in: src/document.ts:2993
Adds a circle path at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
cx? | number | Center x-coordinate override. |
cy? | number | Center y-coordinate override. |
radius? | number | Radius override. |
style? | PathStyle | The drawing style for the circle. |
Returns
this
This flow helper for chaining.
ellipse()
ts
ellipse(
cx?,
cy?,
rx?,
ry?,
style?): this;Defined in: src/document.ts:3036
Adds an ellipse at the current flow cursor. Like circle but with independent horizontal (rx) and vertical (ry) radii; advances the cursor by the full height (2 × ry).
Parameters
| Parameter | Type | Description |
|---|---|---|
cx? | number | Center x override (defaults to the column center). |
cy? | number | Center y override (defaults to one ry below the cursor). |
rx? | number | Horizontal radius override. |
ry? | number | Vertical radius override. |
style? | PathStyle | The drawing style for the ellipse. |
Returns
this
This flow helper for chaining.
estimate()
ts
estimate(block): number;Defined in: src/document.ts:1456
Estimates the height a template block would consume.
Parameters
| Parameter | Type | Description |
|---|---|---|
block | TemplateBlock | The template block to estimate. |
Returns
number
The estimated height.
estimateTableRowHeights()
ts
estimateTableRowHeights(rows, options?): readonly number[];Defined in: src/document.ts:2105
Returns the rendered height of each row in a table at the current flow position. Heights include cell padding and the trailing rowGap. Use this to pre-plan row-by-row page splits when rendering large tables.
Parameters
| Parameter | Type | Description |
|---|---|---|
rows | readonly TableRow[] | The table rows to measure. |
options | FlowTableOptions | Options that control the operation. |
Returns
readonly number[]
Per-row heights including padding and trailing rowGap.
freeText()
ts
freeText(options): this;Defined in: src/document.ts:2892
Adds a free-text annotation at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
options | FlowFreeTextOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
gif()
ts
gif(data, options?): this;Defined in: src/document.ts:1766
Adds a GIF image at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
data | BinaryData | The binary image or font data. |
options | FlowImageOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
heading()
ts
heading(
text,
options?,
annotations?): this;Defined in: src/document.ts:1408
Adds a heading at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
text | string | The text to add. |
options | FlowHeadingOptions | Options that control the operation. |
annotations? | readonly ParagraphTextAnnotation[] | - |
Returns
this
This flow helper for chaining.
highlight()
ts
highlight(options): this;Defined in: src/document.ts:2773
Adds a highlight annotation at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
options | FlowHighlightOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
jbig2()
ts
jbig2(data, options?): this;Defined in: src/document.ts:1718
Adds a JBIG2 image at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
data | BinaryData | The binary image or font data. |
options | FlowImageOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
jp2()
ts
jp2(data, options?): this;Defined in: src/document.ts:1742
Adds a JPEG 2000 image at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
data | BinaryData | The binary image or font data. |
options | FlowImageOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
jpeg()
ts
jpeg(data, options?): this;Defined in: src/document.ts:1694
Adds a JPEG image at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
data | BinaryData | The binary image or font data. |
options | FlowImageOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
line()
ts
line(
x1,
y1,
x2,
y2,
style?): this;Defined in: src/document.ts:3069
Draws a straight line between two absolute points. Unlike rect and circle, a line does not consume vertical flow space.
Parameters
| Parameter | Type | Description |
|---|---|---|
x1 | number | Start x in PDF points. |
y1 | number | Start y in PDF points. |
x2 | number | End x in PDF points. |
y2 | number | End y in PDF points. |
style? | PathStyle | The drawing style for the line. |
Returns
this
This flow helper for chaining.
link()
ts
link(
text,
url,
options?): this;Defined in: src/document.ts:1792
Adds a text link at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
text | string | The text to add. |
url | string | The URI target. |
options | FlowLinkOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
list()
ts
list(items, options): this;Defined in: src/document.ts:3086
Adds a tagged list at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
items | readonly ListItem[] | The list items to add. |
options | FlowListOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
moveDown()
ts
moveDown(distance?): this;Defined in: src/document.ts:1940
Moves the flow cursor downward by the supplied distance.
Parameters
| Parameter | Type | Description |
|---|---|---|
distance | number | The distance to move the cursor. |
Returns
this
This flow helper for chaining.
note()
ts
note(options): this;Defined in: src/document.ts:2850
Adds a text note annotation at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
options | FlowNoteOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
paragraph()
ts
paragraph(
text,
options?,
annotations?): this;Defined in: src/document.ts:1544
Adds a paragraph at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
text | string | The text to add. |
options | FlowTextOptions | Options that control the operation. |
annotations? | readonly ParagraphTextAnnotation[] | - |
Returns
this
This flow helper for chaining.
path()
ts
path(
commands,
style,
height): this;Defined in: src/document.ts:2935
Adds vector path commands at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
commands | PathCommand[] | The vector path commands to add. |
style | PathStyle | The drawing style for the path. |
height | number | The vertical extent consumed by the path. |
Returns
this
This flow helper for chaining.
png()
ts
png(data, options?): this;Defined in: src/document.ts:1682
Adds a PNG image at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
data | BinaryData | The binary image or font data. |
options | FlowImageOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
pushButton()
ts
pushButton(name, options): this;Defined in: src/document.ts:2686
Adds a push-button form field at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
name | string | The fully-qualified field name. |
options | FlowPushButtonOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
radioGroup()
ts
radioGroup(name, options): this;Defined in: src/document.ts:2646
Adds a radio-button group at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
name | string | The fully-qualified field name. |
options | FlowRadioGroupOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
rect()
ts
rect(
x?,
y?,
width?,
height?,
style?): this;Defined in: src/document.ts:2958
Adds a rectangle path at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
x? | number | Horizontal position override. |
y? | number | Vertical position override (bottom edge). |
width? | number | Width override. |
height? | number | Height override. |
style? | PathStyle | The drawing style for the rectangle. |
Returns
this
This flow helper for chaining.
render()
ts
render(blocks, stylesheet?): this;Defined in: src/document.ts:1444
Renders a sequence of template blocks into the flow.
Parameters
| Parameter | Type | Description |
|---|---|---|
blocks | readonly TemplateBlock[] | The template blocks to render. |
stylesheet? | TemplateStylesheet | Optional named styles merged beneath each block's inline options. |
Returns
this
This flow helper for chaining.
reservePageLinkRect()
ts
reservePageLinkRect(options): object;Defined in: src/document.ts:1877
Reserves a rectangular region at the current flow cursor and returns its coordinates without emitting any content. Spacing is applied with the link defaults so this mirrors link layout. The cursor advances by the rect height plus trailing spacing.
Used by the template engine to defer page-to-page link emission until after every page exists.
Parameters
| Parameter | Type | Description |
|---|---|---|
options | Omit<PageLinkOptions, "x" | "y"> & FlowBlockSpacingOptions | Options that control the operation. |
Returns
object
The reserved rect in PDF coordinates.
height
ts
height: number;width
ts
width: number;x
ts
x: number;y
ts
y: number;richParagraph()
ts
richParagraph(runs, options?): this;Defined in: src/document.ts:1566
Adds a paragraph of inline rich-text runs at the current flow cursor. Runs flow on the same line and wrap together; each keeps its own style and may carry a link. Styles omitted on a run inherit from options, then the flow's configured defaults, then the document defaults.
Note: a rich paragraph is placed as a unit and does not split across columns or pages. For very long flowing copy that must break across columns, use paragraph.
Parameters
| Parameter | Type | Description |
|---|---|---|
runs | readonly InlineTextRun[] | The styled inline runs to lay out together. |
options | FlowRichTextOptions | Flow spacing and inherited style defaults. |
Returns
this
section()
ts
section(
blocks,
role?,
structure?,
stylesheet?): this;Defined in: src/document.ts:2483
Renders a section of template blocks within an optional structure container.
Parameters
| Parameter | Type | Description |
|---|---|---|
blocks | readonly TemplateBlock[] | Child blocks to render. |
role? | PdfContainerTag | Optional structure role (e.g. "Sect", "Div"). |
structure? | PdfStructureOptions | Optional structure options. |
stylesheet? | TemplateStylesheet | - |
Returns
this
This flow helper for chaining.
setOverflowHandler()
ts
setOverflowHandler(handler): this;Defined in: src/document.ts:1395
Registers a callback used by template rendering when flow content exhausts the last column and needs a fresh page.
Parameters
| Parameter | Type | Description |
|---|---|---|
handler | (() => PdfFlow) | undefined | Callback that returns the next flow region. |
Returns
this
This flow helper for chaining.
signatureField()
ts
signatureField(name, options): this;Defined in: src/document.ts:2730
Adds a signature form field placeholder at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
name | string | The fully-qualified field name. |
options | FlowSignatureFieldOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
squiggly()
ts
squiggly(options): this;Defined in: src/document.ts:2806
Adds a squiggly text-markup annotation at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
options | FlowHighlightOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
strikeOut()
ts
strikeOut(options): this;Defined in: src/document.ts:2795
Adds a strike-out text-markup annotation at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
options | FlowHighlightOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
svg()
ts
svg(data, options?): this;Defined in: src/document.ts:1778
Adds an SVG graphic at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
data | string | BinaryData | The SVG text data. |
options | FlowImageOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
table()
ts
table(rows, options?): this;Defined in: src/document.ts:1900
Adds a table at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
rows | readonly TableRow[] | The table rows to add. |
options | FlowTableOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
textBlock()
ts
textBlock(
text,
options?,
annotations?): this;Defined in: src/document.ts:1654
Adds a text block at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
text | string | The text to add. |
options | FlowTextOptions | Options that control the operation. |
annotations? | readonly ParagraphTextAnnotation[] | Optional inline annotations anchored to substrings of the rendered text. |
Returns
this
This flow helper for chaining.
textField()
ts
textField(name, options): this;Defined in: src/document.ts:2514
Adds a text form field at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
name | string | The fully-qualified field name. |
options | FlowTextFieldOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
tiff()
ts
tiff(data, options?): this;Defined in: src/document.ts:1730
Adds a TIFF image at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
data | BinaryData | The binary image or font data. |
options | FlowImageOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
underline()
ts
underline(options): this;Defined in: src/document.ts:2784
Adds an underline text-markup annotation at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
options | FlowHighlightOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.
webp()
ts
webp(data, options?): this;Defined in: src/document.ts:1754
Adds a WebP image at the current flow cursor.
Parameters
| Parameter | Type | Description |
|---|---|---|
data | BinaryData | The binary image or font data. |
options | FlowImageOptions | Options that control the operation. |
Returns
this
This flow helper for chaining.