AnnotationsApi

Adds one. A text mark (highlight, underline, squiggly, strikeout) covers quads (omitted or empty: its rect, which becomes their bounds); a line needs line, an ink needs inkList, a polygon needs vertices (three or more corners), a polyline too (two or more). A square, circle, line, drawing, polygon or polyline is written as its tool writes it — the same properties and appearance, so lineEndings: { end: 'openArrow' } is the Arrow tool's arrow: a square's or circle's rect is the box given; a line's, drawing's, polygon's or polyline's is worked out from its geometry, and the one given is not used.

A shape with no color is drawn in #18181B, the default palette's first color; strokeWidth is up to 14 400 points, one point when omitted or null, and 0 gives a square, circle or polygon no outline (a line, drawing or polyline is drawn at one point for 0); lineEndings default to 'none' and are ignored on anything but a line; borderStyle is solid when omitted, dashed or dotted is a pattern sized to the stroke, and cloudy goes round a square, circle or polygon only (an open shape asked for it is drawn solid). An id of your own is written as its name — saved in the file for every reader, so no secrets — and must be one no annotation in the document carries, at most 256 characters, no control characters; omitted, it gets a UUID. flags (a Partial<AnnotationFlags>: a flag left out is off, and it prints unless noPrint) are written as given. A link goes to uri — http:, https:, mailto: or tel:, a bare address gets https://, stored percent-encoded — or to targetPage. Needs the annotations feature.

Changes rect, contents, author, color, fillColor (a square's, circle's or polygon's; refused on anything else) or opacity of the annotation with that id. A color with no alpha changes the color alone; one with an alpha, or an opacity beside it, sets the opacity too; null is refused, a color entry cannot be removed. A new rect moves and scales what the annotation draws — quads, strokes, line ends, a polygon's or polyline's corners — with it; a stamp's or text box's own picture is fitted to it.

update({ color }) rewrites the entry and rebuilds the appearance, so every reader draws the new color. A text box is refused with INVALID_ARGUMENT, since its color is its words'. A stamp accepts the call, but its picture is its own and keeps its colors: only the color entry and the opacity change. update() stamps the modification date when it changes something; it also acts on a reply or a status entry as on any annotation. Needs the annotations feature, and forms too for a form field's widget.

The annotations and the form field values as XFDF — the interchange format Acrobat, Nutrient and Apryse read. Every text mark, note, shape, drawing, polygon, free text and stamp with its name, author, subject, dates, color, opacity, flags, contents, pop-up and geometry; replies (inreplyto) and review statuses (state); the fields' values (<fields>, nested by the dots in their names) as doc.forms.getValues() reads them. A stamp goes out by its name and box alone — its picture stays in the document; a member of an annotation group goes out as an annotation of its own. Dates go out as PDF date strings, coordinates are the page's own, colors #RRGGBB.

Names are the hinge: the SDK writes every annotation's own name as its name, matches by it on import, and reads Acrobat's own names back, so a round trip through a review backend neither duplicates nor loses a comment. Needs the extract feature (the file carries the document's words) and, for the annotations, annotations.

Applies an XFDF file: its annotations are written as create(), reply() and setStatus() write them, with the file's names, authors, subjects and dates (a freetext as the Text Box tool writes it, from its <defaultappearance>), and its <fields> go through doc.forms.setValues().

options.mode: 'merge' (default) — an entry whose name the document already has replaces that annotation in place, keeping the replies in the document the file does not bring back (unless the file moves it to another page, where a thread cannot follow: the old one goes with its thread), and every other entry is added; 'replace' — every annotation the file could describe (text marks, notes, shapes, drawings, polygons, free text, replies, statuses) is removed first, so the document ends up with the file's alone; stamps, links and form fields stay either way.

skipped reasons: unsupported (a stamp, caret, attachment, sound or redaction, a state that is not a review status, an unknown element), no_page, invalid (missing geometry or a refused value, or a name that belongs to a form field, link or pop-up), no_parent (a reply to nothing). flags are written as the file states them; a member of a group (replyType="group") becomes an annotation of its own; an empty attribute is read as none. A name the API cannot write (an obj:… id, one too long) gets a fresh UUID; dashes, icon and a pop-up's own place are read but not written. The license is checked for both halves before either is written, and one annotations change is announced at the end. Needs annotations when the file has annotations, forms when it has fields.

On a certified document the annotations go in only where its certification allows them ('annotations'): at 'forms' a file with annotations is refused with INVALID_STATE unless options.invalidateSignatures (pass annotations: false to take its field values alone), and at 'none' the field values are rejected as read_only.