@syncfusion/ej2-pdf
Version:
Feature-rich JavaScript PDF library with built-in support for loading and manipulating PDF document.
486 lines (485 loc) • 18 kB
TypeScript
import { _PdfCrossReference } from './../pdf-cross-reference';
import { PdfPage } from './../pdf-page';
import { _PdfDictionary, _PdfReference } from './../pdf-primitives';
import { PdfAnnotation, PdfPopupAnnotation, PdfFileLinkAnnotation, PdfUriAnnotation, PdfComment } from './annotation';
/**
* The class provides methods and properties to handle the collection of `PdfAnnotation`.
* ```typescript
* // Load an existing PDF document
* let document: PdfDocument = new PdfDocument(data);
* // Access annotation coolection from first page
* let annotations: PdfAnnotationCollection = document.getPage(0).annotations;
* // Save the document
* document.save('output.pdf');
* // Destroy the document
* document.destroy();
* ```
*/
export declare class PdfAnnotationCollection {
/**
* Holds raw annotation references for the page.
*
* @private
*/
_annotations: Array<_PdfReference>;
/**
* Holds popup comment annotations associated with annotations.
*
* @private
*/
_comments: Array<PdfPopupAnnotation>;
/**
* Cache of parsed annotations keyed by their index.
*
* @private
*/
_parsedAnnotations: Map<number, PdfAnnotation>;
/**
* Indicates whether the collection is being used for export operations.
*
* @private
*/
_isExport: boolean;
private _page;
private _crossReference;
/**
* Represents a annotation collection.
*
* @private
* @param {Array<_PdfReference>} array Annotation references.
* @param {_PdfCrossReference} xref Cross reference object.
* @param {PdfPage} page PDF page object.
*/
constructor(array: Array<_PdfReference>, xref: _PdfCrossReference, page: PdfPage);
/**
* Gets the annotation count (Read only).
*
* @returns {number} Number of annotations.
*
* ```typescript
* // Load an existing PDF document
* let document: PdfDocument = new PdfDocument(data, password);
* // Access first page
* let page: PdfPage = document.getPage(0);
* // Gets the annotation count
* let count: number = page.annotations.count;
* // Destroy the document
* document.destroy();
* ```
*/
readonly count: number;
/**
* Gets the `PdfAnnotation` at the specified index.
*
* ```typescript
* // Load an existing PDF document
* let document: PdfDocument = new PdfDocument(data, password);
* // Access first page
* let page: PdfPage = document.getPage(0);
* // Access the annotation at index 0
* let annotation: PdfAnnotation = page.annotations.at(0);
* // Save the document
* document.save('output.pdf');
* // Destroy the document
* document.destroy();
* ```
*
* @param {number} index Field index.
* @returns {PdfAnnotation} Annotation at the specified index
*/
at(index: number): PdfAnnotation;
/**
* Add a new `PdfAnnotation` into the collection.
*
* ```typescript
* // Load an existing PDF document
* let document: PdfDocument = new PdfDocument(data, password);
* // Access first page
* let page: PdfPage = document.getPage(0);
* // Add a new annotation into the collection
* page.annotations.add(annotation);
* // Save the document
* document.save('output.pdf');
* // Destroy the document
* document.destroy();
* ```
*
* @param {PdfAnnotation} annotation Annotation to add.
* @returns {number} Annotation index.
*/
add(annotation: PdfAnnotation): number;
/**
* Remove an annotation from the collection.
*
* ```typescript
* // Load an existing PDF document
* let document: PdfDocument = new PdfDocument(data);
* // Access first page
* let page: PdfPage = document.getPage(0);
* // Access first annotation from the PDF page
* let annotation: PdfAnnotation = page.annotations.at(0);
* // Remove an annotation from the collection
* page.annotations.remove(annotation);
* // Save the document
* document.save('output.pdf');
* // Destroy the document
* document.destroy();
* ```
*
* @param {PdfAnnotation} annotation Annotation to remove.
* @returns {void} Nothing.
*/
remove(annotation: PdfAnnotation): void;
/**
* Remove an annotation from the collection at the specified index.
*
* ```typescript
* // Load an existing PDF document
* let document: PdfDocument = new PdfDocument(data);
* // Access first page
* let page: PdfPage = document.getPage(0);
* // Remove an annotation from the collection
* page.annotations.removeAt(0);
* // Save the document
* document.save('output.pdf');
* // Destroy the document
* document.destroy();
* ```
*
* @param {number} index Annotation index.
* @returns {void} Nothing.
*/
removeAt(index: number): void;
/**
* Processes and prunes matching object references from the provided arrays,
* synchronizing internal annotation lists, parsed indices, and cross-reference cache.
*
* @private
* @param {_PdfReference[]} references The references to remove.
* @param {_PdfReference[]} array The target reference array to prune from.
* @returns {void} No return value.
*/
_processReferences(references: _PdfReference[], array: _PdfReference[]): void;
/**
* Iterates popup annotations and removes their references from the provided reference array,
* keeping internal state in sync.
*
* @private
* @param {PdfPopupAnnotationCollection} annotationCollection The popup annotation collection to scan.
* @param {_PdfReference[]} array The reference array to remove entries from.
* @returns {void} No return value.
*/
_processAnnotations(annotationCollection: PdfPopupAnnotationCollection, array: _PdfReference[]): void;
/**
* Reindexes parsed annotation entries after a removal, shifting keys above the given index down by one.
*
* @private
* @param {number} index The removed index that subsequent keys should shift below.
* @returns {void} No return value.
*/
_reorderParsedAnnotations(index: number): void;
/**
* Updates the appearance resources of a rubber stamp annotation by processing
* its normal appearance graphics with the associated cross-reference.
*
* @private
* @param {PdfAnnotation} annotation The annotation whose appearance resources will be updated.
* @returns {void} No return value.
*/
_updateCustomAppearanceResource(annotation: PdfAnnotation): void;
/**
* Updates comment and review-history child references for the given annotation
* by applying the specified processing flag to both collections.
*
* @private
* @param {PdfComment} annotation The parent annotation.
* @param {number} flag The processing flag applied to children.
* @returns {void} No return value.
*/
_addCommentsAndReview(annotation: PdfComment, flag: number): void;
/**
* Updates child popup-annotation references for comments or review history,
* assigning appropriate IRT links and flags, and adds each processed child
* to the annotation structure unless the operation is restricted.
*
* @private
* @param {PdfComment} annotation The parent annotation to reference from.
* @param {PdfPopupAnnotationCollection} collection The child popup collection to update.
* @param {number} flag The processing flag governing add/deny behavior.
* @returns {void} No return value.
*/
_updateChildReference(annotation: PdfComment, collection: PdfPopupAnnotationCollection, flag: number): void;
/**
* Parses and caches page annotations when not already initialized, resolving references,
* handling popups with external parents, and storing parsed annotations by their index.
*
* @private
* @returns {void} No return value.
*/
_getAnnotations(): void;
/**
* Determines whether the given dictionary represents a popup annotation
* that has an external parent entry, indicating it should not be parsed
* as a standalone annotation.
*
* @private
* @param {_PdfDictionary} dictionary The dictionary to inspect.
* @returns {boolean} True if the popup has an external parent; otherwise, false.
*/
_isPopupWithExternalParent(dictionary: _PdfDictionary): boolean;
/**
* Parses a raw annotation dictionary into a strongly-typed annotation instance
* based on its subtype and context, handling special cases like popups with
* external parents, geometric variants, and link-action types.
*
* @private
* @param {_PdfDictionary} dictionary The raw annotation dictionary to parse.
* @param {number} [index] Optional index of the annotation in the page array.
* @returns {PdfAnnotation} The parsed annotation instance, or undefined when not applicable.
*/
_parseAnnotation(dictionary: _PdfDictionary, index?: number): PdfAnnotation;
/**
* Creates a file or URI link annotation from the given dictionary by inspecting
* the action subtype and target, defaulting to a URI link when unspecified.
*
* @private
* @param {_PdfDictionary} dictionary The link annotation dictionary to analyze.
* @returns {PdfFileLinkAnnotation|PdfUriAnnotation} The constructed link annotation.
*/
_getLinkAnnotation(dictionary: _PdfDictionary): PdfFileLinkAnnotation | PdfUriAnnotation;
/**
* Determines whether the border array represents a valid textweb link border,
* ensuring all values are defined and nonpositive, as required for link detection.
*
* @private
* @param {number[]} border The border array to validate.
* @returns {boolean} True if the border represents a valid text web link; otherwise, false.
*/
_hasValidBorder(border: number[]): boolean;
/**
* Determines whether the border array represents a valid textweb link border,
* ensuring all values are defined and nonpositive, as required for link detection.
*
* @private
* @param {number[]} isFlatten The border array to validate.
* @returns {void} nothing.
*/
_doPostProcess(isFlatten: boolean): void;
/**
* Reorders the annotations array by swapping a candidate entry into the specified tab index
* when the parent reference or the item itself matches the provided reference.
*
* @private
* @param {_PdfReference} ref The reference used to match the target item to move.
* @param {number} tabIndex The desired position to place the matched item.
* @param {number} index The current index of the candidate item in the annotation array.
* @returns {_PdfReference[]} The updated annotations reference array.
*/
_reArrange(ref: _PdfReference, tabIndex: number, index: number): _PdfReference[];
/**
* Clears all annotation data by resetting raw references, parsed annotations,
* and cached comment collections to their initial empty state.
*
* @private
* @returns {void} No return value.
*/
_clear(): void;
}
/**
* Represents the collection of `PdfPopupAnnotation`
* ```typescript
* // Load an existing PDF document
* let document: PdfDocument = new PdfDocument(data);
* // Access annotation collection from first page
* let annotations: PdfRectangleAnnotation = document.getPage(0).annotations;
* // Gets the comments of annotation
* let comments: PdfPopupAnnotationCollection = annotation.comments;
* // Save the document
* document.save('output.pdf');
* // Destroy the document
* document.destroy();
* ```
*/
export declare class PdfPopupAnnotationCollection {
/**
* Indicates whether the annotation is part of a review workflow.
*
* @private
*/
_isReview: boolean;
/**
* Holds the associated parent annotation for the popup.
*
* @private
*/
_annotation: PdfAnnotation;
/**
* Stores the parent dictionary reference for serialization and lookup.
*
* @private
*/
_parentDictionary: _PdfDictionary;
/**
* Maintains the list of popup annotations linked to the parent annotation.
*
* @private
*/
_collection: PdfPopupAnnotation[];
/**
* References the page on which the popup annotations are located.
*
* @private
*/
_page: PdfPage;
/**
* Caches the last resolved parent object reference for reuse.
*
* @private
*/
_lastParentReference: _PdfReference;
/**
* Initializes a new instance of the `PdfPopupAnnotationCollection` class
*
* @private
* @param {PdfAnnotation} annotation Annotation reference
* @param {boolean} isReview Boolean flag to set review
*/
constructor(annotation: PdfAnnotation, isReview: boolean);
/**
* Gets the annotation count (Read only).
*
* @private
* @returns {number} Number of annotations
*
* ```typescript
* // Load an existing PDF document
* let document: PdfDocument = new PdfDocument(data);
* // Access annotation collection from first page
* let annotations: PdfRectangleAnnotation = document.getPage(0).annotations;
* // Gets the comments of annotation
* let comments: PdfPopupAnnotationCollection = annotation.comments;
* // Gets the count of comments
* let count: number = comments.count;
* // Save the document
* document.save('output.pdf');
* // Destroy the document
* document.destroy();
* ```
*/
readonly count: number;
/**
* Gets the popup annotation at the specified index.
*
* ```typescript
* // Load an existing PDF document
* let document: PdfDocument = new PdfDocument(data);
* // Access annotation collection from first page
* let annotations: PdfRectangleAnnotation = document.getPage(0).annotations;
* // Gets the comments of annotation
* let comments: PdfPopupAnnotationCollection = annotation.comments;
* // Gets the first comment
* let comment: PdfPopupAnnotation = comments.at(0);
* // Save the document
* document.save('output.pdf');
* // Destroy the document
* document.destroy();
* ```
*
* @private
* @param {number} index Index of the annotation
* @returns {number} Annotation at the specified index
*/
at(index: number): PdfPopupAnnotation;
/**
* Add a new popup annotation into the collection
*
* ```typescript
* // Load an existing PDF document
* let document: PdfDocument = new PdfDocument(data, password);
* // Access first page
* let page: PdfPage = document.getPage(0);
* // Create a new popup annotation
* const popupAnnotation: PdfPopupAnnotation = new PdfPopupAnnotation('Test popup annotation', 10, 40, 30, 30);
* popupAnnotation.author = 'Syncfusion';
* // Add a new popup annotation into the collection
* annotation.comments.add(popupAnnotation);
* // Save the document
* document.save('output.pdf');
* // Destroy the document
* document.destroy();
* ```
*
* @param {PdfPopupAnnotation} annotation Annotation to add
* @returns {void} Nothing
*/
add(annotation: PdfPopupAnnotation): void;
/**
* Remove an annotation from the collection
*
* ```typescript
* // Load an existing PDF document
* let document: PdfDocument = new PdfDocument(data);
* // Access annotation collection from first page
* let annotations: PdfRectangleAnnotation = document.getPage(0).annotations;
* // Gets the comments of annotation
* let comments: PdfPopupAnnotationCollection = annotation.comments;
* // Gets the first comment
* let comment: PdfPopupAnnotation = comments.at(0);
* // Remove the comment
* comments.remove(comment);
* // Save the document
* document.save('output.pdf');
* // Destroy the document
* document.destroy();
* ```
*
* @param {PdfPopupAnnotation} annotation Annotation to remove
* @returns {void} Nothing
*/
remove(annotation: PdfPopupAnnotation): void;
/**
* Remove an annotation from the collection at the specified index
*
* ```typescript
* // Load an existing PDF document
* let document: PdfDocument = new PdfDocument(data);
* // Access annotation collection from first page
* let annotations: PdfRectangleAnnotation = document.getPage(0).annotations;
* // Gets the comments of annotation
* let comments: PdfPopupAnnotationCollection = annotation.comments;
* // Remove the first comment
* comments.removeAt(0);
* // Save the document
* document.save('output.pdf');
* // Destroy the document
* document.destroy();
* ```
*
* @param {number} index Annotation index to remove
* @returns {void} Nothing
*/
removeAt(index: number): void;
/**
* Parses either review data or regular comment data based on the current parsing mode.
*
* @private
* @returns {void} No return value.
*/
_parseCommentsOrReview(): void;
/**
* Parses and aggregates review-thread popup annotations linked to the current annotation,
* attaching matching replies to the collection and deferring unmatched items to the comments cache.
*
* @private
* @returns {void} No return value.
*/
_parseReview(): void;
/**
* Parses non-review comment-thread popup annotations linked to the current annotation,
* collecting direct comment replies and preserving unrelated items in the comments cache.
*
* @private
* @returns {void} No return value.
*/
_parseComments(): void;
}