AnnotationsApi.create()
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.
Signature
Parameters
| Parameter | Type | Description |
|---|---|---|
| pageIndex | number | Zero-based page index. |
| annotation | NewAnnotation | type (one of highlight, underline, squiggly, strikeout, note, link, square, circle, line, ink, polygon, polyline) and rect are required; contents, author, color, opacity, fillColor, quads, line, inkList, vertices, strokeWidth, lineEndings, borderStyle, uri, targetPage, id, flags, created and modified are optional. |
| options? | SignedDocumentOptions | { invalidateSignatures? }. |
Returns
Promise<string> The new annotation's id.
Throws
INVALID_ARGUMENT— a stamp, a free text, atypeit does not make (the message names the ones it does:'rectangle'is'square'), a missing line, strokes or corners, a shape point that is not a number or lies past ±14 400 points, a color string the API does not take, anopacityoutside 0–1, a stroke width outside 0 to 14 400, an end cap not inLineEnding, a border style not inBorderStyle, another link scheme, atargetPagethat is not a page of the document, apageIndexthat is not a page of the document, anidthat is empty, taken, longer than 256 characters, holds a control character or is of theobj:…form the SDK derives, a web link whoseuriis'', or text-mark quads with a coordinate that is not a number or lies past ±14 400 points, or that run along more than 1 440 000 points of line in all.PAGE_ERROR— the annotation could not be added.FEATURE_NOT_LICENSED— the license lacksannotations.DOCUMENT_CLOSED— the document has been closed.INVALID_STATE— a certified document whose certification forbids it, unlessoptions.invalidateSignatures; or a progressive document still downloading.
Example
const id = await doc.annotations.create(0, { type: 'line', rect: { x: 0, y: 0, width: 0, height: 0 }, // worked out from the geometry line: { start: { x: 72, y: 600 }, end: { x: 300, y: 600 } }, lineEndings: { end: 'openArrow' }, // the Arrow tool's arrow color: '#D92D20', });