README
GrapeCity Documents PDF Viewer
日本語
A full-featured JavaScript PDF viewer and editor that comes with GrapeCity Documents for PDF.
GrapeCity Documents PDF Viewer (GcDocs PDF Viewer, GcPdfViewer) 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. GcPdfViewer is included in GrapeCity Documents for PDF (GcPdf) - a feature-rich cross-platform PDF API library for .NET Core.
Support API is a server-side ASP.NET Core library that ships as C# source code, and allows you to easily set up a server that uses GcPdf to provide PDF modification features to GcPdfViewer. When connected to Support API, GcPdfViewer can be used as a PDF editor to save filled PDF forms, remove sensitive content, edit annotations and forms, and more.
See docs/index.html for GcPdfViewer client API documentation.
Product highlights:
- Works in all modern browsers, including IE11, Edge, Chrome, FireFox, Opera, Safari
- When connected to GcPdf on the server via Support API, provides:
- Customizable and mobile-friendly form filler
- Real-time collaboration mode
- Annotation and form editors
- Quick edits using secondary toolbars
- PDF redaction
- Signature verification
- 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
- Fully supports file attachments (both attachment annotations and document level attachments)
- Comes with several themes, new custom themes can be added
- Supports external CMaps
- ...and more.
[3.0.19] - 25-Jan-2022
Added
- Added the ability to specify authentication or other HTTP headers in the open() method. (DOC-3998)
// Example: specify basic access authentication and custom headers:
viewer.open("http://example.com//pdfs/GetPdf?file=HelloWorld.pdf", {
headers: {
"Authorization": "Basic " + btoa(unescape(encodeURIComponent("USERNAME:PASSWORD"))),
"CustomHeader": "Custom header value"
}
});
- Added the ability to specify authentication or other HTTP headers in SupportApi requests. (DOC-3998)
// Example: specify basic access authentication and custom headers:
const viewer = new GcPdfViewer("#viewer", {
supportApi: {
apiUrl: "192.168.0.1/support-api",
requestInit: {
headers: {
"Authorization": "Basic " + btoa(unescape(encodeURIComponent("USERNAME:PASSWORD"))),
"CustomHeader": "Custom header value"
}
}
}
});
Fixed
- [Editor] Text added in the free text annotation editor disappears on resizing the annotation. (DOC-3988)
[3.0.18] - 24-Jan-2022
Fixed
- Undo history should be cleared by the close() method. (DOC-3989)
[3.0.17] - 21-Jan-2022
Added
- [Form Editor] "Editable" property added to combo boxes. (DOC-3947)
- [Form Editor] New values added to "Tab order" property: "Annotations" and "Widgets". (DOC-3668)
- Added ability to close the current document. (DOC-3981)
// Usage example:
await viewer.close();
Fixed
- Incorrect tab cycle for an editable combo box. (DOC-3967)
- Tab order differs from Adobe Acrobat Reader in some cases. (DOC-3668)
- [Form Editor] Cannot reset the "Tab order" property to "Not specified". (DOC-3968)
- [Editor] The Backspace key does not work in the free text annotation editor. (DOC-3983)
- [Editor] If a new page is inserted and the document is saved, the tab order of following pages is incorrect. (DOC-3985)
[3.0.13] - 22-Dec-2021
Added
- Added support for editable combo boxes. (DOC-3947)
- [XFA forms] Added the ability to select/copy text content. (DOC-3917)
- [Editor] Remember last used editor values. (DOC-3925)
New settings added to the "editorDefaults" option: "rememberLastValues" and "lastValueKeys". If "rememberLastValues" is set to true or undefined, the last used property values will be used as default values for new annotations. "lastValueKeys" specifies which properties will be remembered.
// The default value of lastValueKeys:
["appearanceColor", "borderStyle", "color", "interiorColor", "backgroundColor", "borderColor", "opacity", "textAlignment", "printableFlag", "open",
"lineStart", "lineEnd", "markBorderColor", "markFillColor", "overlayFillColor", "overlayText", "overlayTextJustification", "newWindow", "calloutLineEnd", "fontSize",
"fontName", "name", "readOnly", "required"]
// Example: turn remembering last used values off:
var viewer = new GcPdfViewer("#root", { editorDefaults: { rememberLastValues: false } });
// Example: remember only the borderStyle property:
var viewer = new GcPdfViewer("#root", { editorDefaults: { rememberLastValues: true, lastValueKeys: ["borderStyle"] } });
- [Android] Added support for zooming using pinch gesture. (DOC-3424, ARD-2508)
Changed
- Japanese localization strings updated.
Fixed
- [iPad] PDF will not render after max zooming when iPad is running in Desktop mode. (DOC-3765)
- [iOS][Android] The main toolbar collapses when the secondary toolbar is clicked. (DOC-3843)
- [Editor] Method showSecondToolbar does not activate editor mode correctly. (DOC-3892)
- [Editor] Incorrect undo / redo behavior when editing ink annotations. (DOC-3924)
- Incorrect zoom controls behavior. (DOC-3929)
[3.0.10] - 25-Nov-2021
Changed
- Breaking change: All public APIs that used page numbers now use zero-based page indices. (DOC-3536)
- PDF.js library was updated from v2.0.943 to v2.10.377, see PDF.js Release Notes.
- Method goToPageNumber deprecated, use goToPage method or pageIndex property instead. (DOC-3536)
- By default, radio buttons and checkboxes now do not use predefined appearances from the PDF. Use the fieldsAppearance option to revert to the old behavior:
var viewer = new GcPdfViewer("#root", { fieldsAppearance: { radioButton: "Predefined", checkBoxButton: "Predefined" } });
- [SupportApi client] The ping() method has been deprecated and is no longer used; instead, the serverVersion() method is used.
- Properties SubmitForm/ResetForm renamed to submitForm/resetForm. (DOC-3379)
Added
- Added ability to edit document without switching to Annotation Editor or Form Editor modes. (DOC-3169)
- Added support for second horizontal toolbar.
- Added secondary editing toolbars to the main viewer toolbar: "Text tools", "Draw tools", "Attachments and stamps", "Form tools", "Page tools".
Use secondToolbarLayout to control which toolbars are enabled.// Example: specify custom second toolbar layout: viewer.secondToolbarLayout = { "text-tools": ['edit-text', 'edit-free-text'] }; - Added API to display a custom second toolbar. (DOC-3170)
// Example: create custom second toolbar with key "custom-toolbar-key": var React = viewer.getType("React"); var toolbarControls = [React.createElement("label", null, "Custom toolbar"), React.createElement("button", { onClick: () => { alert("Execute action."); }, title: "Action title" }, "Action")]; // Register custom second toolbar for key "custom-toolbar-key": viewer.options.secondToolbar = { render: function(toolbarKey) { if(toolbarKey === "custom-toolbar-key") return toolbarControls; return null; } }; // Show custom second toolbar: viewer.showSecondToolbar("custom-toolbar-key"); - Added Light and Dark themes. (DOC-3169)
- Support page content accessibility for tagged PDFs containing logical structure information for screen readers.
- Added ability to show the structure tree of tagged PDFs. (DOC-3131)
// Use addStructureTreePanel method to add the appropriate panel: const viewer = new GcPdfViewer(selector); viewer.addStructureTreePanel(); await viewer.open("sample.pdf");// Use structureTree to access available structure tree data: const viewer = new GcPdfViewer(selector); await viewer.open("sample.pdf"); const structureTree = await viewer.structureTree; if(structureTree) { console.log(structureTree); } - Added goToPage method: navigate to the page with a specified 0-based index.
// Example: go to the first page: viewer.goToPage(0); - Added option maxCanvasPixels: maximum supported canvas size in pixels, i.e. width * height. Undefined or -1 means no limit. If the canvas scaling exceeds maxCanvasPixels, the CSS scaling is used instead of re-rendering the page to the canvas. (DOC-3765)
- Added the ability to use GET method to submit a form.
// Using GcPdf to create an ActionSubmitForm to submit a form using the GET method: var actionSubmit = new ActionSubmitForm("/"); actionSubmit.SubmitFormat = ActionSubmitForm.SubmitFormatType.HtmlForm; actionSubmit.HtmlFormFormat = ActionSubmitForm.HtmlFormFormatFlags.GetMethod; var btnSubmit = new PushButtonField(); btnSubmit.Widget.Rect = new RectangleF(50, 100, 100, 50); btnSubmit.Widget.ButtonAppearance.Caption = "Submit"; btnSubmit.Widget.Page = page; btnSubmit.Widget.Events.Activate = actionSubmit; - Action reset: added support for FieldNames, ExcludeSpecifiedFields and Next properties. (DOC-3379)
- Added new option fieldsAppearance - specifies how form fields are rendered. (DOC-3537)
Use this option to customize rendering of form fields. Available appearance rendering types:- "Custom" - Default. The custom appearance has some improvements over the web appearance, for example you can specify background and border colors.
- "Web" - Standard form field appearance using native platform styling. See https://developer.mozilla.org/en-US/docs/Web/CSS/appearance for details.
- "Predefined" - Predefined appearance stream from PDF when available. If the appearance stream is not available, custom appearance will be used.
// Example 1: Use platform-native styling for radio and checkbox buttons. var viewer = new GcPdfViewer("#root", { fieldsAppearance: { radioButton: "Web", checkBoxButton: "Web" } });// Example 2: Use predefined appearance stream for radio buttons: var viewer = new GcPdfViewer("#root", { fieldsAppearance: { radioButton: "Predefined" } }); - Added enableXfa option: render XFA (XML Forms Architecture) forms if any; the default is true. (DOC-3681)
// Example: turn XFA forms off: var viewer = new GcPdfViewer(selector, { enableXfa: false }); - Added requireTheme option. Use this option to apply a built-in CSS theme, this will inject the theme styles directly into the page head.
Note that only a known built-in theme can be specified, otherwise the viewer will fail to load.
Available built-in themes: "viewer", "dark", "dark-yellow", "gc-blue", "light", "light-blue".
This option takes precedence over the "theme" option which can be used to specify a custom theme.
// Example: var viewer = new GcPdfViewer(selector, { requireTheme: "light" }); - Added onThemeChanged event: raised when the user changes the viewer theme.
// Example: var viewer = new GcPdfViewer(selector, { requireTheme: localStorage.getItem('demo_theme') || 'viewer' }); viewer.addDefaultPanels(); viewer.onThemeChanged.register(function(args) { localStorage.setItem('demo_theme', args.theme); }); - Added onInitialized option: the onInitialized handler will be called immediately after the viewer is instantiated.
// Example: var viewer = new GcPdfViewer("#root", { onInitialized: (viewer)=> { // put viewer initialization code here. } });
Fixed
- Multiple bug fixes.
See CHANGELOG.md for detailed release notes.
See it in action
- GrapeCity Documents PDF Viewer demo site shows the various features of GcPdfViewer, including features that rely on Support API. On that site you can also modify the client side code and see the effect of the changes.
- All demos in GrapeCity Documents for PDF Sample Browser use GcPdfViewer to show sample PDFs.
Installation
To install the latest release version:
npm install @grapecity/gcpdfviewer
To install from the zip archive:
Go to https://www.grapecity.com/download/documents-pdf 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
- gcpdfviewer.js
- gcpdfviewer.worker.js
- package.json
- index.html (sample page)
- Theme files:
- themes/dark-yellow.css
- themes/dark-yellow.jscss
- themes/light-blue.css
- themes/light-blue.jscss
- themes/viewer.css
- themes/viewer.jscss
- Predefined CMap files for Chinese, Japanese, or Korean text output:
- resource/bcmaps/*.bin
- TypeScript declaration files:
- typings/.
Documentation
Online documentation is available here.
Licensing
GrapeCity Documents PDF Viewer is a commercially licensed product. Please visit this page for details.
Getting more help
GrapeCity Documents PDF Viewer is distributed as part of GrapeCity Documents for PDF. You can ask any questions about the viewer, or report bugs using the Documents for PDF public forum.
More details on using the viewer
Adding the viewer to an HTML page:
<!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>GrapeCity Documents PDF Viewer</title>
<script type="text/javascript" src="lib/gcpdfviewer.js"></script>
<script>
function loadPdfViewer(selector) {
var viewer = new GcPdfViewer(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 GcPdfViewer Deployment key to the GcPdfViewer.License property before you create and initialize GcPdfViewer. This must precede the code that references the js files.
// Add your license
GcPdfViewer.LicenseKey = 'xxx';
// Add your code
const viewer = new GcPdfViewer("#viewer1", { file: 'helloworld.pdf' });
viewer.addDefaultPanels();
Support API
Support API is a server-side library that ships as C# source code with GcPdf. The full source code is also included with all GcPdfViewer samples that can be downloaded from the GcPdfViewer demo site. The code can be built to use in an ASP.NET Core or a WebForms application (see #if WEB_FORMS in the sources). When GcPdfViewer is connected to Support API, its editing features are enabled. The edits done on the client are accumulated, and when the user clicks 'save', the document and the edits are sent to the server, the edits are applied, and the modified PDF is sent back to the client.
To set up a server that provides Support API in an ASP.NET Core app (ASP.NET Core 3.0 or later is required):
- Download any of the samples from the GcPdfViewer demo site (e.g. Edit PDF).
- Unpack the downloaded .zip into a directory.
- In that directory you will find a WebApi.zip file containing the full SupportApi C# sources (WebApi.zip/WebApi/SupportApi), plus an ASP.NET Core (WebApi.zip/WebApi/AspNetCore.sln) and a WebForms (WebApi.zip/WebApi/WebForms.sln) sample projects.
- Running the run.cmd batch file in the sample directory will unpack the SupportApi files, build and start the service, build and run the sample and open the sample URL (http://localhost:3003) in your default browser.
- The directory WebApi.zip/WebApi/SupportApi and everything inside it is the Support API library. It can be used as is in your own projects.
- WebApi.zip/WebApi/SupportApi/Controllers/GcPdfViewerController.cs contains the API entry points. Check it out to see what operations are available.
- For more details check out the readme.md that is included in all downloaded viewer samples.
NOTE that you will need a GrapeCity Documents for PDF Professional license to use Support API in your apps.
Keyboard shortcuts
Viewer mode
Ctrl +- zoom inCtrl -- zoom outCtrl 0- zoom to 100%Ctrl 9- zoom to windowCtrl A- select allR- rotate clockwiseShift R- rotate counterclockwiseH- enable pan toolS- enable selection toolV- enable selection toolCtrl O- open local PDFCtrl F- text searchCtrl P- printHome- go to start of lineCtrl Home- go to start of documentShift Home- select to start of lineShift Ctrl Home- select to start of documentEnd- go to end of lineCtrl End- go to end of documentShift End- select to end of lineShift Ctrl End- select to end of documentLeft- go leftShift Left- select leftAlt Left- go back in historyRight- go rightShift Right- select rightAlt Right- go forward in historyUp- go upShift Up- select upDown- go downShift Down- select downPgUp- page upPgDown- page downShift PgUp- select page upShift PgDown- select page down
Editing modes
Delete- delete selected annotation/fieldEsc- unselect annotation/fieldCtrl Z- undoCtrl Y- redoCtrl Shift Z- redo
Toolbar items
The default viewer toolbar items layout (items starting with '