@mescius/dspdfviewer
Version:
Document Solutions PDF Viewer
282 lines (281 loc) • 13.7 kB
TypeScript
import { ReplaceTextModel } from "../Models/ViewerTypes";
/**
* Represents a custom text highlight within a document.
*/
export interface ICustomHighlight {
/**
* An array of rectangles that specify the position and dimensions of the highlight areas on the page.
* Each rectangle can be defined in one of two formats:
*
* 1. **Object format**:
* - `{ x: number, y: number, w: number, h: number }`
* - `x` and `y` represent the coordinates of the rectangle's bottom-left corner.
* - `w` (width) represents the horizontal size of the rectangle, extending to the right from `x`.
* - `h` (height) represents the vertical size of the rectangle, extending upwards from `y`.
*
* 2. **Array format**:
* - `[x1: number, y1: number, x2: number, y2: number]`
* - `x1` and `y1` represent the coordinates of the rectangle's bottom-left corner.
* - `x2` and `y2` represent the coordinates of the rectangle's top-right corner.
*
* **Coordinate System**:
* - The coordinate system's origin (0, 0) is at the bottom-left corner of the page.
* - Coordinates `x` and `y` increase to the right and upwards, respectively.
* - Width (`w`) extends to the right from the `x` position, and height (`h`) extends upwards from the `y` position.
* - All measurements (x, y, w, h) are in pdf points (pt).
*/
rects: ({
x: number;
y: number;
w: number;
h: number;
} | number[])[];
/**
* The fill color of the highlight in `rgba`, `hex`, or named color format.
* If not specified, defaults to 'rgba(255, 255, 0, 0.5)'.
*/
color?: string;
/**
* The color of the highlight border in `rgba`, `hex`, or named color format.
* If not specified, defaults to 'rgba(255, 165, 0, 0.75)'.
*/
borderColor?: string;
/**
* The width of the highlight border in pixels.
* If not specified, defaults to 2 pixels.
*/
borderWidth?: number;
/**
* The text content associated with the highlight.
*/
text?: string;
/**
* A custom function to handle the painting of the highlight.
* @param {CanvasRenderingContext2D} ctx - The rendering context of the canvas to draw on.
* @param {ICustomHighlight} highlight - The highlight object containing details for painting.
*/
paintHandler?: (ctx: CanvasRenderingContext2D, highlight: ICustomHighlight) => void;
hashId?: string;
}
/**
* Options for customizing the appearance of a text highlight.
*/
export type HighlightStyleArgs = {
/** The fill color for the highlight, specified in `rgba`, `hex`, or named color format. */
color?: string;
/** The border color for the highlight, specified in `rgba`, `hex`, or named color format. */
borderColor?: string;
/** The width of the highlight border in pixels. */
borderWidth?: number;
};
/**
* Options for controlling the behavior when adding or clearing text highlights.
*/
export type HighlightBehaviorArgs = {
/** If `true`, clears existing highlights before applying the new one. */
clearPrevious?: boolean;
/** If `true`, skips the immediate repaint of the text layer after applying the highlight. */
skipPaint?: boolean;
};
/**
* Combined options for adding or updating a text highlight.
*
* This type merges the style and behavior options for customizing and managing text highlights.
*/
export type HighlightArgs = HighlightStyleArgs & HighlightBehaviorArgs;
/**
* Interface for managing text highlights within a document.
* Provides methods to add, remove, retrieve, and clear text highlights on specific pages.
*/
export interface ITextHighlightManager {
/**
* Highlights a specified segment of text on a given page.
*
* This method allows you to highlight a portion of text by specifying the start and end character indices.
* The appearance of the highlight can be customized using the optional parameters.
*
* @param {number} pageIndex - The index of the page where the text segment is located (0-based).
* @param {number} startCharIndex - The starting character index (0-based) of the text segment to highlight.
* @param {number} endCharIndex - The ending character index (0-based) of the text segment to highlight.
* @param {Object} [args] - Optional parameters to customize the appearance and behavior of the highlight.
* @param {string} [args.color] - The fill color for the highlight in `rgba`, `hex`, or named color format.
* @param {string} [args.borderColor] - The border color for the highlight in `rgba`, `hex`, or named color format.
* @param {number} [args.borderWidth] - The width of the highlight border in pixels.
* @param {boolean} [args.clearPrevious=false] - If `true`, clears existing highlights before adding the new one.
* @param {boolean} [args.skipPaint=false] - If `true`, skips the immediate repaint of the text layer after adding the highlight.
* @returns {Promise<void>} A promise that resolves once the highlight has been added.
*
* @example
* // Highlight text on page 2 from character index 10 to 20 with a yellow background:
* highlightManager.highlightTextSegment(2, 10, 20, { color: 'rgba(255, 255, 0, 0.5)' });
*/
highlightTextSegment(pageIndex: number, startCharIndex: number, endCharIndex: number, args?: {
color?: string;
borderColor?: string;
borderWidth?: number;
clearPrevious?: boolean;
skipPaint?: boolean;
}): Promise<boolean>;
/**
* Clears all highlights from one or more specific pages.
*
* Removes all custom highlights from the specified pages. You can pass either a single page index or an array of page indices.
*
* @param {number | number[]} pageIndex - The index of the page or an array of page indices to clear highlights from.
*
* @example
* // Clear highlights from page 3:
* highlightManager.clearHighlightedSegments(3);
*
* @example
* // Clear highlights from pages 1, 4, and 5:
* highlightManager.clearHighlightedSegments([1, 4, 5]);
*/
clearHighlightedSegments(pageIndex: number | number[], args?: HighlightBehaviorArgs): void;
/**
* Retrieves all highlights for a specified page.
*
* Returns an array of highlight objects present on the given page.
*
* @param {number} pageIndex - The index of the page to retrieve highlights from (0-based).
* @returns {ICustomHighlight[]} An array of highlights on the specified page.
*
* @example
* // Get all highlights from page 2:
* const highlights = viewer.getHighlights(2);
*/
getHighlightsForPage(pageIndex: number): ICustomHighlight[];
/**
* Retrieves an array of `ReplaceTextModel` data from the replaced highlights.
* This method iterates over the `replaceHighlights` map, collects the `replaceData`
* from each highlight, and returns it in an array.
*
* @returns {ReplaceTextModel[] | undefined} An array of `ReplaceTextModel` objects,
* or `undefined` if no replace highlights are found.
*/
getReplaceTextData(): ReplaceTextModel[] | undefined;
/**
* Repaints the text layer for one or more specified pages.
*
* This method updates the display of highlights by repainting the text layer on the specified pages.
*
* @param {number | number[]} pageIndices - The index or indices of the pages to repaint.
*
* @example
* // Repaint the text layer for page 1:
* highlightManager.repaintTextLayer(1);
*
* @example
* // Repaint the text layer for pages 2 and 3:
* highlightManager.repaintTextLayer([2, 3]);
*/
repaintTextLayer(pageIndices: number | number[]): void;
/**
* Adds a custom highlight directly to a specified page.
*
* This method allows you to add a predefined highlight object to a specific page.
*
* @param {number} pageIndex - The index of the page where the highlight should be added (0-based).
* @param {ICustomHighlight} highlight - The highlight object to add.
* @param {HighlightBehaviorArgs} [args] - Optional behavior arguments, such as whether to skip repainting the text layer after adding the highlight.
*
* @example
* // Add a custom highlight to page 1:
* const highlight = { rects: [{ x: 10, y: 20, w: 100, h: 15 }], color: 'rgba(0, 255, 0, 0.3)' };
* highlightManager.addHighlight(1, highlight);
*/
addHighlight(pageIndex: number, highlight: ICustomHighlight, args?: HighlightBehaviorArgs): number;
/**
* Adds a replace text highlight to the specified page's replaced highlights map.
*
* @param {number} pageIndex - The index of the page where the highlight should be added.
* @param {ICustomHighlight} highlight - The highlight object to add.
* @param {HighlightBehaviorArgs} [args] - Optional behavior arguments, such as whether to skip repainting the text layer after adding the highlight.
*/
addReplaceHighlight(pageIndex: number, highlight: ICustomHighlight, args?: HighlightBehaviorArgs): {
start: number;
end: number;
};
/**
* Adds replace text highlights to the specified page's replaced highlights map.
*
* @param {number} pageIndex - The index of the page where the highlight should be added.
* @param {ICustomHighlight} highlight - The highlight object to add.
* @param {HighlightBehaviorArgs} [args] - Optional behavior arguments, such as whether to skip repainting the text layer after adding the highlight.
*/
addReplaceHighlights(pageIndex: number, highlights: ICustomHighlight[], args?: HighlightBehaviorArgs): {
start: number;
end: number;
};
/**
* Removes a highlight from the specified page's replaced highlights map by its index.
*
* @param {number} pageIndex - The index of the page where the highlight should be removed.
* @param {number} index - The index of the highlight in the replaceHighlights array to remove.
*/
removeReplaceHighlight(pageIndex: number, index: number, args?: HighlightBehaviorArgs): void;
/**
* Removes highlights from the specified page's replaced highlights map by their index range.
*
* @param {number} pageIndex - The index of the page where the highlights should be removed.
* @param {{ start: number; end: number }} indices - The range of indices specifying which highlights to remove.
* @param {HighlightBehaviorArgs} [args] - Optional behavior arguments, such as whether to skip repainting the text layer.
*/
removeReplaceHighlights(pageIndex: number, indices: {
start: number;
end: number;
}, args?: HighlightBehaviorArgs): void;
/**
* Clears all replaced highlights for a specified page.
*
*/
clearAllReplaceHighlights(args?: HighlightBehaviorArgs): void;
/**
* Removes a specific highlight from a page.
*
* This method removes a highlight at a specified index from the highlights on a given page.
*
* @param {number} pageIndex - The index of the page from which to remove the highlight (0-based).
* @param {number} index - The index of the highlight to remove within the specified page.
* @param {HighlightBehaviorArgs} [args] - Optional behavior arguments, such as whether to skip repainting the text layer after removing the highlight.
*
* @example
* // Remove the first highlight from page 2:
* viewer.removeHighlight(2, 0);
*
* @example
* // Remove the second highlight from page 1 and skip repainting:
* viewer.removeHighlight(1, 1, { skipPaint: true });
*/
removeHighlight(pageIndex: number, index: number, args?: HighlightBehaviorArgs): any;
/**
* Clears all highlights from all pages in the document.
*
* This method removes all custom highlights from every page in the document. You can optionally control whether to skip repainting the text layer after clearing the highlights.
*
* @param {HighlightBehaviorArgs} [args] - Optional behavior arguments. If `skipPaint` is `true`, the text layer will not be repainted immediately after clearing the highlights.
*
* @example
* // Clear all highlights from the entire document and repaint the text layer:
* highlightManager.clearAllHighlights();
*
* @example
* // Clear all highlights from the entire document and skip repainting:
* highlightManager.clearAllHighlights({ skipPaint: true });
*/
clearAllHighlights(args?: HighlightBehaviorArgs): any;
/**
* Cleans up the document by resetting the highlights and replaced highlights.
* This method clears all current highlights and replaced highlights,
* effectively preparing the document for a new state or fresh rendering.
*/
cleanupDocument(): any;
/**
* Checks if a replace highlight exists for the given page and hash ID.
*
* @param {number} pageIndex - The index of the page to check.
* @param {string} hashId - The unique hash ID of the replace highlight to check.
* @returns {boolean} `true` if the replace highlight exists, otherwise `false`.
*/
hasReplaceHighlight(pageIndex: number, hashId: string): any;
}