文档

对话框

本指南展示了如何处理 JavaScript、打开/保存文件、颜色、客户端证书和其他对话框。

您可以使用本指南中描述的 JxBrowser API 以编程方式处理对话框。

对话框有不同的类型。当需要显示特定类型的对话框时，会调用相应的回调函数。如果没有注册回调函数，对话框将自动关闭，就像用户在对话框中点击了 Cancel 按钮一样。

在 BrowserView 实例化期间，给定的 Browser 实例将被配置为每种对话框的默认回调实现。默认实现使用相应的 UI 工具包功能来显示对话框。

JavaScript 对话框

Alert

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

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

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

JavaScript 的执行将被阻塞，直到警告对话框被关闭。

Confirm

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

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

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

JavaScript 的执行将被阻塞，直到确认对话框被关闭。

Prompt

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

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

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

JavaScript 的执行将被阻塞，直到提示对话框被关闭。

BeforeUnload

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

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

Java
Kotlin
browser.set(BeforeUnloadCallback.class, (params, tell) -> {
    // 对话框标题。
    String title = params.title();
    // 对话框消息。
    String message = params.message();
    // "Stay" 操作的本地化文本。
    String stayActionText = params.stayActionText();
    // "Leave" 操作的本地化文本。
    String leaveActionText = params.leaveActionText();
    ...
    // 已选择 "Stay" 操作。
    tell.stay();
});
browser.set(BeforeUnloadCallback::class.java, BeforeUnloadCallback { params, tell ->
    // 对话框标题。
    val title = params.title()
    // 对话框消息。
    val message = params.message()
    // "Stay" 操作的本地化文本。
    val stayActionText = params.stayActionText()
    // "Leave" 操作的本地化文本。
    val leaveActionText = params.leaveActionText()
    ...
    // 已选择 "Stay" 操作。
    tell.stay()
})

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

如果您希望在关闭 Browser 时显示对话框，请使用以下方法关闭 Browser：

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

选择颜色

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

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

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

Java
Kotlin
browser.set(SelectColorCallback.class, (params, tell) -> {
    // 默认颜色。
    Color defaultColor = params.defaultColor();
    // 已选颜色。
    Color selectedColor = Color.newBuilder()
            .red(1.0f)
            .green(1.0f)
            .blue(1.0f)
            .build();
    ...
    // 已选择此颜色。
    tell.select(selectedColor);
});
browser.set(SelectColorCallback::class.java, SelectColorCallback { params, tell ->
    // 默认颜色。
    val defaultColor = params.defaultColor()
    // 已选颜色。
    val selectedColor = Color.newBuilder()
            .red(1.0f)
            .green(1.0f)
            .blue(1.0f)
            .build()
    ...
    // 已选择此颜色。
    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) -> {
    // 默认文件名。
    String defaultFileName = params.defaultFileName();
    // 可接受的文件扩展名。
    List<String> acceptableExtensions = params.acceptableExtensions();
    ...
    // 应打开此文件。
    tell.open(Paths.get("<path-to-selected-file>"));
});
browser.set(OpenFileCallback::class.java, OpenFileCallback { params, tell ->
    // 默认文件名。
    val defaultFileName = params.defaultFileName()
    // 可接受的文件扩展名。
    val acceptableExtensions: List<String> = params.acceptableExtensions()
    ...
    // 应打开此文件。
    tell.open(Path("<path-to-selected-file>"))
})

打开多个文件

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

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

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

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

另存为 PDF

当通过打印预览对话框将网页另存为 PDF 文档时，会调用 SaveAsPdfCallback 回调函数。

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

Java
Kotlin
browser.set(SaveAsPdfCallback.class, (params, tell) -> {
    // 建议的文件名。
    String suggestedFileName = params.suggestedFileName();
    ...
    // 应保存此文件。
    tell.save(Paths.get("<path-to-file>"));
});
browser.set(SaveAsPdfCallback::class.java, 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) -> {
    // 对话框标题。
    String title = params.getTitle();
    // 对话框消息。
    String message = params.getMessage();
    // "Select" 操作的本地化文本。
    String selectActionText = params.getSelectActionText();
    // "Cancel" 操作的本地化文本。
    String cancelActionText = params.getCancelActionText();
    // 可用的 SSL 证书列表。
    List<Certificate> certificates = params.getCertificatesList();
    // 列表中最后一个证书的索引。
    int certificateIndex = certificates.size() - 1;
    ...
    // 已选择列表中的最后一个证书。
    tell.select(certificateIndex);
});
browser.set(SelectClientCertificateCallback::class.java,
    SelectClientCertificateCallback { params, tell ->
        // 对话框标题。
        val title = params.getTitle()
        // 对话框消息。
        val message = params.getMessage()
        // "Select" 操作的本地化文本。
        val selectActionText = params.getSelectActionText()
        // "Cancel" 操作的本地化文本。
        val cancelActionText = params.getCancelActionText()
        // 可用的 SSL 证书列表。
        val certificates = params.getCertificatesList()
        // 列表中最后一个证书的索引。
        val certificateIndex = certificates.size - 1
        ...
        // 已选择列表中的最后一个证书。
        tell.select(certificateIndex)
    }
)

打开外部应用程序

当网页想要在关联的外部应用程序中打开一个链接时，会调用 OpenExternalAppCallback 回调函数。

在此回调中，您可以获取本地化对话框标题、消息、“Open” 和 “Cancel” 操作的文本。您可以向终端用户显示一个对话框，以决定是否可以打开链接，或以编程方式打开外部应用程序，如下例所示：

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

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

如果您创建一个 BrowserView 控件并将其嵌入到您的 JavaFX、Swing、SWT 应用程序中，将会注册默认的特定于 UI 工具包的回调实现。终端用户将看到以下对话框：

Open External App Dialog

介绍

安装

指南

故障排除

对话框