pdfrx_web
    Preparing search index...

    Interface PdfAnnotationSpec

    Parameters to create or replace an annotation via PdfPage.addAnnotation / PdfPage.updateAnnotation.

    Only these geometries are honored by the engine: ink (freehand; also how the viewer realizes line/arrow), markup quads (highlight/underline/squiggly/ strikeout), and rect-defined square/circle. freeText/text use rect + contents. Coordinates are bounding-box-relative page coordinates (y-up).

    FreeText requires language-aware font selection, measurement and wrapping; emoji are rendered as image runs because PDF text appearances cannot reliably represent modern color emoji. The normal authored-FreeText flow is therefore:

    1. Create a spec with subtype, rect, and contents.
    2. Call PdfDocument.prepareFreeTextAppearance.
    3. Pass that same spec to PdfPage.addAnnotation or PdfPage.updateAnnotation.

    prepareFreeTextAppearance() mutates the spec by filling fontFace, appearanceLines, and appearanceRuns. It recognizes mixed scripts, chooses language-specific CJK fonts when a resolver is available, wraps using the selected fonts, and replaces supported emoji with embedded image runs. Kana and Hangul normally identify Japanese and Korean themselves. For ambiguous Han-only text, the engine uses an explicit BCP-47 hint such as ja, zh-Hant, or ko, followed by the browser's locale when available. Server integrations should obtain the hint from document metadata, the signed-in user's locale, or a parsed Accept-Language preference.

    const spec: PdfAnnotationSpec = {
      subtype: 'freeText',
      rect: { left: 40, bottom: 700, right: 260, top: 750 },
      // Han-only text needs a language hint when no suitable browser locale exists.
      contents: '契約内容 😀',
      fontSize: 14,
    };

    await document.prepareFreeTextAppearance(spec, { language: 'ja' });
    const annotationId = await document.pages[0]!.addAnnotation(spec);

    Most applications should let the preparation method create the appearance fields. Set them directly only when an integration already performs its own font resolution, measurement, line breaking, and emoji rasterization.

    For the reason language affects glyph shapes, the automatic browser/server behavior, Linux font setup, offline assets, caches, and custom providers, read the Text, language, and emoji appearance guide.

    The corresponding PDF annotation dictionaries are defined by ISO 32000-2:2020, 12.5.2 and the subtype-specific parts of 12.5.6.

    interface PdfAnnotationSpec {
        actorId?: string | null;
        appearanceImage?: { height: number; pixels: Uint8Array; width: number };
        appearanceLines?: string[];
        appearancePaths?: {
            fillColor: PdfAnnotationColor | null;
            fillMode: number;
            lineCap: number;
            lineJoin: number;
            segments: {
                close: boolean;
                point: PdfAnnotationPoint;
                type: "line" | "move" | "bezier";
            }[];
            stroke: boolean;
            strokeColor: PdfAnnotationColor
            | null;
            strokeWidth: number;
        }[];
        appearanceRuns?: {
            fontFace: string
            | null;
            image?: {
                height: number;
                pixels: Uint8Array;
                scale: number;
                width: number;
            };
            text: string;
            x: number;
        }[][];
        author?: string
        | null;
        borderWidth?: number;
        color?: PdfAnnotationColor | null;
        contents?: string | null;
        flags?: number;
        fontFace?: string | null;
        fontSize?: number;
        geometry?: PdfAnnotationGeometry;
        id?: string;
        interiorColor?: PdfAnnotationColor | null;
        linkTarget?: PdfLinkTarget;
        rect?: PdfRect;
        revision?: number;
        subtype: PdfAnnotationSubtype;
        textAlign?: "left" | "center" | "right";
        textColor?: PdfAnnotationColor | null;
        textOrientation?: PdfTextOrientation;
        textVerticalAlign?: "top" | "middle" | "bottom";
    }
    Index
    actorId? appearanceImage? appearanceLines? appearancePaths? appearanceRuns? author? borderWidth? color? contents? flags? fontFace? fontSize? geometry? id? interiorColor? linkTarget? rect? revision? subtype textAlign? textColor? textOrientation? textVerticalAlign?
    actorId?: string | null
    appearanceImage?: { height: number; pixels: Uint8Array; width: number }

    RGBA pixels used as the normal appearance of a stamp annotation.

    appearanceLines?: string[]

    Pre-wrapped lines used by the generated FreeText appearance. Usually populated by PdfDocument.prepareFreeTextAppearance.

    appearancePaths?: {
        fillColor: PdfAnnotationColor | null;
        fillMode: number;
        lineCap: number;
        lineJoin: number;
        segments: {
            close: boolean;
            point: PdfAnnotationPoint;
            type: "line" | "move" | "bezier";
        }[];
        stroke: boolean;
        strokeColor: PdfAnnotationColor
        | null;
        strokeWidth: number;
    }[]

    Normalized vector paths used as the normal appearance of a stamp annotation. Points are in a 0–1 box with an SVG-style y-down axis.

    Type Declaration

    • fillColor: PdfAnnotationColor | null
    • fillMode: number
    • lineCap: number
    • lineJoin: number
    • segments: { close: boolean; point: PdfAnnotationPoint; type: "line" | "move" | "bezier" }[]
    • stroke: boolean
    • strokeColor: PdfAnnotationColor | null
    • strokeWidth: number

      Stroke width as a fraction of the appearance width.

    appearanceRuns?: {
        fontFace: string | null;
        image?: {
            height: number;
            pixels: Uint8Array;
            scale: number;
            width: number;
        };
        text: string;
        x: number;
    }[][]

    Per-line positioned font and image runs used for mixed-script text and emoji. Usually populated by PdfDocument.prepareFreeTextAppearance; advanced integrations may construct the runs directly.

    author?: string | null
    borderWidth?: number
    color?: PdfAnnotationColor | null
    contents?: string | null

    Annotation text. For authored FreeText, pass this spec through PdfDocument.prepareFreeTextAppearance to resolve its fonts, wrapping, and emoji image runs.

    flags?: number
    fontFace?: string | null

    Primary font face registered with the engine for a generated FreeText appearance. Usually populated by PdfDocument.prepareFreeTextAppearance.

    fontSize?: number

    FreeText font size in points. Defaults to 12.

    geometry?: PdfAnnotationGeometry
    id?: string

    Identity stored in the PDF annotation dictionary's /NM ("annotation name") entry. Supply an application id when the annotation must correlate with another representation, such as an external store. Omit it to let the engine generate an id; PdfPage.addAnnotation returns the generated value.

    interiorColor?: PdfAnnotationColor | null
    linkTarget?: PdfLinkTarget

    Required when subtype is link; ignored for other annotation types.

    rect?: PdfRect
    revision?: number
    subtype: PdfAnnotationSubtype
    textAlign?: "left" | "center" | "right"

    Horizontal placement of FreeText content within its box. Defaults to left.

    textColor?: PdfAnnotationColor | null

    FreeText glyph color. Defaults to black.

    textOrientation?: PdfTextOrientation

    Text direction for FreeText content. Defaults to page-relative, unrotated.

    textVerticalAlign?: "top" | "middle" | "bottom"

    Vertical placement of FreeText content within its box. Defaults to top.

    Settings
    Member Visibility

    On This Page
    Properties