@mescius/dspdfviewer
Version:
Document Solutions PDF Viewer
419 lines (343 loc) • 18 kB
Markdown
# Document Solutions PDF Viewer and Editor
#### [日本語](#japanese)
__Document Solutions PDF Viewer__ (__DsPdfViewer__) is a fast, modern JavaScript based PDF viewer and editor that runs in all major browsers.
The viewer can be used as a cross platform solution to view (or modify - see _Support API_ below) PDF documents on Windows, MAC, Linux, iOS and Android devices.
DsPdfViewer is included in [Document Solutions for PDF (DsPdf)](https://developer.mescius.com/document-solutions/dot-net-pdf-api) - a feature-rich cross-platform PDF API library for .NET Core.
Client-side (Wasm) or server-side
([DS.Documents.Pdf.ViewerSupportApi](https://www.nuget.org/packages/DS.Documents.Pdf.ViewerSupportApi/))
[_Support API_](#support_api) option allows you to turn DsPdfViewer into a powerful PDF editor
that can be used to edit existing or create new PDFs, fill and save PDF forms,
remove (redact) sensitive content, add or edit annotations and AcroForm fields, and more.
DsPdfViewer provides a rich JavaScript object model, see __docs/index.html__ for the client API documentation.
Product highlights:
- Works in all modern browsers, including Edge, Chrome, FireFox, Opera, Safari
- Provides form filling and PDF editing tools (see [_Support API_](#support_api)):
- Customizable and mobile-friendly form filler
- Annotation and form editors
- Quick edits using secondary toolbars
- PDF redaction
- Signature verification
- Real-time collaboration mode
- Other editing features
- Works with frameworks such as React, Preact, Angular
- Supports form filling; filled forms can be printed or form data can be submitted to the server
- Supports XFA (XML Forms Architecture) forms
- Provides caret for text selection/copy, including vertical and RTL texts
- Includes thumbnails, text search, outline, attachments, articles, layers and structure tags panels
- Allows opening PDF files from local disks
- Supports annotations including text, free text, rich text etc.
- Supports redact annotations (including appearance streams), allows user to hide or show redacts
- Supports sound annotations
- Allows rotating and printing the rotated document
- Supports article threads navigation
- Supports file attachments
- Comes with several themes, new custom themes can be added
- Supports external CMaps
- ...and more.
## See it in action
- Go to [Document Solutions for PDF Viewer demos](https://developer.mescius.com/document-solutions/javascript-pdf-viewer/demos/)
to explore the various features of DsPdfViewer, including features that rely on [_Support API_](#support_api).
The demo site allows you to modify the demo code and immediately see the effect of your changes.
- The [Document Solutions for PDF API demo site](https://developer.mescius.com/document-solutions/dot-net-pdf-api/demos/)
uses DsPdfViewer to display sample PDFs.
## Latest changes
## [9.1.0] - 05-May-2026
### Added
- Added support for cross-domain iframe licensing. (DOC-7243)
### Changed
- SignalR is now disabled by default (`supportApi.webSocketUrl` is `false`). (DOC-7328)
## Fixed
- Various bug fixes and stability improvements.
## [9.0.4] - 07-Apr-2026
### Fixed
- Fixed an issue where setting viewer.options.snapAlignment = true in the console had no effect. (DOC-5680)
- Fixed an issue where the selected value of a radio button did not persist after saving. (DOC-7351)
## [9.0.3] - 03-Mar-2026
### Fixed
- Fixed an issue where rotated annotations were rendered incorrectly. (DOC-5762)
- Fixed an issue where SVG/PNG export could produce ZIP files with duplicated `.zip` extensions. (DOC-7227)
- Fixed runtime errors that occurred when host DOM element was removed and re-created using Angular `@if / *ngIf` with `hideAnnotationPopups` enabled. (DOC-7277)
- Fixed an issue where mouse wheel scrolling in side panels also scrolled the document in the main window. (DOC-7349)
- Fixed an issue where DsPdfViewer rendered text highlights immediately instead of skipping paint when `skipPaint: true` was specified. (DOC-7160)
- [iOS] Fixed an issue that caused incorrect position of custom highlights in the `Custom Highlights` demo. (DOC-6629)
- Fixed an issue where multi-select list box fields ignored multiple default values after a reset. (DOC-7423)
## [9.0.2] - 04-Feb-2026
### Fixed
- Fixed cross-Origin frame access violation when the viewer is loaded from a jscodemine hosted sample. (DOC-7339)
- [Mobile] Fixed an issue where the value of a checkbox was not updated on a Mobile Phone. (DOC-6865)
- Fixed incorrect mouse wheel behavior where it scrolled unfocused main window before scrolling focused side panel. (DOC-6955)
## [9.0.1] - 23-Jan-2026
### Fixed
- Fixed an issue where signatures created with the Signature tool in Wasm mode on Windows Chromium-based browsers (such as Chrome, Edge, and Brave) were saved as a "DRAFT" stamp instead of the drawn signature. (DOC-7288)
- Fixed an issue where the base URL (webSocketUrl setting) for SignalR requests could not be changed in the ASP.NET SignalR version (ASP.NET Core was not affected). (DOC-6916)
## [9.0.0] - 05-Dec-2025
### Added
- Added HighlightManager API, providing programmatic control over text and custom highlights. (DOC-7151)
### Fixed
- Improved thumbnail image quality in the PDF Organizer dialog. (DOC-7019)
- Fixed a "Worker was terminated" console error when switching between PDF files. (DOC-7152)
- Fixed issues with stamp annotations when using certain transparent images. (DOC-7155)
- [Localization] [Regression] The "Show All" button in notifications was not localized when using the Japanese language. (DOC-7146)
### See `CHANGELOG.md` for previous release notes.
## Installation
### To install the latest release version:
```sh
npm install @mescius/dspdfviewer
```
### To install from the zip archive:
Go to https://developer.mescius.com/document-solutions/dot-net-pdf-api/download and follow the directions on that page to get your 30-day evaluation and deployment license key.
The license key will allow you to develop and deploy your application to a test server.
Unzip the viewer distribution files (list below) to an appropriate location accessible from the web page where the viewer will live.
Viewer zip includes the following files:
- `README.md`: this file
- `CHANGELOG.md`
- `THIRD_PARTY_LICENSES.txt`
- `dspdfviewer.js`
- `dspdfviewer.worker.js`
- `wasmSupportApi.js`
- `wasmSupportApiServer.js`
- `DsPdf.wasm`
- `package.json`
- `index.html`: example page
- `docs/`: documentation
- `examples/`: various usage examples list page
- `localization/`: resources for custom localization
- `resources/`: various resources
- `themes/`: theme files
- `typings/`: TypeScript declarations
## <a id="local-examples"></a>Documentation and examples
Online documentation is available [here](https://developer.mescius.com/document-solutions/dot-net-pdf-api/docs/online/pdfviewer.html).
For local documentation and some local usage examples, run `npx serve` and open link in your browser when the server is started.
## Licensing
Document Solutions PDF Viewer is a commercially licensed product. Please [visit this page](https://developer.mescius.com/document-solutions/licensing) for details.
## Getting more help
Document Solutions PDF Viewer is distributed as part of Document Solutions for PDF.
You can ask any questions about the viewer, or report bugs using the
[Document Solutions for PDF public forum](https://developer.mescius.com/forums/documents-pdf).
## More details on using the viewer
### Adding the viewer to an HTML page:
```HTML
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<!-- Limit content scaling to ensure that the viewer zooms correctly on mobile devices: -->
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no" />
<meta name="theme-color" content="#000000" />
<title>Document Solutions PDF Viewer</title>
<script type="text/javascript" src="lib/dspdfviewer.js"></script>
<script>
function loadPdfViewer(selector) {
var viewer = new DsPdfViewer(selector,
{
/* Specify options here */
renderInteractiveForms: true
});
// Skip the 'report list' panel:
// viewer.addReportListPanel();
viewer.addDefaultPanels();
// Optionally, open a PDF (will only work if this runs from a server):
viewer.open('HelloWorld.pdf');
// Change default viewer toolbar:
viewer.toolbarLayout.viewer.default = ['$navigation', '$split', 'text-selection', 'pan', '$zoom', '$fullscreen',
'save', 'print', 'rotate', 'view-mode', 'doc-title'];
viewer.applyToolbarLayout();
}
</script>
</head>
<body onload="loadPdfViewer('#root')">
<div id="root"></div>
</body>
</html>
```
### How to license the viewer:
Set the DsPdfViewer Deployment key to the DsPdfViewer.License property before you create and initialize DsPdfViewer.
This must precede the code that references the js files.
```javascript
// Add your license
DsPdfViewer.LicenseKey = 'xxx';
// Add your code
const viewer = new DsPdfViewer("#viewer1", { file: 'helloworld.pdf' });
viewer.addDefaultPanels();
```
### <a id="support_api"></a>Support API
_Support API_ is our PDF processing engine that enables the PDF editing features of DsPdfViewer.
Two options are available when configuring the viewer with _Support API_:
- **Server-based Support API**: requires [DS.Documents.Pdf.ViewerSupportApi](https://www.nuget.org/packages/DS.Documents.Pdf.ViewerSupportApi/)
NuGet package which needs to run on a .NET server. The viewer connects to it via the
[supportApi](https://developer.mescius.com/document-solutions/javascript-pdf-viewer/api/classes/DsPdfViewer.html#supportApi) property
and uses that connection to perform any edits.
To set up a Support API server on your system and see it in action,
download any of the samples from the [DsPdfViewer demo site](https://developer.mescius.com/document-solutions/javascript-pdf-viewer/demos/)
(e.g. [Edit PDF](https://developer.mescius.com/document-solutions/javascript-pdf-viewer/demos/edit-pdf/purejs)),
and follow the instructions in the `readme.md` included in the downloaded zip.
The full C# source code of [ViewerSupportApi](https://www.nuget.org/packages/DS.Documents.Pdf.ViewerSupportApi/)
together with demo projects for .NET 8 and Web Forms is included in the `src/` folder
inside the NuGet package (the **WEB_FORMS** constant is defined for the Web Forms target).
In your server solution you can either reference the package, or include the source project and reference it instead.
- **Client-based Support API**: uses the `DsPdf.wasm` WebAssembly binary that runs in the client browser.
This configuration does not require a server connection, all editing is done on the client.
You also do not need to download any additional components as the Wasm binaries are included in this package.
To try the Wasm option, you can [run the web server locally](#local-examples), click "More examples" and look for "Client Support API".
Due to its client-based nature, collaboration features are not available in the Wasm configuration.
Also, in this release (v7.2) the following features are not yet supported, and will be disabled
in the viewer UI if the Wasm configuration is used:
- Adding/applying redacts
- Electronic signatures
- Export to raster or SVG images
- Converting annotations to content
If you are using IIS, you will need to explicitly allow IIS to load .wasm files in your `web.config` in order to use `DsPdf.wasm`:
```XML
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<system.webServer>
<staticContent>
<remove fileExtension=".wasm" />
<mimeMap fileExtension=".wasm" mimeType="application/wasm" />
</staticContent>
<httpCompression>
<dynamicTypes>
<add mimeType="application/wasm" enabled="true" />
</dynamicTypes>
</httpCompression>
</system.webServer>
</configuration>
```
#### Note that you need a Document Solutions for PDF Professional license in order to use _Support API_ in your apps.
### Keyboard shortcuts
#### Viewer mode
- ```Ctrl +``` - zoom in
- ```Ctrl -``` - zoom out
- ```Ctrl 0``` - zoom to 100%
- ```Ctrl 9``` - zoom to window
- ```Ctrl A``` - select all
- ```R``` - rotate clockwise
- ```Shift R``` - rotate counterclockwise
- ```H``` - enable pan tool
- ```S``` - enable selection tool
- ```V``` - enable selection tool
- ```Ctrl O``` - open local PDF
- ```Ctrl F``` - text search
- ```Ctrl P``` - print
- ```Home``` - go to start of line
- ```Ctrl Home``` - go to start of document
- ```Shift Home``` - select to start of line
- ```Shift Ctrl Home``` - select to start of document
- ```End``` - go to end of line
- ```Ctrl End``` - go to end of document
- ```Shift End``` - select to end of line
- ```Shift Ctrl End``` - select to end of document
- ```Left``` - go left
- ```Shift Left``` - select left
- ```Alt Left``` - go back in history
- ```Right``` - go right
- ```Shift Right``` - select right
- ```Alt Right``` - go forward in history
- ```Up``` - go up
- ```Shift Up``` - select up
- ```Down``` - go down
- ```Shift Down``` - select down
- ```PgUp``` - page up
- ```PgDown``` - page down
- ```Shift PgUp``` - select page up
- ```Shift PgDown``` - select page down
#### Editing modes
- ```Delete``` - delete selected annotation/field
- ```Esc``` - unselect annotation/field
- ```Ctrl Z``` - undo
- ```Ctrl Y``` - redo
- ```Ctrl Shift Z``` - redo
### Toolbar items
The default viewer toolbar items layout (items starting with '$' are inherited from the base viewer, other items are PDF viewer specific.):
```
['open', '$navigation', '$split', 'text-selection', 'pan', '$zoom', '$fullscreen', 'rotate', 'view-mode', 'theme-change', 'download', 'print', 'save', 'hide-annotations', 'doc-title', 'doc-properties', 'about']
```
The full list of the PDF-viewer specific toolbar items:
```
'text-selection', 'pan', 'open', 'save', 'download', 'print', 'rotate', 'theme-change', 'doc-title', 'view-mode', 'single-page', 'continuous-view'
```
The full list of base viewer toolbar items:
```
'$navigation' '$refresh', '$history', '$mousemode', '$zoom', '$fullscreen', '$split'
```
You can get default base viewer items by using the getDefaultToolbarItems() method, e.g.:
```javascript
const toolbar: Toolbar = viewer.toolbar;
let buttons = toolbar.getDefaultToolbarItems();
buttons = buttons.filter(b => b !== '$refresh');
```
To specify a custom set of toolbar items, use the toolbarLayout property and applyToolbarLayout() method, e.g.:
```javascript
viewer.toolbarLayout.viewer = {
default: ["$navigation", 'open', '$split', 'doc-title'],
fullscreen: ['$fullscreen', '$navigation'],
mobile: ["$navigation", 'doc-title']
};
viewer.toolbarLayout.annotationEditor = {
default: ['edit-select', 'save', '$split', 'edit-text'],
fullscreen: ['$fullscreen', 'edit-select', 'save', '$split', 'edit-text'],
mobile: ['$navigation']
};
viewer.toolbarLayout.formEditor = {
default: ['edit-select-field', 'save', '$split', 'edit-widget-tx-field', 'edit-widget-tx-password'],
fullscreen: ['$fullscreen', 'edit-select-field', 'save', '$split', 'edit-widget-tx-field', 'edit-widget-tx-password'],
mobile: ['$navigation']
};
viewer.applyToolbarLayout();
```
Here is an example of how to create your own custom toolbar button:
```javascript
const toolbar: Toolbar = viewer.toolbar;
toolbar.addItem({
key: 'my-custom-button',
iconCssClass: 'mdi mdi-bike',
title: 'Custom button',
enabled: false,
action: () => {
alert("Custom toolbar button clicked");
},
onUpdate: (args) => ({ enabled: viewer.hasDocument }),
});
viewer.toolbarLayout.viewer.default = ['$navigation', 'my-custom-button'];
viewer.applyToolbarLayout();
```
### Using the viewer in frameworks such as React, Preact, Angular etc.
Add a reference to the viewer script:
```HTML
<body>
<script type="text/javascript" src="/lib/dspdfviewer/dspdfviewer.js"></script>
...
```
Add the placeholder to your App template, e.g.:
```HTML
<section id="pdf"></section>
```
Render the viewer:
```javascript
let viewer = new DsPdfViewer('section#pdf');
viewer.addDefaultPanels();
```
---
# <a id="japanese"></a>DioDocs PDFビューワ
[DioDocs PDFビューワ](https://developer.mescius.jp/diodocs-pdf/javascript-pdf-viewer)は、WebアプリケーションのクライアントサイドでPDFファイルを読み込んで表示する、JavaScriptベースのPDFビューワです。また、バックエンドのAPIを使って、PDFファイルを編集することもできます。
## サンプル
使い方については、下記をご参照ください。
- [デモ](https://demo.mescius.jp/diodocs/pdfviewer/demos/)
## インストール方法
```sh
npm install @mescius/dspdfviewer
```
日本語版での動作保証は、[日本語版サイト](https://docs.mescius.jp/help/diodocs/pdf/#ReleaseNotes_GcPDFVIewer.html)で公開しているバージョンのみとなります。
## ドキュメント
ドキュメントについては、下記をご参照ください。
- [ヘルプ](https://docs.mescius.jp/help/diodocs/pdf/#grapecitydocumentspdfviewer.html)
- [APIリファレンス](https://docs.mescius.jp/help/diodocs/pdfviewer/)
## 製品情報
価格、ライセンスについては、下記をご参照ください。
- [製品情報](https://developer.mescius.jp/diodocs-pdf/javascript-pdf-viewer)
## サポート
ナレッジベース、テクニカルサポートについては、下記をご参照ください。
- [サポート＆サービス](https://developer.mescius.jp/support)
- [サブスクリプションサービス利用規約](https://docs.mescius.jp/license/diodocs/diodocs-subscriptionservice.pdf)
---
_The End._