Message APINPM Package/docs/guides/files

Files Guide

NPM SDK guide for opening documents, synchronizing file state, switching tabs and pages, exporting, printing, and recovering from file errors.

Scope And NPM Prerequisites

This guide covers the NPM document API. Mount the viewer and wait for viewer.ready() before opening a URL, server path, or browser file. Register document listeners before an open action when the host UI must show state transitions.

Implementation Order

Canvas owns the open-file list, active file, and page state. The host UI reflects NPM document events instead of predicting success from the initial command.

  • 1Subscribe to document events before opening.
  • 2Use viewer.documents.open({ url, displayName }) for a Canvas-reachable source.
  • 3Use viewer.documents.openFile(file) for a browser File.
  • 4Enable dependent controls only after the open result and current file events establish active state.
  • 5Use events to synchronize tabs, metadata, pages, and export status.
  • 6Unsubscribe and destroy the viewer on route cleanup.

Open And Synchronize File State

An open promise resolves from observed file state. The opened event is NPM-normalized from Canvas metadata and progress completion, not a PostMessage success envelope. Use activeId to join fileTabs, fileInfo, and pageList; do not use a displayed file name or tab title as an identifier.

  • viewer.documents.on("opening", handleOpening)
  • viewer.documents.on("opened", handleOpened)
  • viewer.documents.on("failed", handleFailed)
  • viewer.documents.on("fileInfo", handleFileInfo)
  • viewer.documents.on("fileTabs", handleFileTabs)
  • viewer.documents.on("pageList", handlePageList)
  • viewer.documents.setActiveFileByIndex(index)
  • viewer.documents.selectPage(pageNumber)

Export, Print, And Recovery

Export is asynchronous: viewer.documents.export() resolves with a generated file URL after export completion. Allow only one active export per viewer. Print is fire-and-forget, so do not show a completed-print state because the NPM SDK has no documented print result event.

  • viewer.documents.export()
  • viewer.documents.export({ timeoutMs })
  • viewer.documents.on("exportComplete", handleExportComplete)
  • viewer.documents.print()
  • On open failure, clear loading state, preserve the selected source, and offer retry or replacement.
  • A null fileInfo event must render an empty details panel safely.
  • After tab switching, wait for fileTabs, fileInfo, or pageList before showing the final active file.
  • On export failure or timeout, unlock Export and allow a manual retry.
  • Remove all document-event subscriptions on route cleanup.

Verification Checklist

Verify URL opening, browser-file opening, tab switching, and export against files with different types or display names.

  • Opening and failure UI are driven by document events.
  • A local File uses openFile; a Canvas-reachable source uses open.
  • The host tab bar uses activeId and follows Canvas after a switch request.
  • A null fileInfo payload renders safely.
  • Export stays pending until its result or error; print does not imply completion.
  • Route unmount removes listeners and destroys the viewer.