Skip to content

Latest commit

 

History

History
627 lines (506 loc) · 48.5 KB

APIDocs.md

File metadata and controls

627 lines (506 loc) · 48.5 KB

PdfJsKit Logo

API Docs

Table of Contents

PdfViewer

Extends EventTarget

The viewer component to display PDF files. Renders PDF.js viewer in an iframe but updates UI theme and structure for a neat and fast experience.

Parameters

  • options Object The options for PdfViewer class.

    • options.id String The id that will be used for DOM element of this component in the page. If the id is already used, it will be incremented like pdfViewer2...pdfViewerX. (optional, default "pdfViewer")

    • options.hidden Boolean A value indicating whether the component is displayed when page is loaded. When set to false, the component can be displayed later via calling PdfViewer#show method. For example, the component can be displayed via a button's click event. (optional, default false)

    • options.width (Number | String) The width of the component. If it's a number it will be treated as pixels, if it's a string it will be treated as CSS units (e.g. "80%", "36rem"). (optional, default 960)

    • options.height (Number | String) The height of the component. If it's a number it will be treated as pixels, if it's a string it will be treated as CSS units (e.g. "80%", "36rem"). (optional, default 720)

    • options.border Boolean A value indicating whether the component should haver borders. (optional, default true)

    • options.resizable Boolean A value that specifies if the component can be resized when the user drags sides. (optional, default true)

    • options.libraryPath String The path from where the component should load its assets (css, images etc.). Relative paths will be considered relative to the host page. If not set, script version (.js) will try to use same directory of the script, module version (.mjs) will use "pdfjskit". (optional, default "pdfjskit")

    • options.language String The display (user interface) language of the component. It can be set to the two-letter language names like "en", "de", "fr" etc. or to specific languages like "en-US", "de-DE", "fr-FR" etc. (optional, default "en-US")

    • options.license Object The license info (JSON) you received when you purchased. The evaluation version is the same as the purchased one – the trial version simply becomes licensed when you apply the license. If not set, you will see license reminder every time you load a document. { license: { "key": "42U44-A8W3U-0TG5A-66C4F-3AA0E-776A0", "owner": "*.example.com", "date": "2024-09-01", "product": "PdfJSKit", "type": "Professional", "version": "1.0" } } (optional, default null)

    • options.documentUrl (String | URL) The url of the PDF to open on load. Relative paths will be considered relative to the host page. (optional, default "")

    • options.documentData (PdfJs#TypedArray | ArrayBuffer | Array<number> | string) The binary data of the PDF to open on load. If binary data is provided, then it will be used first instead of documentUrl.Use TypedArrays (Uint8Array) to improve the memory usage. If PDF data is BASE64-encoded, use atob() to convert it to a binary string first.NOTE: If TypedArrays are used they will generally be transferred to the worker-thread. This will help reduce main-thread memory usage, however it will take ownership of the TypedArrays. (optional, default null)

    • options.documentPassword String The password of the PDF to open on load, for decrypting password-protected PDFs. (optional, default null)

    • options.documentSize Number The file size of the PDF to open on load, if known. It's used for progress reports and range requests operations. (optional, default null)

    • options.zoomMode (String | Number) The initial mode for zooming pages in the viewer. Possible values are "auto", "page-actual", "page-width", "page-height", "page-fit" (case insensitive and dashes can be omitted) or a percentage string like "80%" or a percentage number like 80. If not set, the document's zoom level will be remembered per document via browser's local storage. The history will start with "auto". (optional, default "")

    • options.scrollMode String The initial mode for scrolling pages in the viewer. Possible values are "vertical", "horizontal", "wrapped", "page" (case insensitive). If not set, the document's scroll mode will be remembered per document via browser's local storage. The history will start with "vertical".
      Note that if rememberViewHistory is set to false, then it can be derived from 'PageLayout' setting inside PDF if exists. (optional, default "unknown")

    • options.spreadMode String The initial mode for spreading pages in the viewer. Possible values are "none", "odd", "even" (case insensitive). If not set, the document's spread mode will be remembered per document via browser's local storage. The history will start with "none". Note that if rememberViewHistory is set to false, then it can be derived from 'PageLayout' setting inside PDF if exists. (optional, default "unknown")

    • options.sidebarView String The initial active view in sidebar of the viewer. Possible values are "none", "thumbs", "outline", "attachments", "layers" (case insensitive). If not set, the sidebar view will be remembered per document via browser's local storage. The history will start with "none". Note that if rememberViewHistory is set to false, then it can be derived from 'PageMode' setting inside PDF if exists. (optional, default "unknown")

    • options.cursorTool String The initial cursor tool in the viewer. Possible values are "select", "hand" (case insensitive). (optional, default "select")

    • options.rotationMode String A value that specifies whether rotate buttons should only rotate all pages or only the currently viewed page. Possible values are "all-pages", "current-page" (case insensitive and dashes can be omitted). (optional, default "all-pages")

    • options.rememberViewHistory Boolean A value that specifies whether for each document fingerprint, the viewer should remember UI state via browser's local storage, i.e. last viewed page, zoom level, scroll position, rotation, sidebarView, scrollMode, spreadMode. If you want the viewer to discard any view history entries and always load all documents at the first page (and with default zoom values), then you should set this property to false. (optional, default true)

    • options.toolbarVisible Boolean A value that specifies whether the top toolbar is visible. (optional, default true)

    • options.sidebarVisible Boolean A value that specifies whether the left sidebar is visible. (optional, default true)

    • options.verticalToolbarVisible Boolean A value that specifies whether the right vertical toolbar is visible. (optional, default true)

    • options.toolbarAtBottom Boolean A value that specifies whether the top toolbar should be placed at the bottom instead. (optional, default false)

    • options.theme String The theme to use for the viewer. Possible values are "slate", "classic-light", "classic-dark" or the CSS class name of a custom theme. When two values separated by comma is set, the second value will be the dark theme. Dark theme is used when a user indicates their preference through an operating system setting (e.g. light or dark mode) or a user agent setting. When single value is provided, dark theme is disabled, i.e. the only provided theme will be used always even when user prefers dark mode. (optional, default "slate, classic-dark")

    • options.mobileMode String A value that specifies on which mobile device type to use large UI sizing for the viewer. Possible values are "on-any", "on-phone", "on-tablet", "never" (case insensitive and dashes can be omitted). Note that device features are not detected, instead browser's viewport size is used to decide the UI sizing. So if you manually resize the browser window (or emulate a device via browser's F12 dev tools), phone or tablet size can be triggered. (optional, default "on-any")

    • options.debugMode Boolean A value indicating whether to show details in text box in the addition to the main message on error dialog. This can be useful for debugging purpose. (optional, default false)

    • options.events Object? The event handlers to register. An event handler can be a function or name of the function in string. String function name should refer to a valid JavaScript function which is accessible on the host page. String Function names should be specified without parentheses like "FunctionName" or "Namespace.FunctionName". events: { loaded: showEvent, failed: "functionNameInHostPage" }

      function showEvent(e) {
  var json = JSON.stringify(e.detail, null, 2);

  //console.log(e.target);
  //console.log(e.type);
  console.log(json);
}
      • options.events.loaded (Function | String) The event raised when the viewer has been loaded. //SAMPLE OUTPUT: { "eventName": "loaded" } (optional, default null)
      • options.events.failed (Function | String) The event raised when an error occurs. //SAMPLE OUTPUT: { "eventName": "failed", "document": "document.pdf", "message": "Invalid or corrupted PDF file.", "reason": "Invalid PDF structure.", "isResponseError": false } (optional, default null)
      • options.events.documentLoaded (Function | String) The event raised when a document has been loaded. //SAMPLE OUTPUT: { "eventName": "documentLoaded", "document": "document.pdf" } (optional, default null)
      • options.events.pageChanged (Function | String) The event raised when viewed page is changed. //SAMPLE OUTPUT: { "eventName": "pageChanged", "document": "document.pdf", "pageNumber": 2, "pageLabel": null, "previous": 1 } (optional, default null)
      • options.events.pageRendered (Function | String) The event raised when a page had finished rendering. //SAMPLE OUTPUT: { "eventName": "pageRendered", "document": "document.pdf", "pageNumber": 1, "cssTransform": false, "timestamp": 1426.5, "error": null } (optional, default null)
      • options.events.rotationChanged (Function | String) The event raised when page rotation is changed. //SAMPLE OUTPUT: { "eventName": "rotationChanged", "document": "document.pdf", "pagesRotation": 90, "pageNumber": 2, "pageRotation": 90 } (optional, default null)
      • options.events.downloading (Function | String) The event raised before user downloads the original document or PDF version. //SAMPLE OUTPUT: { "eventName": "downloading", "document": "document.pdf", "isFromKeyboard": false, "downloadType": "pdf" } (optional, default null)
      • options.events.printing (Function | String) The event raised before user prints the document. //SAMPLE OUTPUT: { "eventName": "printing", "document": "document.pdf", "totalPages": 91 } (optional, default null)
      • options.events.printed (Function | String) The event raised when printing is completed. //SAMPLE OUTPUT: { "eventName": "printed", "document": "document.pdf", "totalPages": 91 } (optional, default null)
      • options.events.textSelected (Function | String) The event raised when user selects text in the document. //SAMPLE OUTPUT: { "eventName": "textSelected", "document": "document.pdf", "text": "We are intently focused on implementing new and innovative strategies " } (optional, default null)
      • options.events.textCopied (Function | String) The event raised when user copies the selected text in the document. //SAMPLE OUTPUT: { "eventName": "textCopied", "document": "document.pdf", "text": "We are grateful for the recent enactment of the substantial multi-year funding" } (optional, default null)

    • options.permissions Object? The permissions for the viewer to enable/disable corresponding UI elements.

      • options.permissions.viewThumbnails Boolean Ability to view thumbnails for the document pages. (optional, default true)
      • options.permissions.viewOutlines Boolean Ability to view outlines of the document. (optional, default true)
      • options.permissions.viewAttachments Boolean Ability to view attachments of the document. (optional, default true)
      • options.permissions.viewLayers Boolean Ability to view layers of the document. (optional, default true)
      • options.permissions.navigatePages Boolean Ability to navigate pages, e.g. next page, previous page and jump to page. (optional, default true)
      • options.permissions.zoom Boolean Ability to zoom in or out of the document. (optional, default true)
      • options.permissions.changeZoomMode Boolean Ability to change zoom mode of the document, e.g. fit width, fit page etc. (optional, default true)
      • options.permissions.find Boolean Ability to find text within the document. (optional, default true)
      • options.permissions.downloadOriginal Boolean Ability to download the original document. Downloading can be disabled for security (DRM) purpose. (optional, default false)
      • options.permissions.save Boolean Ability to save the document, if there are changes like new annotations, these will be included. Saving can be disabled for additional security (DRM) purpose. (optional, default true)
      • options.permissions.print Boolean Ability to print the displayed document. Printing can be disabled for additional security (DRM) purpose. (optional, default true)
      • options.permissions.open Boolean Ability to open local PDF files, i.e. user is shown "Open" menu item which is when clicked shows browser's open dialog to choose a PDF file to load. (optional, default true)
      • options.permissions.goFullScreen Boolean Ability to switch the viewer to full screen. (optional, default true)
      • options.permissions.goPresentationMode Boolean Ability to switch the viewer to presentation mode. (optional, default true)
      • options.permissions.viewProperties Boolean Ability to view properties of the document. (optional, default true)
      • options.permissions.selectText Boolean Ability to select and copy text in the displayed document Text selection can be disabled for additional security (DRM) purpose. (optional, default true)
      • options.permissions.pan Boolean Ability to pan the document. (optional, default true)
      • options.permissions.rotate Boolean Ability to rotate the page or document, e.g. rotate clockwise and rotate counterclockwise. (optional, default true)
      • options.permissions.changeScrollMode Boolean Ability to change scroll mode of the document, e.g. vertical, horizontal etc. (optional, default true)
      • options.permissions.changeSpreadMode Boolean Ability to change spread mode of the document, e.g. odd, even etc. (optional, default true)
      • options.permissions.viewAnnotations Boolean Ability to view and edit annotations of the document. (optional, default true)
      • options.permissions.fillForms Boolean Ability to fill values into form fields of the document. Requires also ViewAnnotations permission. (optional, default true)

    • options.searchOptions Object? The text search options of the viewer. If you specify a search term, an automatic search will be done when the document is displayed, i.e. the specified term will be searched and the term(s) will be highlighted in the pages. For example, if you launch the viewer from a search results page, you can pass the same search term to the viewer.

      • options.searchOptions.term String A value that specifies the search term used. (optional, default "")
      • options.searchOptions.matchCase Boolean The search should be case-sensitive, i.e. the found text must match the case of the search term. (optional, default false)
      • options.searchOptions.matchDiacritics Boolean The search should match the letters with diacritics (accents), e.g u matches also ü. Diacritics, often loosely called accents, are the various little dots and squiggles which, in many languages, are written above, below or on top of certain letters of the alphabet to indicate something about their pronunciation. (optional, default false)
      • options.searchOptions.matchWholeWord Boolean The search should match the whole word only, i.e the found text must be a whole word (surrounded by a non-word character). (e.g. "doc" matches " doc " or ".doc" but not "document"). (optional, default false)
      • options.searchOptions.matchAnyWord Boolean The search should match the term as a whole or match any word in the term separately (e.g. "bicycle bells" or "bicycle" or "bells"). (optional, default false)
      • options.searchOptions.highlightColor String The color to use for highlighting search results. Default is yellow. (optional, default "#FFFF00")
      • options.searchOptions.activeHighlightColor String The color to use for highlighting active (current) search result. Default is orange. (optional, default "#FFA500")
      • options.searchOptions.highlightAll Boolean A value that specifies whether to highlight all search results, i.e. not only active (current) search result. (optional, default true)

    • options.printOptions Object? The print options of the viewer.

      • options.printOptions.resolution Number A value in percentage that specifies the resolution (quality level) used when printing. The default level ensures excellent quality but may cause slow printing for some documents, you can decrease the level to increase the printing speed while maintaining an acceptable quality for your case. (optional, default 150)
      • options.printOptions.autoRotate Boolean A value that specifies whether to enable automatic rotation of landscape pages upon printing. Note that most browsers may already auto-rotate pages when printing. (optional, default true)

    • options.translations Object? A value that specifies the custom translations for the viewer. The viewer has about 111 language files, however for some few custom text which are not inside those language files, this property is used to override. For example, you can override the default "Rotation Mode" message for localization purpose. translations: { "en": { "preparing-document": "Preparing document...", "cover-sheet": "Cover Sheet", "rotation-mode": "Rotation Mode", "rotation-mode-title": "Rotation Mode (rotate current page or all pages)", "full-screen": "Full Screen", "download-original": "Download Original", "any-word": "Any Word" }, "de": { "any-word": "Jedes Wort" } }

Examples

import PdfViewer from "pdfjskit";
 
var pdfViewer = new PdfViewer({
  documentUrl: "pdfjskit/sample.pdf",
  width: "80%",
  height: 720,
  resizable: true,
  language: "en-US",
  theme: "slate, classic-dark"
});

pdfViewer.render(document.getElementById("container"));

zoomMode

Gets or sets the mode for zooming pages in the viewer. Possible values are "auto", "page-actual", "page-width", "page-height", "page-fit" (case insensitive and dashes can be omitted) or a percentage string like "80%" or a percentage number like 80.

Type: (String | Number)

scrollMode

Gets or sets the mode for scrolling pages in the viewer. Possible values are "vertical", "horizontal", "wrapped", "page" (case insensitive).

Type: String

spreadMode

Gets or sets the mode for spreading pages in the viewer. Possible values are "none", "odd", "even" (case insensitive).

Type: String

sidebarView

Gets or sets the active view in sidebar of the viewer. Possible values are "none", "thumbs", "outline", "attachments", "layers" (case insensitive).

Type: String

cursorTool

Gets or sets the cursor tool in the viewer. Possible values are "select", "hand" (case insensitive).

Type: String

rotationMode

Gets or sets a value that specifies whether rotate buttons should only rotate all pages or only the currently viewed page. Possible values are "all-pages", "current-page" (case insensitive and dashes can be omitted).

Type: String

pagesCount

Gets the page count of the document.

Type: Number

page

Gets or sets the current page of the document.

Type: Number

pagesRotation

Gets or sets the rotation degree for all pages.

Type: Number

pageRotation

Gets or sets the rotation degree for current page only.

Type: Number

fileName

Gets the file name of current document.

Type: String

theme

Gets or sets the theme to use for the viewer. Possible values are "slate", "classic-light", "classic-dark" or the CSS class name of a custom theme. When two values separated by comma is set, the second value will be the dark theme. Dark theme is used when a user indicates their preference through an operating system setting (e.g. light or dark mode) or a user agent setting. When single value is provided, dark theme is disabled, i.e. the only provided theme will be used always even when user prefers dark mode.

Type: String

language

Gets or sets the display (user interface) language of the component. It can be set to the two-letter language names like "en", "de", "fr" etc. or to specific languages like "en-US", "de-DE", "fr-FR" etc.

Type: String

license

Sets the license info (JSON) you received when you purchased. The evaluation version is the same as the purchased one – the trial version simply becomes licensed when you apply the license. If not set, you will see license reminder every time you load a document.

Type: Object

Parameters

  • value

element

Gets the DOM element of this component in the page (if it's rendered).

Type: Element

productInfo

Gets the product info for this component (e.g. product name and version).

Type: Object

render

Renders the component in the page.

Parameters

  • target Element? The target DOM element, e.g. the container or adjacent element. If omitted HTML string will be returned.
  • position String A string representing the position relative to the targetElement* 'beforebegin': Before the targetElement itself.
    • 'afterbegin': Just inside the targetElement, before its first child.
    • 'beforeend': Just inside the targetElement, after its last child.
    • 'afterend': After the targetElement itself. (optional, default "beforeend")

Returns (Element | String) DOM element, if target was specified, otherwise HTML string.

show

Shows the component. Note that the component should be rendered beforehand.

hide

Hides the component. Note that the component should be rendered beforehand.

destroy

Destroys the component. Removes the component element from DOM.

open

Opens a new document.

Parameters

Returns Promise Promise that is resolved when the document is opened.

close

Closes current document.

save

Saves current document. Browser's save dialog will be launched.

saveAsBinary

Saves current document as binary (byte array).

Parameters

  • discardEdits Boolean A value that specifies whether to discard edits e.g. if there are changes like new annotations.

Returns Uint8Array

saveAsBlob

Saves current document as blob.

Parameters

  • discardEdits Boolean A value that specifies whether to discard edits e.g. if there are changes like new annotations.

Returns Blob

downloadOriginal

Downloads the original of current document. Browser's save dialog will be launched.

rotateCurrentPage

Rotates current page by delta degree.

Parameters

  • delta Number The degree to add to the rotation.

rotateAllPages

Rotates all pages by delta degree.

Parameters

  • delta Number The degree to add to the rotation.

toggleFullScreen

Toggles full screen mode.

PdfJs

PDF.js related type definitions.

TypedArray

Type: (Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array)

DocumentInitParameters

Document initialization / loading parameters object.

Type: Object

Properties

  • url (string | URL)? The URL of the PDF.
  • data (PdfJs#TypedArray | ArrayBuffer | Array<number> | string)? Binary PDF data. Use TypedArrays (Uint8Array) to improve the memory usage. If PDF data is BASE64-encoded, use atob() to convert it to a binary string first.NOTE: If TypedArrays are used they will generally be transferred to the worker-thread. This will help reduce main-thread memory usage, however it will take ownership of the TypedArrays.
  • httpHeaders Object? Basic authentication headers.
  • withCredentials boolean? Indicates whether or not cross-site Access-Control requests should be made using credentials such as cookies or authorization headers. The default is false.
  • password string? For decrypting password-protected PDFs.
  • length number? The PDF file length. It's used for progress reports and range requests operations.
  • range PDFDataRangeTransport? Allows for using a custom range transport implementation.
  • rangeChunkSize number? Specify maximum number of bytes fetched per range request. The default value is DEFAULT_RANGE_CHUNK_SIZE.
  • worker PDFWorker? The worker that will be used for loading and parsing the PDF data.
  • verbosity number? Controls the logging level; the constants from VerbosityLevel should be used.
  • docBaseUrl string? The base URL of the document, used when attempting to recover valid absolute URLs for annotations, and outline items, that (incorrectly) only specify relative URLs.
  • cMapUrl string? The URL where the predefined Adobe CMaps are located. Include the trailing slash.
  • cMapPacked boolean? Specifies if the Adobe CMaps are binary packed or not. The default value is true.
  • CMapReaderFactory Object? The factory that will be used when reading built-in CMap files. Providing a custom factory is useful for environments without Fetch API or XMLHttpRequest support, such as Node.js. The default value is {DOMCMapReaderFactory}.
  • useSystemFonts boolean? When true, fonts that aren't embedded in the PDF document will fallback to a system font. The default value is true in web environments and false in Node.js; unless disableFontFace === true in which case this defaults to false regardless of the environment (to prevent completely broken fonts).
  • standardFontDataUrl string? The URL where the standard font files are located. Include the trailing slash.
  • StandardFontDataFactory Object? The factory that will be used when reading the standard font files. Providing a custom factory is useful for environments without Fetch API or XMLHttpRequest support, such as Node.js. The default value is {DOMStandardFontDataFactory}.
  • useWorkerFetch boolean? Enable using the Fetch API in the worker-thread when reading CMap and standard font files. When true, the CMapReaderFactory and StandardFontDataFactory options are ignored. The default value is true in web environments and false in Node.js.
  • stopAtErrors boolean? Reject certain promises, e.g. getOperatorList, getTextContent, and RenderTask, when the associated PDF data cannot be successfully parsed, instead of attempting to recover whatever possible of the data. The default value is false.
  • maxImageSize number? The maximum allowed image size in total pixels, i.e. width * height. Images above this value will not be rendered. Use -1 for no limit, which is also the default value.
  • isEvalSupported boolean? Determines if we can evaluate strings as JavaScript. Primarily used to improve performance of PDF functions. The default value is true.
  • isOffscreenCanvasSupported boolean? Determines if we can use OffscreenCanvas in the worker. Primarily used to improve performance of image conversion/rendering. The default value is true in web environments and false in Node.js.
  • canvasMaxAreaInBytes number? The integer value is used to know when an image must be resized (uses OffscreenCanvas in the worker). If it's -1 then a possibly slow algorithm is used to guess the max value.
  • disableFontFace boolean? By default fonts are converted to OpenType fonts and loaded via the Font Loading API or @font-face rules. If disabled, fonts will be rendered using a built-in font renderer that constructs the glyphs with primitive path commands. The default value is false in web environments and true in Node.js.
  • fontExtraProperties boolean? Include additional properties, which are unused during rendering of PDF documents, when exporting the parsed font data from the worker-thread. This may be useful for debugging purposes (and backwards compatibility), but note that it will lead to increased memory usage. The default value is false.
  • enableXfa boolean? Render Xfa forms if any. The default value is false.
  • ownerDocument Document? Specify an explicit document context to create elements with and to load resources, such as fonts, into. Defaults to the current document.
  • disableRange boolean? Disable range request loading of PDF files. When enabled, and if the server supports partial content requests, then the PDF will be fetched in chunks. The default value is false.
  • disableStream boolean? Disable streaming of PDF file data. By default PDF.js attempts to load PDF files in chunks. The default value is false.
  • disableAutoFetch boolean? Disable pre-fetching of PDF file data. When range requests are enabled PDF.js will automatically keep fetching more data even if it isn't needed to display the current page. The default value is false.NOTE: It is also necessary to disable streaming, see above, in order for disabling of pre-fetching to work correctly.
  • pdfBug boolean? Enables special hooks for debugging PDF.js (see web/debugger.js). The default value is false.
  • CanvasFactory Object? The factory that will be used when creating canvases. The default value is {DOMCanvasFactory}.
  • FilterFactory Object? The factory that will be used to create SVG filters when rendering some images on the main canvas. The default value is {DOMFilterFactory}.
  • enableHWA boolean? Enables hardware acceleration for rendering. The default value is false.