FindReplaceAddon Class Reference

Provides APIs to find or replace text in the PDF document. More...

Inherits UIXAddon.

Public Member Functions
	activate ()
	Activate find and replace function. More...
	clearCache ()
	Call this function to clear the cache before each new find or replace operation. More...
	deactivate ()
	Deactivate find and replace function. Must be called after activate. More...
async	find (find, options)
	Find text. More...
async	replace (find, replace, options)
	Replace text. It will do find first, then replace. More...
async	replaceAll (find, replace, options)
	Replace all text. It will do find first, then replace. More...
	setNeedToReplace (callback)
	A callback function to verify whether need to replace the text. It works on [replace]FindReplaceAddon#replace and [replaceAll]FindReplaceAddon#replaceAll API. More...

Detailed Description

Provides APIs to find or replace text in the PDF document.

Since

9.2.0

Example of obtaining and using the FindReplace Addon:

pdfui.getAddonInstance('FindReplaceUIXAddon').then(findReplace => {
  if (findReplace) {
    // ...
  } else {
    console.error("FindReplace Addon instance not found.");
  }
});

Member Function Documentation

activate()

FindReplaceAddon::activate ( )

inline

Activate find and replace function.

Returns

Promise<void> - Promise resolved when the find and replace function is activated.

Example of obtaining and using the FindReplace Addon:

pdfui.getAddonInstance('FindReplaceUIXAddon').then(findReplace => {
  if (findReplace) {
    findReplace.activate();
  } else {
    console.error("FindReplace Addon instance not found.");
  }
});

Since

9.2.0

clearCache()

FindReplaceAddon::clearCache ( )

inline

Call this function to clear the cache before each new find or replace operation.

Since

10.0.0

deactivate()

FindReplaceAddon::deactivate ( )

inline

Deactivate find and replace function. Must be called after activate.

Returns

Promise<void> - Promise resolved when the find and replace function is deactivated.

Example of obtaining and using the FindReplace Addon:

pdfui.getAddonInstance('FindReplaceUIXAddon').then(findReplace => {
  if (findReplace) {
    findReplace.deactivate();
  } else {
    console.error("FindReplace Addon instance not found.");
  }
});

Since

9.2.0

find()

async FindReplaceAddon::find (   find,   options  )

inline

Find text.

Note

Usually, you need to activate the find and replace function before using the APIs. For activation and deactivation, see [activate]FindReplaceAddon#activate and [deactivate]FindReplaceAddon#deactivate.

Parameters

find	string - Text to find.
[options]	Object - Options for finding.
[options.pageRange]	Array - Specifies page index range, like: [startIndex: number, endIndex: number]. Default is all pages. The valid page range: from 0 to count - 1. count is the total number of pages.
[options.wholeWords=false]	boolean - Whether to match whole words.
[options.caseSensitive=false]	boolean - Whether to match case sensitive.
[options.isReversed=false]	boolean - Whether to search in reversed order.

Returns

Promise<{isFound: boolean; pageIndex: number; rectArray: Array<{left: number; right: number; top: number; bottom: number}>}> - Find result. The rectArray is PDF coordinates.

Example of obtaining and using the FindReplace Addon:

pdfui.getAddonInstance('FindReplaceUIXAddon').then(findReplace => {
    if (findReplace) {
        findReplace.activate().then(() => {
           // Call this function to clear the cache before each new find or replace operation.
           findReplace.clearCache().then(_ => {
             findReplace.find('text to find', {
                pageRange: [0, 3], 
                wholeWords: true,
                caseSensitive: true,
                isReversed: true
             }).then(result => {
                // ... 
             }); 
           });
        });
    } else {
        console.error("FindReplace Addon instance not found.");
    }
});

Since

9.2.0

replace()

async FindReplaceAddon::replace (   find,   replace,   options  )

inline

Replace text. It will do find first, then replace.

Note

Usually, you need to activate the find and replace function before using the APIs. For activation and deactivation, see [activate]FindReplaceAddon#activate and [deactivate]FindReplaceAddon#deactivate.

Parameters

find	string - Text to find.
replace	string - Text to replace.
[options]	Object - Options for finding.
[options.pageRange]	Array - Specifies page index range, like: [startIndex: number, endIndex: number]. Default is all pages. The valid page range: from 0 to count - 1. count is the total number of pages.
[options.wholeWords=false]	boolean - Whether to match whole words.
[options.caseSensitive=false]	boolean - Whether to match case sensitive.
[options.isReversed=false]	boolean - Whether to search in reversed order.

Returns

Promise<number> - The state of the replacement operation. 0: The target was not found. 1: Replacement was successful. 2: Replacement failed. 3: The specified target is not the one to replace. 4: An unknown error occurred.

Example of obtaining and using the FindReplace Addon:

pdfui.getAddonInstance('FindReplaceUIXAddon').then(findReplace => {
    if (findReplace) {
        findReplace.activate().then(() => {
           // Call this function to clear the cache before each new find or replace operation.
           findReplace.clearCache().then(_ => {
             findReplace.replace('text to find', 'text to replace', {
                pageRange: [0, 3],
                wholeWords: true,
                caseSensitive: true,
                isReversed: true
             }).then(() => {
                // The text is replaced
             }, () => {
                // Finished searching the document. No matches were found. 
             }); 
          });
        });
    } else {
        console.error("FindReplace Addon instance not found.");
    }
});

Since

9.2.0

replaceAll()

async FindReplaceAddon::replaceAll (   find,   replace,   options  )

inline

Replace all text. It will do find first, then replace.

Note

Usually, you need to activate the find and replace function before using the APIs. For activation and deactivation, see [activate]FindReplaceAddon#activate and [deactivate]FindReplaceAddon#deactivate.

Parameters

find	string - Text to find.
replace	string - Text to replace.
[options]	Object - Options for finding.
[options.pageRange]	Array - Specifies page index range, like: [startIndex: number, endIndex: number]. Default is all pages. The valid page range: from 0 to count - 1. count is the total number of pages.
[options.wholeWords=false]	boolean - Whether to match whole words.
[options.caseSensitive=false]	boolean - Whether to match case sensitive.

Returns

Promise<number> - Promise resolved with the number of replacements.

Example of obtaining and using the FindReplace Addon:

pdfui.getAddonInstance('FindReplaceUIXAddon').then(findReplace => {
    if (findReplace) {
        findReplace.activate().then(() => {
          // Call this function to clear the cache before each new find or replace operation.
          findReplace.clearCache().then(_ => {
            findReplace.replaceAll('text to find', 'text to replace', {
                pageRange: [0, 3],
                wholeWords: true,
                caseSensitive: true
            }).then((count) => {
                // ... 
            }); 
         });
        });
    } else {
        console.error("FindReplace Addon instance not found.");
    }
});

Since

9.2.0

setNeedToReplace()

FindReplaceAddon::setNeedToReplace (   callback )

inline

A callback function to verify whether need to replace the text. It works on [replace]FindReplaceAddon#replace and [replaceAll]FindReplaceAddon#replaceAll API.

Note

Usually, you need to activate the find and replace function before using the APIs. For activation and deactivation, see [activate]FindReplaceAddon#activate and [deactivate]FindReplaceAddon#deactivate.

Parameters

callback

(find: string, replace: string, pageIndex: number, rectArray: Array<{left: number; right: number; top: number; bottom: number}>) => Promise<boolean> - The callback function will be called when a match is found. If the callback function returns true, the text will be replaced. If the callback function returns false, the text will not be replaced. Parameter rectArray is PDF coordinates of the matched text.

Example of obtaining and using the FindReplace Addon:

pdfui.getAddonInstance('FindReplaceUIXAddon').then(findReplace => {
    if (findReplace) {
        findReplace.activate().then(() => {
            // First, set the callback function.
            findReplace.setNeedToReplace((find, replace, pageIndex, rectArray) => {
                // verify whether need to replace the text
                return Promise.resolve(true);
            });
           // Then, call the replace API.
            findReplace.replace('text to find', 'text to replace', {
                pageRange: [0, 3],
                wholeWords: true,
                caseSensitive: true,
                isReversed: true
             }).then(() => {
                // The text is replaced
             }, () => {
                // Finished searching the document. No matches were found. 
             }); 
         });
    } else {
        console.error("FindReplace Addon instance not found.");
    }
});

Since

10.0.0