自定义快捷键

概述

为了方便应用层自定义快捷键，FoxitWebSDKForWeb 提供了 PDFViewer.onShortcutKey 等接口,向应用层开放自定义快捷键的能力。本文将介绍相关接口的用法以及注意事项。

名词定义

在开始前，为了避免混淆，这里我们定义了下列名词在这篇文档中的语义：

1. 组合键：表示特定的一组按键组合，比如 Ctrl+Z 是一个组合键，Cmd+Z 是另一个组合键
2. 快捷键：表示能够触发某个功能的一组组合键，比如撤销功能的快捷键是 Ctrl+Z 和 Cmd+Z。

内置的组合键及描述

这里我们列出目前 WebSDK 中内置的组合键，开发者可以参考这张表格，在应用层替换内置的快捷键实现。

组合键	描述
Esc	关闭对话框，退出编辑模式或退出搜索面板。
Home	跳转到第一页。
End	跳转到最后一页。
Delete	删除选定的对象。编辑模式下：删除选定的文本对象；非编辑模式下：删除选定的注释对象。
PageUp	当存在垂直滚动条时, 将当前视图向上移动。
PageDown	当存在垂直滚动条时, 将当前视图向下移动。
UpArrow	当存在垂直滚动条时, 将滚动条向上移动。
DownArrow	当存在垂直滚动条时, 将滚动条向下移动。
LeftArrow	当存在水平滚动条时, 将滚动条向左移动。
RightArrow	当存在水平滚动条时, 将滚动条向右移动。
Enter	确认或继续。
Ctrl+Z	撤销。Mac平台为Cmd+Z。
Ctrl+Y	重做。Mac平台为Cmd+Shift+Z。
Ctrl+MouseLeft	选择多个对象、注释、路径、文本编辑。
Ctrl+F	打开搜索面板。Mac平台为Cmd+F。
Ctrl+P	打开打印面板。Mac平台为Cmd+P。
Ctrl+RightArrow	打开左侧导航面板。Mac平台为Cmd+RightArrow。
Ctrl+LeftArrow	关闭左侧导航面板。Mac平台为Cmd+LeftArrow。
Ctrl+C	复制注释（路径、文本编辑、图像）。Mac平台为Cmd+C。
Ctrl+X	剪切注释（文本）。Mac平台为Cmd+X。
Ctrl+V	粘贴注释（路径、文本编辑、图像）。Mac平台为Cmd+V。

开始自定义

开发者可以通过 PDFViewer.onShortcutKey 接口添加快捷键事件处理函数。如果接收到的快捷键是SDK内部已有的快捷键（参考上述表格），设置 preventDefaultImplementation 参数为 true 将会替换SDK内部快捷键的实现。否则，在快捷键触发后，SDK内部实现和开发者自定义的处理函数将同时执行。

替换内置快捷键实现

这里我们以打印功能快捷键为例：

<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"
    }
}

上面示例替换了SDK内置实现，用户按下Ctrl+P组合键后，将会触发自定义的打印实现，您可以在该实现中获取到print-dialog显示打印对话框，或者使用其他方法实现自定义的打印功能。

替换组合键

如果您不想使用 Ctrl+P 触发打印功能，则需要替换 SDK 内置的实现，并注册自定义的快捷键实现打印功能。以下是示例代码：

<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() {
        pdfui.print({
            pages: [0]
        });
    })
</script>

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

在上述示例中，我们首先通过 PDFViewer.onShortcutKey 注册一个空函数，以替换SDK内置的 Ctrl+P 实现。然后，我们再注册一个Ctrl+Alt+P的事件监听器，当用户按下 Ctrl+Alt+P 时，我们会调用 pdfui.print() 方法实现打印功能。

需要注意的是，替换内置快捷键实现时，onShortcutKey 接口第三个参数要指定为 true，这样自定义实现将会替换SDK内置的默认实现，而不是与其并存。

删除快捷键监听事件

在某些情况下，您可能需要在特定条件下删除快捷键监听事件。例如，在文档打开时，您可以监听 Ctrl+W 事件以关闭文档。但在文档关闭后，您需要取消 Ctrl+W 事件的监听，以避免不必要的操作。为此，PDFViewer.onShortcutKey 接口会返回一个函数，您可以使用该函数来删除快捷键事件的监听。以下是一个示例：

<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"
    }
}

在上述示例中，我们首先在openFileSuccess事件回调中使用 PDFViewer.onShortcutKey 监听了 Ctrl+Shift+K 事件，并将返回的函数保存到变量 removeShortcutKeyHandler 中。将要关闭文档时，我们可以调用 removeShortcutKeyHandler 函数来删除对 Ctrl+Shift+K 事件的监听。

需要注意的是，如果您使用了多个 PDFViewer.onShortcutKey 监听事件，那么每个事件都会返回一个相应的函数，您需要保存每个函数并在需要的时候分别调用。

禁用/启用全局快捷键

在某些情况下，您可能需要警用快捷键功能，那么可以通过 setEnableShortcutKey 接口来实现。该接口接受一个布尔值参数，如果为 true，则启用快捷键功能；如果为 false 则禁用快捷键功能。

<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"
    }
}

上述示例禁用了快捷键功能，这时候所有的组合键都将不会被触发，这时候调用 pdfui.setEnableShortcutKey(true) 就可以实现重新启用快捷键。

注意事项

为了更符合 Mac 用户习惯，我们在 Mac 平台上使用了不同的组合鍵，通常会用 Cmd 代替 Ctrl 键， 以“撤销”功能为例，Windows/Linux 下面的组合键是 Ctrl+Z, 而在 Mac 中则变为 Cmd+Z。 如果要替换“撤销”功能的快捷键，则需要根据不同的系统类型来选择这两个组合键中的一个以监听快捷键事件。