Customize keyboard shortcuts

Overview

Foxit PDF SDK for Web provides interfaces such as PDFViewer.onShortcutKey so applications can customize keyboard shortcuts easily. This document explains how to use these APIs and related notes.

Terminology

To avoid confusion, the following terms are used consistently in this document:

1. Key combination: A specific key press combination, for example Ctrl+Z or Cmd+Z.

2. Shortcut: A key combination that triggers a specific action—for example, undo is bound to Ctrl+Z or Cmd+Z.

Built-in key combinations

The table below lists built-in key combinations in Foxit PDF SDK for Web. You can replace the built-in behavior at the application layer using these as a reference.

Key combination	Description
Esc	Close dialogs, exit edit mode, or exit the search panel.
Home	Go to the first page.
End	Go to the last page.
Delete	Delete the selected object. In edit mode: delete the selected text object; otherwise: delete the selected annotation.
PageUp	When a vertical scrollbar is present, move the current view up.
PageDown	When a vertical scrollbar is present, move the current view down.
UpArrow	When a vertical scrollbar is present, scroll up.
DownArrow	When a vertical scrollbar is present, scroll down.
LeftArrow	When a horizontal scrollbar is present, scroll left.
RightArrow	When a horizontal scrollbar is present, scroll right.
Enter	Confirm or continue.
Ctrl+Z	Undo. On Mac: Cmd+Z.
Ctrl+Y	Redo. On Mac: Cmd+Shift+Z.
Ctrl+F	Open the search panel. On Mac: Cmd+F.
Ctrl+P	Open the print panel. On Mac: Cmd+P.
Ctrl+RightArrow	Open the left navigation panel. On Mac: Cmd+RightArrow.
Ctrl+LeftArrow	Close the left navigation panel. On Mac: Cmd+LeftArrow.
Ctrl+C	Copy annotations (path, text edit, image). On Mac: Cmd+C.
Ctrl+X	Cut annotations (text). On Mac: Cmd+X.
Ctrl+V	Paste annotations (path, text edit, image). On Mac: Cmd+V.

Get started

Use the PDFViewer.onShortcutKey API to register shortcut handlers. If the shortcut is already defined in the SDK (see the table above), set preventDefaultImplementation to true to replace the built-in behavior. Otherwise, both the SDK handler and your custom handler run when the shortcut is triggered.

Replace a built-in shortcut

The print shortcut is used as an example:

<script>
    const libPath = window.top.location.origin + '/lib';
    const FRAGMENT_ACTION = UIExtension.UIConsts.FRAGMENT_ACTION;
    const pdfui = new UIExtension.PDFUI({
        viewerOptions: {
            libPath: libPath,
            jr: {
                licenseSN: licenseSN,
                licenseKey: licenseKey
            }
        },
        renderTo: document.body,
        appearance: UIExtension.appearances.adaptive,
        addons: libPath + '/uix-addons/allInOne.js'
    });
    pdfui.onShortcutKey("Ctrl+P", function () {
        pdfui.getComponentByName('print-dialog').then(printDialog => {
            if (printDialog) {
                printDialog.show();
            }
        })
    });
</script>

{
  "iframeOptions": {
    "style": "height: 500px"
  }
}

In this example, the built-in shortcut implementation is replaced. When the user presses Ctrl+P, the custom print handler runs. You can obtain print-dialog to show the print dialog, or implement printing another way.

Change the key combination

To use a key combination other than Ctrl+P for print, disable the built-in handler and register your own shortcut:

<script>
    const libPath = window.top.location.origin + '/lib';
    const FRAGMENT_ACTION = UIExtension.UIConsts.FRAGMENT_ACTION;
    const pdfui = new UIExtension.PDFUI({
        viewerOptions: {
            libPath: libPath,
            jr: {
                licenseSN: licenseSN,
                licenseKey: licenseKey
            }
        },
        renderTo: document.body,
        appearance: UIExtension.appearances.adaptive,
        addons: libPath + '/uix-addons/allInOne.js'
    });
    pdfui.onShortcutKey('Ctrl+P', function () {
        // PASS
    }, true);
    pdfui.onShortcutKey('Ctrl+Alt+P', function (e) {
        pdfui.print({
            pages: [0]
        });
    })
</script>

{
  "iframeOptions": {
    "style": "height: 500px"
  }
}

First, register an empty handler with PDFViewer.onShortcutKey to replace the built-in Ctrl+P behavior. Then register Ctrl+Alt+P; when the user presses it, pdfui.print() runs.

When replacing a built-in shortcut, set the third parameter of onShortcutKey to true so your handler replaces the default instead of running alongside it.

Remove a shortcut listener

You may need to remove a shortcut listener under certain conditions. For example, listen for Ctrl+W to close a document when it is open, then remove that listener after the document closes. PDFViewer.onShortcutKey returns a function you can call to unregister the handler:

<script>
    const libPath = window.top.location.origin + '/lib';
    const FRAGMENT_ACTION = UIExtension.UIConsts.FRAGMENT_ACTION;
    const pdfui = new UIExtension.PDFUI({
        viewerOptions: {
            libPath: libPath,
            jr: {
                licenseSN: licenseSN,
                licenseKey: licenseKey
            }
        },
        renderTo: document.body,
        appearance: UIExtension.appearances.adaptive,
        addons: libPath + '/uix-addons/allInOne.js'
    });
    var removeShortcutKeyHandler = () => {
    };
    pdfui.addViewerEventListener(UIExtension.PDFViewCtrl.ViewerEvents.openFileSuccess, () => {
        removeShortcutKeyHandler();
        pdfui.onShortcutKey('Ctrl+Shift+K', function (e) {
            e.preventDefault();/ 阻止浏览器原生的默认实现
            pdfui.close(); / 用户关闭文档
        }).then((remove) => {
            removeShortcutKeyHandler = remove;
        })
    });
    pdfui.addViewerEventListener(UIExtension.PDFViewCtrl.ViewerEvents.willCloseDocument, () => {
        removeShortcutKeyHandler();
    });
</script>

{
  "iframeOptions": {
    "style": "height: 500px"
  }
}

In the openFileSuccess callback, PDFViewer.onShortcutKey listens for Ctrl+Shift+K and stores the returned remover in removeShortcutKeyHandler. Call that function before closing the document to stop listening for Ctrl+Shift+K.

If you register multiple handlers with PDFViewer.onShortcutKey, each returns its own remover—save and call them separately as needed.

Enable or disable global shortcuts

Use setEnableShortcutKey to enable or disable all shortcuts globally. Pass true to enable or false to disable.

<script>
    const libPath = window.top.location.origin + '/lib';
    const FRAGMENT_ACTION = UIExtension.UIConsts.FRAGMENT_ACTION;
    const pdfui = new UIExtension.PDFUI({
        viewerOptions: {
            libPath: libPath,
            jr: {
                licenseSN: licenseSN,
                licenseKey: licenseKey
            }
        },
        renderTo: document.body,
        appearance: UIExtension.appearances.adaptive,
        addons: libPath + '/uix-addons/allInOne.js'
    });
    pdfui.setEnableShortcutKey(false);
</script>

{
  "iframeOptions": {
    "style": "height: 500px"
  }
}

This disables all shortcuts. Call pdfui.setEnableShortcutKey(true) to re-enable them.

Notes

On Mac, common shortcuts use Cmd instead of Ctrl—for example, undo is Ctrl+Z on Windows/Linux and Cmd+Z on Mac.

When replacing the undo shortcut, register the appropriate combination for the target platform.