API reference / Common / Annotation

Interface: Annotation

One annotation: the entries every annotation dictionary carries (Table 164), and its subtype's own in kind.

Coordinates are page-local like the page's content — top-left origin, y-down, translated so the MediaBox top-left is (0, 0) — so the importer flips them from PDF default user space as it flips the page.

Properties

Property	Description
id? string	May be left unset (the all-zero UNSET_ID) in the InsertAnnotations wire form, in which case execution mints a fresh id in its place. The model never stores the sentinel.
rect Rect	/Rect — where the annotation sits on the page.
contents string | null	/Contents — the text shown for it, or its alternate description.
name string | null	/NM — its name, unique among the page's annotations.
modified string | null	/M — when it was last modified, as the PDF date string.
flags AnnotationFlags	/F.
color Color | null	/C — the colour of its background when closed, its title bar, or its border, by subtype. None for no colour (an absent or empty /C).
border | AnnotationBorder | null	/Border — the pre-/BS border description.
borderStyle | AnnotationBorderStyle | null	/BS — the border style, which takes precedence over /Border.
appearance | AnnotationAppearance | null	/AP with the /AS that picks among its states.
optionalContent | OptionalContent | null	/OC — the optional content the annotation's visibility follows.
kind AnnotationKind	/Subtype and the entries only that subtype carries.
ephemeral? boolean	Shown, but never saved: a save writes the page's annotations without it, and an annotation the file held that turns ephemeral leaves the file. A host's own mark — a preview, a live cursor — no file sets.