@mescius/dspdfviewer
Version:
Document Solutions PDF Viewer
464 lines (462 loc) • 15.2 kB
TypeScript
/** @module Viewer/Search */ /** */
import GcPdfViewer from "../GcPdfViewer";
import { IGcTextRect } from '../Models/GcMeasurementTypes';
import { GcPdfSearcher } from './GcPdfSearcher';
import { SearchWorker } from './SearchWorker';
export declare const MaxSearchResultsCount = 25;
/**
* Represents a rectangle with specified coordinates, width, and height.
*/
export declare class Rect {
/**
* Initializes a new instance of the Rect class.
*
* @param {number} left - The left coordinate of the rectangle.
* @param {number} top - The top coordinate of the rectangle.
* @param {number} width - The width of the rectangle.
* @param {number} height - The height of the rectangle.
*
* @throws Will throw an error if any of the provided parameters is not a number.
*/
constructor(left: number, top: number, width: number, height: number);
/** Gets or sets the left coordinate of this {@link Rect}. */
left: number;
/** Gets or sets the top coordinate of this {@link Rect}. */
top: number;
/** Gets or sets the width of this {@link Rect}. */
width: number;
/** Gets or sets the height of this {@link Rect}. */
height: number;
}
/**
* Options for the PDF Searcher.
*/
export type PdfSearcherOptions = {
/**
* The search query.
*/
query: string;
/**
* Indicates whether the search should be treated as a phrase search.
*/
phraseSearch: boolean;
/**
* Indicates whether the search should be case-sensitive.
*/
caseSensitive: boolean;
/**
* Indicates whether the search should match entire words.
*/
entireWord: boolean;
/**
* The search direction, indicating whether to find results in the forward or backward direction.
*/
findPrevious: boolean;
/**
* Indicates whether the search should match words that start with the provided query.
*/
startsWith: boolean;
/**
* Indicates whether the search should match words that end with the provided query.
*/
endsWith: boolean;
/**
* Indicates whether the search should support wildcard characters.
*/
wildcards: boolean;
/**
* Indicates whether the search should perform proximity search.
*/
proximity: boolean;
/**
* Indicates whether all occurrences of the search should be highlighted.
*/
highlightAll: boolean;
};
/**
* Defines options to perform search.
**/
export type FindOptions = {
/**
* The text to search for.
**/
Text: string;
/**
* Specifies whether the search is case sensitive.
**/
MatchCase: boolean;
/**
* Specifies whether to search for the specified whole word only.
**/
WholeWord: boolean;
/**
* Specifies whether to search for at the beginning of the word.
**/
StartsWith: boolean;
/**
* Specifies whether to search for at the beginning of Text.
**/
EndsWith: boolean;
/**
* Specifies whether a search query is wildcards.
* Note, wildcards search cannot be combined with options like 'EndsWith', 'StartsWith', 'WholeWord'.
**/
Wildcards: boolean;
/**
* Proximity searching is a way to search for two or more words that occur within a certain number of words from each other.
**/
Proximity: boolean;
/**
* Specifies whether to perform the search in the backward order.
**/
SearchBackward: boolean;
/**
* Highlight all search results.
**/
HighlightAll: boolean;
};
/**
* Defines a text range.
**/
export declare class Range {
readonly length: number;
/** The range start */
readonly Start: number;
/** The range length */
readonly Length: number;
/**
* Constructor of {@link Range}
* @param start The range start
* @param length The range length
*/
constructor(start: number, length: number);
/** True is range is empty */
get isEmpty(): boolean;
/** Gets the empty range. */
static readonly Empty: Range;
}
/**
* Search result model.
**/
export declare class SearchResult {
/**
* The index of the page where the occurrence is found.
**/
readonly PageIndex: number;
/**
* Text to display.
**/
readonly DisplayText: string;
readonly matchIndex: number;
readonly searcher: GcPdfSearcher | null;
/**
* The logical page item number (for subsequent searches, ordered).
**/
readonly ItemIndex: number;
/**
* Plugin-specific data.
* @ignore
**/
readonly Range: Range;
/**
* Plugin-specific data.
* @ignore
**/
UserData?: any;
/**
* Plugin-specific data.
* @ignore
**/
readonly annotationId?: string | undefined;
/**
* Overall search result index
* @ignore
**/
overallIndex: number;
/**
* Class constructor.
* @param PageIndex The index of the page where the occurrence is found.
* @param DisplayText Text to display.
* @param ItemArea Plugin-specific data.
* @param ItemIndex The logical page item number (for subsequent searches, ordered).
* @param Range Plugin-specific data.
* @param UserData Plugin-specific data.
* @param annotationId Plugin-specific data.
*/
constructor(
/**
* The index of the page where the occurrence is found.
**/
PageIndex: number,
/**
* Text to display.
**/
DisplayText: string, matchIndex: number, searcher: GcPdfSearcher | null,
/**
* The logical page item number (for subsequent searches, ordered).
**/
ItemIndex: number,
/**
* Plugin-specific data.
* @ignore
**/
Range: Range,
/**
* Plugin-specific data.
* @ignore
**/
UserData?: any,
/**
* Plugin-specific data.
* @ignore
**/
annotationId?: string | undefined);
/**
* Search result item area.
* @ignore
**/
get ItemArea(): Rect;
/**
* Represents the display coordinates of a search result.
*
* @type {TextPartsQuadPoints}
* @memberof SearchResult
* @readonly
*
* @description
* This property provides information about the display coordinates of a search result,
* including the page index, outer rectangle coordinates, and quadrilateral points.
*
* The coordinates have their origin at the bottom-left corner as per PDF specifications.
*
* @example
* // Accessing the display coordinates of a search result
* const searchIterator = await viewer.searcher.search(findOptions);
* const searchResults = [];
* let searchResult = await searchIterator.next();
* while (!searchResult.done) {
* searchResults.push(searchResult.value);
* searchResult = await searchIterator.next();
* }
*
* // Accessing the coordinates of the first search result
* if (searchResults.length > 0) {
* const resultCoordinates = searchResults[0].coordinates;
* console.log(resultCoordinates);
* }
*/
get coordinates(): TextPartsQuadPoints;
/**
* Provides detailed information about the search result, including display coordinates
* and the original text data from which the coordinates were derived.
*
* @type {{ coordinates: TextPartsQuadPoints; sourceData: TextSourceData[] }}
* @memberof SearchResult
* @readonly
*
* @description
* This property combines the display coordinates of a search result (`TextPartsQuadPoints`)
* and the underlying text data (`TextSourceData`) used to calculate these coordinates.
*
* The `coordinates` include the page index, quadrilateral points, and rectangle coordinates
* based on the PDF's bottom-left origin.
*
* The `sourceData` contains details like font styles, bounding boxes, and other
* textual metadata essential for rendering or processing the search result.
*
* @example
* // Accessing the detailed information of a search result
* const searchIterator = await viewer.searcher.search(findOptions);
* const searchResults = [];
*
* let searchResult = await searchIterator.next();
* while (!searchResult.done) {
* searchResults.push(searchResult.value);
* searchResult = await searchIterator.next();
* }
*
* // Accessing the detailed information of the first search result
* if (searchResults.length > 0) {
* const resultDetails = searchResults[0].detailedCoordinates;
* console.log(resultDetails.coordinates); // Display coordinates
* console.log(resultDetails.sourceData); // Original text data
* }
*/
get detailedCoordinates(): {
coordinates: TextPartsQuadPoints;
sourceData: TextSourceData[];
};
_collectHighlightRectangles(begin: {
divIdx: number;
offset: number;
}, end: {
divIdx: number;
offset: number;
}, pageContent: any): {
rect: IGcTextRect;
fromOffset: number;
toOffset: number;
}[];
/**
* @hidden Result indicating page boundaries, not an actual result.
* @ignore
**/
static readonly MakePageStart: (pageIndex: number) => SearchResult;
/**
* Result indicating search is finished. Also indicates position past the end of document.
* @ignore
**/
static readonly PastEnd: SearchResult;
/**
* Special result value for Find method to begin searching from the beginning of the document/page
* @ignore
**/
static readonly BeforeBegin: SearchResult;
}
/**
* Represents the progress of a search operation within a document.
*
* @typedef {Object} ProgressModel
*
* @property {number} pageIndex - The current page index being processed.
* @property {number | null} pageCount - The total number of pages in the document, or null if unknown.
*/
export type ProgressModel = {
pageIndex: number;
pageCount: number | null;
};
/**
* Represents the model for a search panel, including the search options, results, and status.
*
* @typedef {Object} SearchPanelModel
*
* @property {FindOptions} options - The options used for the search operation.
* @property {SearchResult[]} results - An array of search results.
* @property {'ready' | 'inprogress' | 'suspended' | 'done' | 'cancelled'} status - The current status of the search operation.
* @property {ProgressModel} progress - The progress of the search operation.
*/
export type SearchPanelModel = {
options: FindOptions;
results: SearchResult[];
status: 'ready' | 'inprogress' | 'suspended' | 'done' | 'cancelled';
progress: ProgressModel;
replaceMode: boolean;
replaceWith?: string;
};
export type SearchMsg = {
type: 'PushResult';
payload: SearchResult;
} | {
type: 'ResetResults';
} | {
type: 'Started';
} | {
type: 'SearchCompleted';
} | {
type: 'Suspended';
} | {
type: 'Cancelled';
} | {
type: 'Progress';
payload: ProgressModel;
} | {
type: 'UpdateOption';
payload: {
option: 'MatchCase' | 'WholeWord' | 'StartsWith' | 'EndsWith' | 'Wildcards' | 'Proximity' | 'HighlightAll';
value: boolean;
};
} | {
type: 'UpdateText';
payload: {
text: string;
};
} | {
type: 'UpdateReplaceWith';
payload: {
replaceWith: string;
};
} | {
type: 'UpdateReplaceMode';
payload: {
replaceMode: boolean;
};
};
/**
* Represents the properties for the SearchPanel component.
*
* @typedef {Object} SearchPanelProps
*
* @property {SearchWorker} searchWorker - The worker responsible for handling search operations.
* @property {GcPdfViewer} viewer - The PDF viewer instance where the search is performed.
*/
export type SearchPanelProps = {
searchWorker: SearchWorker;
viewer: GcPdfViewer;
};
/**
* Initializes and returns a new ProgressModel with default values.
*
* @returns {ProgressModel} The initial progress model with pageIndex set to 0 and pageCount set to 0.
*/
export declare const initSearchProgress: () => ProgressModel;
/**
* Initializes and returns a new SearchPanelModel with default options, an empty results array,
* initial progress, and a status of 'ready'.
*
* @returns {SearchPanelModel} The initial search panel model.
*/
export declare const initSearchModel: () => SearchPanelModel;
/**
* Reducer for search panel state.
* @hidden
*/
export declare const searchStateReducer: (msg: SearchMsg, model: SearchPanelModel) => SearchPanelModel;
export type SearchOptionType = 'MatchCase' | 'WholeWord' | 'StartsWith' | 'EndsWith' | 'Wildcards' | 'Proximity' | 'HighlightAll';
/**
* Represents information about a painted box.
*
* @typedef {Object} PaintedBoxInfo
* @property {number} pageIndex - The index of the page.
* @property {number} x - The x-coordinate of the box.
* @property {number} y - The y-coordinate of the box.
* @property {number} w - The width of the box.
* @property {number} h - The height of the box.
* @property {number} angle - The angle of the box.
* @property {"ltr" | "rtl"} dir - The text direction, either 'ltr' (left-to-right) or 'rtl' (right-to-left).
* @property {boolean} vertical - Indicates whether the box is vertical or horizontal.
*/
export type PaintedBoxInfo = {
pageIndex: number;
x: number;
y: number;
w: number;
h: number;
angle: number;
dir: "ltr" | "rtl";
vertical: boolean;
};
/**
* Represents information about selected or highlighted text fragments in a PDF document.
*
* @typedef {Object} TextPartsQuadPoints
* @property {number} pageIndex - The index of the page containing the text fragments.
* @property {number[]} outerRect - The coordinates of the outer rectangle surrounding the selected text fragments,
* with [x1, y1, x2, y2] format.
* Represents the coordinates of the left/bottom and right/top corners.
* @property {{ x: number; y: number; }[][]} quadPoints - The quadrilateral points defining the selected text fragments,
* where each fragment is represented by an array of points [{ x, y }, ...].
* The coordinates have their origin at the bottom-left corner as per PDF specifications.
*/
export type TextPartsQuadPoints = {
pageIndex: number;
outerRect: number[];
quadPoints: {
x: number;
y: number;
}[][];
};
export type TextSourceData = {
sourceGeoms: any[];
convertedMatchIndex: number;
convertedMatch: any;
};