对话框

本指南介绍如何处理 JavaScript、打开/保存文件、颜色选择、客户端证书以及其他对话框。

你可以使用本指南中介绍的 Fuzio API 以编程方式处理对话框。

对话框有多种类型。当需要显示某一类型的对话框时，会调用相应的回调。如果未注册该回调，对话框将被自动关闭，效果相当于用户在对话框中点击了 Cancel 按钮。

在实例化 BrowserView 时，会为指定的 Browser 实例配置每种对话框的默认回调实现。默认实现会使用对应 UI 工具包的能力来显示对话框。

JavaScript 对话框

Alert

当需要显示 JavaScript 的 alert 对话框时，会触发 AlertCallback 回调。这发生在调用 window.alert() JavaScript 函数时。

在该回调中，你可以获取对话框参数，例如标题、消息以及 “OK” 操作的本地化文本。当对话框关闭时，必须调用 tell.ok()。例如：

Java
Kotlin
browser.set(AlertCallback.class, (params, tell) -> {
    // 页面的 URL。
    var url = params.url();
    // 对话框标题。
    var title = params.title();
    // 对话框消息。
    var message = params.message();
    // "OK" 操作的本地化文本。
    var okActionText = params.okActionText();
    // 如有必要，创建并显示对话框。
    // 对话框已关闭。
    tell.ok();
});
browser.register(AlertCallback { params, tell ->
    // 页面的 URL。
    val url = params.url()
    // 对话框标题。
    val title = params.title()
    // 对话框消息。
    val message = params.message()
    // "OK" 回调操作的本地化文本。
    val okActionText = params.okActionText()
    // 如有必要，创建并显示对话框。
    // 对话框已关闭。
    tell.ok()
})

在 Alert 对话框关闭之前，JavaScript 的执行会被阻塞。

Confirm

当需要显示 JavaScript 的 confirm 对话框时，会触发 ConfirmCallback 回调。这发生在调用 window.confirm() JavaScript 函数时。

在该回调中，你可以获取对话框参数，例如标题、消息以及 “Yes” 和 “No” 操作的本地化文本。当对话框关闭时，必须调用 tell.ok() 或 tell.cancel()。例如：

Java
Kotlin
browser.set(ConfirmCallback.class, (params, tell) -> {
    // 页面的 URL。
    var url = params.url();
    // 对话框标题。
    var title = params.title();
    // 对话框消息。
    var message = params.message();
    // "OK" 操作的本地化文本。
    var okActionText = params.okActionText();
    // "Cancel" 操作的本地化文本。
    var cancelActionText = params.cancelActionText();
    // 已选择 "OK" 操作。
    tell.ok();
});
browser.register(ConfirmCallback { params, tell ->
    // 页面的 URL。
    val url = params.url()
    // 对话框标题。
    val title = params.title()
    // 对话框消息。
    val message = params.message()
    // "OK" 操作的本地化文本。
    val okActionText = params.okActionText()
    // "Cancel" 操作的本地化文本。
    val cancelActionText = params.cancelActionText()
    // 已选择 "OK" 操作。
    tell.ok()
})

在 Confirm 对话框关闭之前，JavaScript 的执行会被阻塞。

Prompt

当需要显示 JavaScript 的 prompt 对话框时，会触发 PromptCallback 回调。这发生在调用 window.prompt() JavaScript 函数时。

在该回调中，你可以获取对话框参数，例如标题、消息、文本，以及 “OK” 和 “Cancel” 操作的本地化文本。当对话框关闭时，必须调用 tell.ok(String) 或 tell.cancel()。例如：

Java
Kotlin
browser.set(PromptCallback.class, (params, tell) -> {
    // 页面的 URL。
    var url = params.url();
    // 对话框标题。
    var title = params.title();
    // 对话框消息。
    var message = params.message();
    // "OK" 操作的本地化文本。
    var okActionText = params.okActionText();
    // "Cancel" 操作的本地化文本。
    var cancelActionText = params.cancelActionText();
    // 已输入文本并选择了 "OK" 操作。
    tell.ok("Entered text");
});
browser.register(PromptCallback { params, tell ->
    // 页面的 URL。
    val url = params.url()
    // 对话框标题。
    val title = params.title()
    // 对话框消息。
    val message = params.message()
    // "OK" 操作的本地化文本。
    val okActionText = params.okActionText()
    // "Cancel" 操作的本地化文本。
    val cancelActionText = params.cancelActionText()
    // 已输入文本并选择了 "OK" 操作。
    tell.ok("Entered text")
})

在 Prompt 对话框关闭之前，JavaScript 的执行会被阻塞。

BeforeUnload

当网页即将被卸载时，会触发 onbeforeunload 事件。该事件允许你在确认对话框中显示一条消息，以告知用户是否要停留在当前页面或离开。

当需要显示该确认对话框时，会触发 BeforeUnloadCallback 回调。在该回调中，你可以获取对话框参数，例如标题、消息，以及 “Stay” 与 “Leave” 操作的本地化文本。当对话框关闭时，必须调用 tell.stay() 或 tell.leave()。例如：

Java
Kotlin
browser.set(BeforeUnloadCallback.class, (params, tell) -> {
    // 对话框标题。
    var title = params.title();
    // 对话框消息。
    var message = params.message();
    // "Stay" 操作的本地化文本。
    var stayActionText = params.stayActionText();
    // "Leave" 操作的本地化文本。
    var leaveActionText = params.leaveActionText();
    // true 表示页面正在重新加载，false 表示新导航。
    var isReload = params.isReload();
    // 已选择 "Stay" 操作。
    tell.stay();
});
browser.register(BeforeUnloadCallback { params, tell ->
    // 对话框标题。
    val title = params.title()
    // 对话框消息。
    val message = params.message()
    // "Stay" 操作的本地化文本。
    val stayActionText = params.stayActionText()
    // "Leave" 操作的本地化文本。
    val leaveActionText = params.leaveActionText()
    // true 表示页面正在重新加载，false 表示新导航。
    val isReload = params.isReload
    // 已选择 "Stay" 操作。
    tell.stay()
})

当通过 Browser.close() 关闭 Browser 实例时，此回调将不会被调用。

如果你希望在关闭 Browser 时也显示该对话框，请使用以下方式关闭 Browser：

Java
Kotlin
browser.close(CloseOptions.newBuilder().fireBeforeUnload().build());
browser.close(fireBeforeUnload = true)

保存文件选择器

在 Chromium 中，JavaScript 代码可以通过 showSaveFilePicker()方法显示文件保存选择器对话框。当 Chromium 需要显示该对话框时，Fuzio 会触发 SaveFileCallback。

你可以使用 SaveFileCallback 来实现自定义的文件选择器对话框，或以编程方式选择文件：

Java
Kotlin
browser.set(SaveFileCallback.class, (params, tell) -> {
    // Chromium 建议的文件名。
    var fileName = params.suggestedFileName();
    // Chromium 建议的目录。
    var directory = params.suggestedDirectory();
    // 可接受的文件扩展名。
    var extensions = params.acceptableExtensions();
    // 指示对话框是否应接受所有文件类型。
    var acceptAll = params.acceptAll();
    // 可接受扩展名的描述，
    // 例如："Image files" 或 "PDF File (.pdf)"。
    var filterDescription = params.filterDescription();

    if (isPdfFile(extensions)) {
        // 按给定路径保存文件。
        tell.save(Paths.get(directory).resolve(fileName));
    } else {
        // 取消操作。
        tell.cancel();
    }
});
browser.register(SaveFileCallback { params, tell ->
    // Chromium 建议的文件名。
    val fileName = params.suggestedFileName()
    // Chromium 建议的目录。
    val directory = params.suggestedDirectory()
    // 可接受的文件扩展名。
    val extensions = params.acceptableExtensions()
    // 指示对话框是否应接受所有文件类型。
    val acceptAll = params.acceptAll()
    // 可接受扩展名的描述，
    // 例如："Image files" 或 "PDF File (.pdf)"。
    var filterDescription = params.filterDescription()

    if (isPdfFile(extensions)) {
        // 按给定路径保存文件。
        tell.save(Paths.get(directory).resolve(fileName))
    } else {
        // 取消操作。
        tell.cancel()
    }
})

确认表单重新提交

当你刷新页面，或在通过 HTTP POST 请求加载的页面上前进/后退导航时，Chromium 会显示 “Confirm form resubmission（确认重新提交表单）” 对话框。

你可以使用 BeforeFormRepostCallback 来实现自定义对话框，或以编程方式进行响应：

Java
Kotlin
browser.set(BeforeFormRepostCallback.class, (params, action) -> {
    var title = params.title();
    var message = params.message();
    var cancelActionText = params.cancelActionText();
    var repostActionText = params.repostActionText();

    if (allowLeavingPage) {
        action.cancel();
    } else {
        action.repost();
    }
});
browser.register(BeforeFormRepostCallback { params, action ->
    val title = params.title()
    val message = params.message()
    val cancelActionText = params.cancelActionText()
    val repostActionText = params.repostActionText()
    if (allowLeavingPage) {
        action.cancel()
    } else {
        action.repost()
    }
})

选择颜色

当需要选择颜色时，会触发 SelectColorCallback 回调。这发生在用户点击 color 类型的 input 元素时：

<input type="color" value="#ff0000">

在该回调中，你可以获取对话框参数（例如默认颜色）。当对话框关闭时，必须调用 tell.select(Color) 或 tell.cancel()。例如：

Java
Kotlin
browser.set(SelectColorCallback.class, (params, tell) -> {
    // 默认颜色。
    var defaultColor = params.defaultColor();
    // 选中的颜色。
    var selectedColor = Color.newBuilder()
            .red(1.0f)
            .green(1.0f)
            .blue(1.0f)
            .build();
    // 已选中此颜色。
    tell.select(selectedColor);
});
browser.register(SelectColorCallback { params, tell ->
    // 默认颜色。
    val defaultColor = params.defaultColor()
    // 选中的颜色。
    val selectedColor = Color(red = 1.0f, green = 1.0f, blue = 1.0f)
    // 已选中此颜色。
    tell.select(selectedColor)
})

打开一个文件

当网页希望用户从设备存储中选择一个文件时，会触发 OpenFileCallback 回调。这发生在用户点击类型为 file 的 input 元素时：

<input type="file" accept="image/png, image/jpeg">

在该回调中，你可以获取对话框参数，例如建议的目录名、可接受的文件扩展名，以及可接受扩展名的描述。当对话框关闭时，必须调用tell.open(Path) 或 tell.cancel()。例如：

Java
Kotlin
browser.set(OpenFileCallback.class, (params, tell) -> {
    // 建议的目录。
    var suggestedDirectory = params.suggestedDirectory();
    // 可接受的扩展名。
    var acceptableExtensions = params.acceptableExtensions();
    // 应打开此文件。
    tell.open(Paths.get("<path-to-selected-file>"));
});
browser.register(OpenFileCallback { params, tell ->
    // 建议的目录。
    val suggestedDirectory = params.suggestedDirectory()
    // 可接受的扩展名。
    val acceptableExtensions: List<String> = params.acceptableExtensions()
    // 应打开此文件。
    tell.open(Path("<path-to-selected-file>"))
})

打开多个文件

当网页希望用户从设备存储中选择多个文件时，会触发 OpenFilesCallback 回调。这发生在用户点击类型为 file 且带有 multiple 属性的 input 元素时：

<input type="file" accept="image/png, image/jpeg" multiple>

在该回调中，你可以获取对话框参数，例如默认文件名、可接受的文件扩展名，以及可接受扩展名的描述。当对话框关闭时，必须调用 tell.open(Path...) 或 tell.cancel()。例如：

Java
Kotlin
browser.set(OpenFilesCallback.class, (params, tell) -> {
    // 可接受的扩展名。
    var acceptableExtensions = params.acceptableExtensions();
    var file1 = Paths.get("<path-to-selected-file1>");
    var file2 = Paths.get("<path-to-selected-file2>");
    // 应打开这些文件。
    tell.open(file1, file2);
});
browser.register(OpenFilesCallback { params, tell ->
    // 可接受的扩展名。
    val acceptableExtensions: List<String> = params.acceptableExtensions()
    val file1 = Path("<path-to-selected-file1>")
    val file2 = Path("<path-to-selected-file2>")
    //  应打开这些文件。
    tell.open(file1, file2)
})

打开文件夹

当 Chromium 需要用户从设备存储中选择一个文件夹时，会触发 OpenFolderCallback 回调。

如有需要，你可以创建并显示一个对话框，让用户选择文件夹。当对话框关闭时，必须调用 tell.open(Path) 或 tell.cancel()。例如：

Java
Kotlin
browser.set(OpenFolderCallback.class, (params, tell) -> {
    // 应打开此文件夹。
    tell.open(Paths.get("<path-to-folder>"));
});
browser.register(OpenFolderCallback { params, tell ->
    // 应打开此文件夹。
    tell.open(Path("<path-to-folder>"))
})

保存为 PDF

当通过 Print Preview（打印预览）对话框将网页保存为 PDF 文档时，会触发 SaveAsPdfCallback 回调。

在该回调中，你可以获取对话框参数，例如默认文件名。当对话框关闭时，必须调用 tell.save(Path) 或 tell.cancel()。例如：

Java
Kotlin
browser.set(SaveAsPdfCallback.class, (params, tell) -> {
    // 建议的文件名。
    var suggestedFileName = params.suggestedFileName();
    // 应保存此文件。
    tell.save(Paths.get("<path-to-file>"));
});
browser.register(SaveAsPdfCallback { params, tell ->
    // 建议的文件名。
    val suggestedFileName = params.suggestedFileName()
    // 应保存此文件。
    tell.save(Path("<path-to-file>"))
})

选择客户端证书

当 Chromium 需要用户从可用证书列表中选择一个客户端 SSL 证书时，会触发 SelectClientCertificateCallback 回调。

在该回调中，你可以获取对话框参数，例如对话框标题、消息、“Select” 和 “Cancel” 操作的本地化文本，以及可用证书列表。

当对话框关闭时，必须调用 tell.select(int) 或 tell.cancel()。例如：

Java
Kotlin
browser.set(SelectClientCertificateCallback.class, (params, tell) -> {
    // 对话框标题。
    var title = params.title();
    // 对话框消息。
    var message = params.message();
    // "Select" 操作的本地化文本。
    var selectActionText = params.selectActionText();
    // "Cancel" 操作的本地化文本。
    var cancelActionText = params.cancelActionText();
    // 可用的 SSL 证书。
    var certificates = params.certificates();
    // 列表中最后一个证书的索引。
    var certificateIndex = certificates.size() - 1;
    // 已选中列表中的最后一个证书。
    tell.select(certificateIndex);
});
browser.register(SelectClientCertificateCallback { params, tell ->
    // 对话框标题。
    val title = params.title()
    // 对话框消息。
    val message = params.message()
    // "Select" 操作的本地化文本。
    val selectActionText = params.selectActionText()
    // "Cancel" 操作的本地化文本。
    val cancelActionText = params.cancelActionText()
    // 可用的 SSL 证书。
    val certificates = params.certificates()
    // 列表中最后一个证书的索引。
    val certificateIndex = certificates.size - 1
    // 已选中列表中的最后一个证书。
    tell.select(certificateIndex)
})

打开外部应用

当网页希望在关联的外部应用程序中打开链接时，会触发 OpenExternalAppCallback 回调。

在该回调中，你可以获取本地化的对话框标题、消息，以及 “Open” 与 “Cancel” 操作的文本。你可以向最终用户显示一个对话框，让用户决定是否允许打开该链接；也可以像下面示例那样以编程方式打开外部应用：

Java
Kotlin
browser.set(OpenExternalAppCallback.class, (params, tell) -> tell.open());
browser.register(OpenExternalAppCallback { params, tell ->
    tell.open()
})

默认情况下，打开外部应用的请求会被取消。

如果你创建了一个 BrowserView 控件并将其嵌入到 JavaFX、Swing 或 SWT 应用中，那么会注册与 UI 工具包相关的默认回调实现。最终用户将看到如下对话框：

打开外部应用对话框

弹出窗口

上下文菜单