Web SDKv1.0.0
Get started (opens in a new tab)Changelog (opens in a new tab)Playground (opens in a new tab)JavaScript PDF viewer (opens in a new tab)Get a free key (opens in a new tab)

EditTextToolApi

The Edit Text tool, drivable from code. This is the one that replaces DOM puppeteering outright.

Every member needs the tool to be active (await viewer.activateTool('editText') first) and the edit-text feature; beginEdit, and setText with any text but '', also need extract. A page is analyzed on demand, so editing does not depend on what the user happens to have scrolled into view. Text set this way travels the same path as typing, so font substitution, reflow, and undo all behave identically.

A tool handle throws SDKError INVALID_STATE, with instructions, when its tool is not running, rather than failing silently: "The editText tool is not active. Call viewer.activateTool('editText') and await it first."

commit() and cancel() both deactivate the tool, exactly as pressing Save or Escape in the toolbar does, because committing rewrites and reloads the page. Re-activate before further edits, and treat every block id from before a commit as stale — ids are only stable within one detection pass.

namespaceviewer.tools.editText

Usage

TypeScript
await viewer.activateTool('editText');

const editText = viewer.tools.editText;
const blocks = await editText.listBlocks(0);

const total = blocks.find((b) => b.text.startsWith('Total:'));
if (total) {
  await editText.setText(total.id, 'Total: $1,299.00');
  await editText.commit();
}

Reading

listBlocksmethodsince 1.0.0
listBlocks(pageIndex: number): Promise<EditableTextBlock[]>
The editable text blocks on a page, as EditableTextBlock[]. Each block's text is '' under a license without extract.
ParameterTypeDescription
pageIndexnumberZero-based page index.
Returns Promise<EditableTextBlock[]> Each { id, pageIndex, text, bounds, fontFamily, fontSize, fontWeight, isItalic, fillColor, opacity }; id is stable within one detection pass, text includes an uncommitted edit, bounds is a Rect in page space.
  • INVALID_STATE while the tool is not active — without edit-text it cannot be activated.
  • INVALID_ARGUMENT for a page index the document has not.
  • PAGE_ERROR when the page could not be loaded.
TypeScript
const blocks = await viewer.tools.editText.listBlocks(0);
editingBlockIdgettersince 1.0.0
get editingBlockId(): string | null
The block currently open for editing, or null.
Returns string | null
  • INVALID_STATE while the tool is not active — without edit-text it cannot be activated.
selectedBlockIdgettersince 1.0.0
get selectedBlockId(): string | null
The selected block, or null.
Returns string | null
  • INVALID_STATE while the tool is not active — without edit-text it cannot be activated.
hasPendingEditsgettersince 1.0.0
get hasPendingEdits(): boolean
Whether edits are pending — not yet in the document, so not yet in viewer.hasUnsavedChanges. Every way of leaving the tool writes them, and so does an export from createExporter(), so this is for a host's own beforeunload warning beside hasUnsavedChanges; false while the tool is not active.
Returns boolean
TypeScript
window.addEventListener('beforeunload', (e) => {
  if (viewer.hasUnsavedChanges || viewer.tools.editText.hasPendingEdits) e.preventDefault();
});

Editing

beginEditmethodsince 1.0.0
beginEdit(blockId: string): Promise<void>
Opens a block for editing — what a double-click does. Needs edit-text and extract: the editor shows the block's words in the page.
ParameterTypeDescription
blockIdstringA block id from listBlocks() of the current detection pass.
Returns Promise<void>
  • INVALID_STATE while the tool is not active — without edit-text it cannot be activated.
  • FEATURE_NOT_LICENSED without extract.
  • INVALID_ARGUMENT for a text block id that names no block.
  • PAGE_ERROR when the block's page could not be loaded.
TypeScript
const [first] = blocks;
if (first) await viewer.tools.editText.beginEdit(first.id);
setTextmethodsince 1.0.0
setText(blockId: string, text: string): Promise<void>
Replaces a block's text, opening it first if needed. An empty string removes the block, as the toolbar's delete does. Without extract only that is allowed; retyping rejects with FEATURE_NOT_LICENSED, as it opens the block. A block read as right-aligned — an amount in a column, a heading over values set flush under it — keeps its right edge and grows to the left, exactly as when typed.
ParameterTypeDescription
blockIdstringA block id from listBlocks() of the current detection pass.
textstringThe new text; '' removes the block.
Returns Promise<void>
  • INVALID_STATE while the tool is not active — without edit-text it cannot be activated.
  • INVALID_ARGUMENT, the text left as it was, when it holds a character no available font can draw; or for a block id that names no block.
  • FEATURE_NOT_LICENSED without extract for any text but ''.
  • INVALID_STATE when other blocks keep being opened while it waits for fonts (a text block that kept losing its editing surface to another).
  • PAGE_ERROR when the block's page could not be loaded.
TypeScript
await viewer.tools.editText.setText(total.id, 'Total: $1,299.00');
await viewer.tools.editText.setText(footnote.id, ''); // removes the block
commitmethodsince 1.0.0
commit(): Promise<void>
Writes every pending edit into the document and reports textChanged. Deactivates the tool, as pressing Save in the toolbar does; re-activate before further edits, and re-read listBlocks() — every block id from before a commit is stale.
Returns Promise<void>
  • INVALID_STATE while the tool is not active — without edit-text it cannot be activated.
TypeScript
await viewer.tools.editText.commit();
cancelmethodsince 1.0.0
cancel(): Promise<void>
Discards every pending edit — the one way to: leaving the tool by any other means writes them. Deactivates the tool, as pressing Escape in the toolbar does.
Returns Promise<void> Resolves once discarded.
  • INVALID_STATE while the tool is not active — without edit-text it cannot be activated.
TypeScript
await viewer.tools.editText.cancel();