zeropdf v1.3.0

---

zeropdf / PdfPage

Class: PdfPage

Defined in: src/document.ts:3180

A mutable page builder for placing text, graphics, images, links, annotations, form fields, and structured content on a PDF page.

Constructors

Constructor

new PdfPage(
   page, 
   embeddedFonts, 
   fontFamilies?, 
   textDefaults?, 
   origin?, 
   shapeDefaults?): PdfPage;

Defined in: src/document.ts:3189

Creates a page builder around an internal page model and embedded font registry.

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.
fontFamilies	ReadonlyMap<string, FontFamilyFaces>	...	Font families registered with the document, used to resolve a family name plus bold/italic flags to a concrete face.
textDefaults?	TextDefaults	undefined	-
origin?	"bottom-left" | "top-left"	"bottom-left"	-
shapeDefaults?	ShapeStyle	undefined	-

Returns

PdfPage

Accessors

size

Get Signature

get size(): CustomPageSize;

Defined in: src/document.ts:3250

Gets the page size.

Returns

CustomPageSize

The number of bytes.

Methods

bmp()

bmp(data, options): this;

Defined in: src/document.ts:3652

Adds a BMP image to the page.

Parameters

Parameter	Type	Description
data	BinaryData	The binary image or font data.
options	BmpImageOptions	Options that control the operation.

Returns

this

---

checkBox()

checkBox(name, options): this;

Defined in: src/document.ts:3987

Adds a checkbox form field to the page.

Parameters

Parameter	Type	Description
name	string	The name to assign or look up.
options	CheckBoxOptions	Options that control the operation.

Returns

this

---

choiceField()

choiceField(name, options): this;

Defined in: src/document.ts:4015

Adds a choice form field to the page.

Parameters

Parameter	Type	Description
name	string	The name to assign or look up.
options	ChoiceFieldOptions	Options that control the operation.

Returns

this

---

circle()

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

Defined in: src/document.ts:3593

Draws a circle centered at (cx, cy).

Parameters

Parameter	Type	Description
cx	number	Center x in PDF points.
cy	number	Center y in PDF points.
radius	number	Radius in PDF points.
style?	ShapeStyle	Fill/stroke styling. Stroked when omitted.

Returns

this

---

container()

Creates a tagged structure container on the page.

Param

The structure tag to create.

Param

Either structure options or a build callback.

Param

An optional build callback when options are provided separately.

Call Signature

container(tag, build?): PdfStructureContainer;

Defined in: src/document.ts:3406

Creates a tagged structure container on the page.

Parameters

Parameter	Type	Description
tag	PdfContainerTag	The structure tag to create.
build?	(container) => void	An optional callback that receives the created container.

Returns

PdfStructureContainer

The created structure container.

Call Signature

container(
   tag, 
   options?, 
   build?): PdfStructureContainer;

Defined in: src/document.ts:3419

Creates a tagged structure container on the page.

Parameters

Parameter	Type	Description
tag	PdfContainerTag	The structure tag to create.
options?	PdfStructureOptions	Options that control the operation.
build?	(container) => void	An optional callback that receives the created container.

Returns

PdfStructureContainer

The created structure container.

---

ellipse()

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

Defined in: src/document.ts:3607

Draws an ellipse centered at (cx, cy) with horizontal radius rx and vertical radius ry.

Parameters

Parameter	Type	Description
cx	number	Center x in PDF points.
cy	number	Center y in PDF points.
rx	number	Horizontal radius in PDF points.
ry	number	Vertical radius in PDF points.
style?	ShapeStyle	Fill/stroke styling. Stroked when omitted.

Returns

this

---

flow()

flow(options?): PdfFlow;

Defined in: src/document.ts:3527

Creates a cursor-based flow helper for the page.

Parameters

Parameter	Type	Description
options	FlowOptions	Options that control the operation.

Returns

PdfFlow

The created flow helper.

---

freeText()

freeText(options): this;

Defined in: src/document.ts:3893

Adds a free-text annotation to the page.

Parameters

Parameter	Type	Description
options	FreeTextAnnotationOptions	Options that control the operation.

Returns

this

---

gif()

gif(data, options): this;

Defined in: src/document.ts:3707

Adds a GIF image to the page.

Parameters

Parameter	Type	Description
data	BinaryData	The binary image or font data.
options	GifImageOptions	Options that control the operation.

Returns

this

---

highlight()

highlight(options): this;

Defined in: src/document.ts:3768

Adds a highlight annotation to the page.

Parameters

Parameter	Type	Description
options	HighlightAnnotationOptions	Options that control the operation.

Returns

this

---

image()

image(data, options): this;

Defined in: src/document.ts:3618

Adds a raster image, auto-detecting the format (PNG, JPEG, GIF, BMP, TIFF, WebP, JPEG 2000) from the data. For SVG use svg.

Parameters

Parameter	Type	Description
data	BinaryData	The image bytes.
options	JpegImageOptions	Placement and tagging options.

Returns

this

---

jbig2()

jbig2(data, options): this;

Defined in: src/document.ts:3663

Adds a JBIG2 image to the page.

Parameters

Parameter	Type	Description
data	BinaryData	The binary image or font data.
options	Jbig2ImageOptions	Options that control the operation.

Returns

this

---

jp2()

jp2(data, options): this;

Defined in: src/document.ts:3685

Adds a JPEG 2000 image to the page.

Parameters

Parameter	Type	Description
data	BinaryData	The binary image or font data.
options	Jp2ImageOptions	Options that control the operation.

Returns

this

---

jpeg()

jpeg(data, options): this;

Defined in: src/document.ts:3630

Adds a JPEG image to the page.

Parameters

Parameter	Type	Description
data	BinaryData	The binary image or font data.
options	JpegImageOptions	Options that control the operation.

Returns

this

---

line()

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

Defined in: src/document.ts:3578

Draws a straight line between two points.

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?	ShapeStyle	Stroke styling.

Returns

this

---

link()

link(url, options): this;

Defined in: src/document.ts:3730

Adds a URI link annotation to the page.

Parameters

Parameter	Type	Description
url	string	The URI target.
options	UriLinkOptions	Options that control the operation.

Returns

this

---

linkToPage()

linkToPage(target, options): this;

Defined in: src/document.ts:3742

Adds an internal page link annotation.

Parameters

Parameter	Type	Description
target	PdfPage	The destination page, outline target, or structure element.
options	PageLinkOptions	Options that control the operation.

Returns

this

---

list()

list(items, options): this;

Defined in: src/document.ts:3365

Adds a tagged list to the page.

Parameters

Parameter	Type	Description
items	readonly ListItem[]	The list items to add.
options	ListOptions	Options that control the operation.

Returns

this

---

note()

note(options): this;

Defined in: src/document.ts:3868

Adds a text note annotation to the page.

Parameters

Parameter	Type	Description
options	NoteAnnotationOptions	Options that control the operation.

Returns

this

---

path()

path(commands, style): this;

Defined in: src/document.ts:3545

Adds vector path commands to the page.

Parameters

Parameter	Type	Description
commands	PathCommand[]	The vector path commands to add.
style	PathStyle	The drawing style for the path.

Returns

this

---

placeText()

placeText(text, options): PlacedTextResult;

Defined in: src/document.ts:3336

Draws a single line of text and returns its measured size plus endY — the y where the next element can start. Unlike text (which chains), this returns layout feedback for manual stacking.

Parameters

Parameter	Type	Description
text	string	The text to draw.
options	TextOptions	Text options.

Returns

PlacedTextResult

{ width, height, endY } in PDF points.

---

placeTextBlock()

placeTextBlock(text, options): PlacedTextBlockResult;

Defined in: src/document.ts:3352

Draws a wrapped text block and returns its measured size, line count, and endY — the y just below the block, for stacking the next element.

Parameters

Parameter	Type	Description
text	string	The text to wrap and draw.
options	TextBlockOptions	Text block options.

Returns

PlacedTextBlockResult

{ width, height, lineCount, endY } in PDF points.

---

png()

png(data, options): this;

Defined in: src/document.ts:3641

Adds a PNG image to the page.

Parameters

Parameter	Type	Description
data	BinaryData	The binary image or font data.
options	PngImageOptions	Options that control the operation.

Returns

this

---

pushButton()

pushButton(name, options): this;

Defined in: src/document.ts:4074

Adds a push-button form field to the page.

Parameters

Parameter	Type	Description
name	string	The name to assign or look up.
options	PushButtonOptions	Options that control the operation.

Returns

this

---

radioGroup()

radioGroup(name, options): this;

Defined in: src/document.ts:4043

Adds a radio-button group to the page.

Parameters

Parameter	Type	Description
name	string	The name to assign or look up.
options	RadioGroupOptions	Options that control the operation.

Returns

this

---

rect()

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

Defined in: src/document.ts:3565

Draws a rectangle. Convenience wrapper over path.

Parameters

Parameter	Type	Description
x	number	Left edge in PDF points.
y	number	Bottom edge in PDF points.
width	number	Width in PDF points.
height	number	Height in PDF points.
style?	ShapeStyle	Fill/stroke styling. Stroked when omitted.

Returns

this

---

restoreState()

restoreState(): this;

Defined in: src/document.ts:4136

Restores the most recently saved graphics state.

Returns

this

---

richText()

richText(runs, options): this;

Defined in: src/document.ts:3304

Adds a paragraph of inline rich-text runs. Each InlineTextRun carries its own style yet the runs flow on the same line and wrap together as one paragraph. Runs that omit a style inherit it from options, then from the document defaults; runs carrying a link become clickable.

Supports left/center/right/justify alignment via options.align, line-level direction ("ltr"/"rtl"/"auto"), and writingMode: "vertical" (single column). In the flow and template layouts the paragraph wraps and splits across columns and pages.

Parameters

Parameter	Type	Description
runs	readonly InlineTextRun[]	The styled inline runs to lay out together.
options	RichTextOptions	Block geometry and inherited style defaults.

Returns

this

Example

page.richText(
  [
    { text: "Read the " },
    { text: "terms", bold: true, link: "https://x.com/terms" },
    { text: " before continuing." },
  ],
  { x: 56, y: 700, width: 300, fontSize: 12 },
);

---

rotate()

rotate(degrees): this;

Defined in: src/document.ts:4176

Adds a rotation transform to subsequent page operations.

Parameters

Parameter	Type	Description
degrees	number	The rotation angle in degrees.

Returns

this

---

saveState()

saveState(): this;

Defined in: src/document.ts:4127

Saves the current graphics state.

Returns

this

---

scale()

scale(x, y?): this;

Defined in: src/document.ts:4166

Adds a scale transform to subsequent page operations.

Parameters

Parameter	Type	Default value	Description
x	number	undefined	The horizontal transform value.
y	number	x	The vertical transform value.

Returns

this

---

setExtGState()

setExtGState(options): this;

Defined in: src/document.ts:4208

Sets graphics-state parameters (alpha and/or blend mode) for subsequent painting operations. Emitted as an inline ExtGState entry referenced by the gs operator. Pair with saveState/restoreState to scope the effect.

Parameters

Parameter	Type	Description
options	ExtGStateOptions	Alpha and blend-mode options.

Returns

this

---

signatureField()

signatureField(name, options): this;

Defined in: src/document.ts:4102

Adds a signature form field placeholder to the page.

Parameters

Parameter	Type	Description
name	string	The name to assign or look up.
options	SignatureFieldOptions	Options that control the operation.

Returns

this

---

squiggly()

squiggly(options): this;

Defined in: src/document.ts:3843

Adds a squiggly text-markup annotation to the page.

Parameters

Parameter	Type	Description
options	SquigglyAnnotationOptions	Options that control the operation.

Returns

this

---

strikeOut()

strikeOut(options): this;

Defined in: src/document.ts:3818

Adds a strike-out text-markup annotation to the page.

Parameters

Parameter	Type	Description
options	StrikeOutAnnotationOptions	Options that control the operation.

Returns

this

---

structure()

Creates a tagged structure container on the page.

Param

The replacement structure role.

Param

Either structure options or a build callback.

Param

An optional build callback when options are provided separately.

Call Signature

structure(role, build?): PdfStructureContainer;

Defined in: src/document.ts:3467

Creates a tagged structure container on the page.

Parameters

Parameter	Type	Description
role	| string & object | PdfStandardStructureTag	The replacement structure role.
build?	(container) => void	An optional callback that receives the created container.

Returns

PdfStructureContainer

The created structure container.

Call Signature

structure(
   role, 
   options?, 
   build?): PdfStructureContainer;

Defined in: src/document.ts:3480

Creates a tagged structure container on the page.

Parameters

Parameter	Type	Description
role	| string & object | PdfStandardStructureTag	The replacement structure role.
options?	PdfStructureOptions	Options that control the operation.
build?	(container) => void	An optional callback that receives the created container.

Returns

PdfStructureContainer

The created structure container.

---

svg()

svg(data, options): this;

Defined in: src/document.ts:3718

Adds an SVG graphic to the page.

Parameters

Parameter	Type	Description
data	string | BinaryData	The SVG text data.
options	SvgImageOptions	Options that control the operation.

Returns

this

---

table()

table(rows, options): this;

Defined in: src/document.ts:3385

Adds a tagged table to the page.

Parameters

Parameter	Type	Description
rows	readonly TableRow[]	The table rows to add.
options	TableOptions	Options that control the operation.

Returns

this

---

text()

text(text, options): this;

Defined in: src/document.ts:3260

Adds text to the page.

Parameters

Parameter	Type	Description
text	string	The text to add.
options	TextOptions	Options that control the operation.

Returns

this

---

textBlock()

textBlock(text, options): this;

Defined in: src/document.ts:3272

Adds a multiline text block to the page.

Parameters

Parameter	Type	Description
text	string	The text to add.
options	TextBlockOptions	Options that control the operation.

Returns

this

---

textField()

textField(name, options): this;

Defined in: src/document.ts:3959

Adds a text form field to the page.

Parameters

Parameter	Type	Description
name	string	The name to assign or look up.
options	TextFieldOptions	Options that control the operation.

Returns

this

---

tiff()

tiff(data, options): this;

Defined in: src/document.ts:3674

Adds a TIFF image to the page.

Parameters

Parameter	Type	Description
data	BinaryData	The binary image or font data.
options	TiffImageOptions	Options that control the operation.

Returns

this

---

toInternalModel()

toInternalModel(): InternalPageModel;

Defined in: src/document.ts:4219

Returns the internal page model used by serializers and editors.

Returns

InternalPageModel

The internal page model.

---

transform()

transform(matrix): this;

Defined in: src/document.ts:4194

Adds a raw transformation matrix to subsequent page operations.

Parameters

Parameter	Type	Description
matrix	Transform	The transformation matrix to apply.

Returns

this

---

translate()

translate(x, y): this;

Defined in: src/document.ts:4155

Adds a translation transform to subsequent page operations.

Parameters

Parameter	Type	Description
x	number	The horizontal transform value.
y	number	The vertical transform value.

Returns

this

---

underline()

underline(options): this;

Defined in: src/document.ts:3793

Adds an underline text-markup annotation to the page.

Parameters

Parameter	Type	Description
options	UnderlineAnnotationOptions	Options that control the operation.

Returns

this

---

webp()

webp(data, options): this;

Defined in: src/document.ts:3696

Adds a WebP image to the page.

Parameters

Parameter	Type	Description
data	BinaryData	The binary image or font data.
options	WebpImageOptions	Options that control the operation.

Returns

this