Skip to main content

Class: PdfFlow

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​

new PdfFlow(
page,
embeddedFonts,
state,
parent?,
overflowHandler?,
fontFamilies?,
textDefaults?): PdfFlow;

Creates a cursor-based flow writer for a page and optional parent structure node.

Parameters​

ParameterTypeDefault valueDescription
pageInternalPageModelundefinedThe internal page model to write into.
embeddedFontsReadonlyMap<string, ParsedTrueTypeFont>undefinedThe embedded font registry used for text layout.
stateFlowStateundefinedThe mutable flow state to use.
parentInternalStructureNode | undefinedundefinedThe parent structure element whose child order should change.
overflowHandler(() => PdfFlow) | undefinedundefined-
fontFamiliesReadonlyMap<string, FontFamilyFaces>...-
textDefaults?TextDefaultsundefined-

Returns​

PdfFlow

Accessors​

columnCount​

Get Signature​

get columnCount(): number;

Gets the total number of flow columns.

Returns​

number

The flow column count.


columnIndex​

Get Signature​

get columnIndex(): number;

Gets the zero-based active column index.

Returns​

number

The current flow column index.


cursorY​

Get Signature​

get cursorY(): number;

Gets the current vertical cursor position.

Returns​

number

The current cursor y-coordinate.


remainingHeight​

Get Signature​

get remainingHeight(): number;

Gets the remaining writable height above the bottom margin.

Returns​

number

The remaining writable height.

Methods​

advanceColumn()​

advanceColumn(): boolean;

Advances the flow cursor to the top of the next column on the same page.

Returns​

boolean

Whether a next column was available.


bmp()​

bmp(data, options?): this;

Adds a BMP image at the current flow cursor.

Parameters​

ParameterTypeDescription
dataBinaryDataThe binary image or font data.
optionsFlowImageOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


checkBox()​

checkBox(name, options): this;

Adds a checkbox form field at the current flow cursor.

Parameters​

ParameterTypeDescription
namestringThe fully-qualified field name.
optionsFlowCheckBoxOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


choiceField()​

choiceField(name, options): this;

Adds a choice form field at the current flow cursor.

Parameters​

ParameterTypeDescription
namestringThe fully-qualified field name.
optionsFlowChoiceFieldOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


circle()​

circle(
cx?,
cy?,
radius?,
style?): this;

Adds a circle path at the current flow cursor.

Parameters​

ParameterTypeDescription
cx?numberCenter x-coordinate override.
cy?numberCenter y-coordinate override.
radius?numberRadius override.
style?PathStyleThe drawing style for the circle.

Returns​

this

This flow helper for chaining.


ellipse()​

ellipse(
cx?,
cy?,
rx?,
ry?,
style?): this;

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​

ParameterTypeDescription
cx?numberCenter x override (defaults to the column center).
cy?numberCenter y override (defaults to one ry below the cursor).
rx?numberHorizontal radius override.
ry?numberVertical radius override.
style?PathStyleThe drawing style for the ellipse.

Returns​

this

This flow helper for chaining.


estimate()​

estimate(block): number;

Estimates the height a template block would consume.

Parameters​

ParameterTypeDescription
blockTemplateBlockThe template block to estimate.

Returns​

number

The estimated height.


estimateTableRowHeights()​

estimateTableRowHeights(rows, options?): readonly number[];

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​

ParameterTypeDescription
rowsreadonly TableRow[]The table rows to measure.
optionsFlowTableOptionsOptions that control the operation.

Returns​

readonly number[]

Per-row heights including padding and trailing rowGap.


freeText()​

freeText(options): this;

Adds a free-text annotation at the current flow cursor.

Parameters​

ParameterTypeDescription
optionsFlowFreeTextOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


gif()​

gif(data, options?): this;

Adds a GIF image at the current flow cursor.

Parameters​

ParameterTypeDescription
dataBinaryDataThe binary image or font data.
optionsFlowImageOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


heading()​

heading(
text,
options?,
annotations?): this;

Adds a heading at the current flow cursor.

Parameters​

ParameterTypeDescription
textstringThe text to add.
optionsFlowHeadingOptionsOptions that control the operation.
annotations?readonly ParagraphTextAnnotation[]-

Returns​

this

This flow helper for chaining.


highlight()​

highlight(options): this;

Adds a highlight annotation at the current flow cursor.

Parameters​

ParameterTypeDescription
optionsFlowHighlightOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


jbig2()​

jbig2(data, options?): this;

Adds a JBIG2 image at the current flow cursor.

Parameters​

ParameterTypeDescription
dataBinaryDataThe binary image or font data.
optionsFlowImageOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


jp2()​

jp2(data, options?): this;

Adds a JPEG 2000 image at the current flow cursor.

Parameters​

ParameterTypeDescription
dataBinaryDataThe binary image or font data.
optionsFlowImageOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


jpeg()​

jpeg(data, options?): this;

Adds a JPEG image at the current flow cursor.

Parameters​

ParameterTypeDescription
dataBinaryDataThe binary image or font data.
optionsFlowImageOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


line()​

line(
x1,
y1,
x2,
y2,
style?): this;

Draws a straight line between two absolute points. Unlike rect and circle, a line does not consume vertical flow space.

Parameters​

ParameterTypeDescription
x1numberStart x in PDF points.
y1numberStart y in PDF points.
x2numberEnd x in PDF points.
y2numberEnd y in PDF points.
style?PathStyleThe drawing style for the line.

Returns​

this

This flow helper for chaining.


link(
text,
url,
options?): this;

Adds a text link at the current flow cursor.

Parameters​

ParameterTypeDescription
textstringThe text to add.
urlstringThe URI target.
optionsFlowLinkOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


list()​

list(items, options): this;

Adds a tagged list at the current flow cursor.

Parameters​

ParameterTypeDescription
itemsreadonly ListItem[]The list items to add.
optionsFlowListOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


moveDown()​

moveDown(distance?): this;

Moves the flow cursor downward by the supplied distance.

Parameters​

ParameterTypeDescription
distancenumberThe distance to move the cursor.

Returns​

this

This flow helper for chaining.


note()​

note(options): this;

Adds a text note annotation at the current flow cursor.

Parameters​

ParameterTypeDescription
optionsFlowNoteOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


paragraph()​

paragraph(
text,
options?,
annotations?): this;

Adds a paragraph at the current flow cursor.

Parameters​

ParameterTypeDescription
textstringThe text to add.
optionsFlowTextOptionsOptions that control the operation.
annotations?readonly ParagraphTextAnnotation[]-

Returns​

this

This flow helper for chaining.


path()​

path(
commands,
style,
height): this;

Adds vector path commands at the current flow cursor.

Parameters​

ParameterTypeDescription
commandsPathCommand[]The vector path commands to add.
stylePathStyleThe drawing style for the path.
heightnumberThe vertical extent consumed by the path.

Returns​

this

This flow helper for chaining.


png()​

png(data, options?): this;

Adds a PNG image at the current flow cursor.

Parameters​

ParameterTypeDescription
dataBinaryDataThe binary image or font data.
optionsFlowImageOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


pushButton()​

pushButton(name, options): this;

Adds a push-button form field at the current flow cursor.

Parameters​

ParameterTypeDescription
namestringThe fully-qualified field name.
optionsFlowPushButtonOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


radioGroup()​

radioGroup(name, options): this;

Adds a radio-button group at the current flow cursor.

Parameters​

ParameterTypeDescription
namestringThe fully-qualified field name.
optionsFlowRadioGroupOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


rect()​

rect(
x?,
y?,
width?,
height?,
style?): this;

Adds a rectangle path at the current flow cursor.

Parameters​

ParameterTypeDescription
x?numberHorizontal position override.
y?numberVertical position override (bottom edge).
width?numberWidth override.
height?numberHeight override.
style?PathStyleThe drawing style for the rectangle.

Returns​

this

This flow helper for chaining.


render()​

render(blocks, stylesheet?): this;

Renders a sequence of template blocks into the flow.

Parameters​

ParameterTypeDescription
blocksreadonly TemplateBlock[]The template blocks to render.
stylesheet?TemplateStylesheetOptional named styles merged beneath each block's inline options.

Returns​

this

This flow helper for chaining.


reservePageLinkRect()​

reservePageLinkRect(options): object;

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​

ParameterTypeDescription
optionsOmit<PageLinkOptions, "x" | "y"> & FlowBlockSpacingOptionsOptions that control the operation.

Returns​

object

The reserved rect in PDF coordinates.

height​
height: number;
width​
width: number;
x​
x: number;
y​
y: number;

richParagraph()​

richParagraph(runs, options?): this;

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​

ParameterTypeDescription
runsreadonly InlineTextRun[]The styled inline runs to lay out together.
optionsFlowRichTextOptionsFlow spacing and inherited style defaults.

Returns​

this


section()​

section(
blocks,
role?,
structure?,
stylesheet?): this;

Renders a section of template blocks within an optional structure container.

Parameters​

ParameterTypeDescription
blocksreadonly TemplateBlock[]Child blocks to render.
role?PdfContainerTagOptional structure role (e.g. "Sect", "Div").
structure?PdfStructureOptionsOptional structure options.
stylesheet?TemplateStylesheet-

Returns​

this

This flow helper for chaining.


setOverflowHandler()​

setOverflowHandler(handler): this;

Registers a callback used by template rendering when flow content exhausts the last column and needs a fresh page.

Parameters​

ParameterTypeDescription
handler(() => PdfFlow) | undefinedCallback that returns the next flow region.

Returns​

this

This flow helper for chaining.


signatureField()​

signatureField(name, options): this;

Adds a signature form field placeholder at the current flow cursor.

Parameters​

ParameterTypeDescription
namestringThe fully-qualified field name.
optionsFlowSignatureFieldOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


squiggly()​

squiggly(options): this;

Adds a squiggly text-markup annotation at the current flow cursor.

Parameters​

ParameterTypeDescription
optionsFlowHighlightOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


strikeOut()​

strikeOut(options): this;

Adds a strike-out text-markup annotation at the current flow cursor.

Parameters​

ParameterTypeDescription
optionsFlowHighlightOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


svg()​

svg(data, options?): this;

Adds an SVG graphic at the current flow cursor.

Parameters​

ParameterTypeDescription
datastring | BinaryDataThe SVG text data.
optionsFlowImageOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


table()​

table(rows, options?): this;

Adds a table at the current flow cursor.

Parameters​

ParameterTypeDescription
rowsreadonly TableRow[]The table rows to add.
optionsFlowTableOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


textBlock()​

textBlock(
text,
options?,
annotations?): this;

Adds a text block at the current flow cursor.

Parameters​

ParameterTypeDescription
textstringThe text to add.
optionsFlowTextOptionsOptions 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()​

textField(name, options): this;

Adds a text form field at the current flow cursor.

Parameters​

ParameterTypeDescription
namestringThe fully-qualified field name.
optionsFlowTextFieldOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


tiff()​

tiff(data, options?): this;

Adds a TIFF image at the current flow cursor.

Parameters​

ParameterTypeDescription
dataBinaryDataThe binary image or font data.
optionsFlowImageOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


underline()​

underline(options): this;

Adds an underline text-markup annotation at the current flow cursor.

Parameters​

ParameterTypeDescription
optionsFlowHighlightOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.


webp()​

webp(data, options?): this;

Adds a WebP image at the current flow cursor.

Parameters​

ParameterTypeDescription
dataBinaryDataThe binary image or font data.
optionsFlowImageOptionsOptions that control the operation.

Returns​

this

This flow helper for chaining.