# # ViewerUI

Viewer UI 定义了一系列方法，用于创建和显示用户界面组件。这些方法可以被 PDFViewCtrl 和 UIExtension 调用。通过使用 Viewer UI，我们可以定制一些自定义的 UI 元素，如右键菜单、alert 弹框提示、loading 加载遮罩层等。

Viewer UI 的接口声明可以参考 API Reference
(opens new window)。在 SDK 中，有两套可用的内置 Viewer UI：PDFViewCtrl 的 TinyViewerUI
(opens new window) 和 UIExtension 的 XViewerUI
(opens new window)。

在实际应用中，我们可以根据自己的需求选择是否使用 PDFViewCtrl 或 UIExtension，从而选择使用这两个内置的 Viewer UI。

## # IViewer 定义的方法列表

1. `createContextMenu(key, anchor, config)`: 创建上下文菜单组件并注册右键单击事件。可以重写此方法来自定义右键菜单。参数说明如下：

   - key: 任意类型，表示上下文菜单实例的所有者，可以是 StateHandler
     (opens new window) 的名称或 `AnnotComponent` 的实例。
   - anchor: HTMLElement，用于响应右键单击事件的 HTML 元素。
   - config: 对象，配置项。
     - config.selector: 字符串，触发此菜单的元素的 CSS 选择器，该元素应为 anchor 或其子元素。
     - config.items: 数组，包含默认菜单项的配置。参考 JQuery contextmenu plugin documentation
       (opens new window) 插件文档。
     - config.items[].nameI18nKey: 字符串，菜单项的国际化文本键。

   返回值: `IContextMenu|undefined`
   (opens new window)，上下文菜单组件，包括显示/隐藏和销毁API。返回 `undefined` 表示不显示指定目标的右键菜单。

2. `alert(message)`: 显示带有可选内容和确定按钮的警告对话框，然后在对话框关闭后返回已完成的 Promise。

   - message: 字符串，警告对话框的消息，使用 i18next.js 的词条格式。

   返回值: `Promise<void>`

3. `confirm(message)`: 显示带有可选消息和两个按钮（确定和取消）的模态对话框，然后返回一个 Promise。如果用户点击确定，Promise 将被完成；如果用户点击取消，Promise 将被拒绝。

   - message: 字符串，确认对话框的消息，使用 i18next.js 的词条格式。

   返回值: `Promise<void>`

4. `prompt(defaultValue, message, title)`: 显示带有可选消息的对话框，提示用户输入一些文本。

   - defaultValue: 字符串，文本输入框中显示的默认值。
   - message: 字符串，要显示给用户的文本。
   - title: 字符串，对话框的标题。

   返回值: `Promise<string>`, 返回一个 Promise，在输入框中填入的值被完成。

5. `promptPassword(defaultValue, message, title)`: 显示带有可选消息的对话框，提示用户输入密码。

   - defaultValue: 字符串，密码输入框中显示的默认密码。
   - message: 字符串，要显示给用户的文本。
   - title: 字符串，对话框的标题。

   返回值: `Promise<string>`, 返回一个 Promise，在密码输入框中填入的值被完成。

6. `loading(coverOn)`: 显示一个加载层，表示页面或组件的加载状态。

   - coverOn: HTMLElement, 目标层。

   返回值: `Function`, 一个用于关闭加载层的函数。

7. `createTextSelectionTooltip(pageRender)`: 创建一个工具提示组件，当用户选择文本时显示。

   - pageRender: PDFPageRender.

   返回值: `IFloatingTooltip`
   (opens new window).

8. `getSignatureUI()`: 获取签名组件，可以重写此方法来自定义签名属性对话框。

   返回值：`Promise<ISignatureUI>`, 返回一个Promise，包含可自定义的签名组件

## # 应用方法

通常，我们可能只需要重写 Viewer UI 中的部分方法，比如重写 alert 对话框。在这种情况下，我们可以通过继承 SDK 内置的 Viewer UI 来实现：

    class CustomViewerUI extends UIExtension.XViewerUI {
        alert(message) {
            // 这里显示自定义的 alert 对话框，并在控制台打印内容
            console.log('alert:', message);
            return Promise.resolve();
        }
    }

    new PDFUI({
     viewerOptions: {
         viewerUI: new CustomViewerUI()
     }
    })

在 PDFViewCtrl 层实现自定义 Viewer UI ， 方法是相同的：

    class CustomViewerUI extends PDFViewCtrl.viewerui.TinyViewerUI {
        alert(message) {
            // 这里显示自定义的 alert 对话框，并在控制台打印内容
            console.log('alert:', message);
            return Promise.resolve();
        }
    }
    new PDFViewer({
        viewerUI: new CustomViewerUI()
    })

有关更多例子，可以参考以下两个文档中的内容：

1. Annot contextmenu customization
2. Page contextmenu customization
3. Signature Dialog Customization