目录
Chrome 扩展程序
本页面将介绍如何使用 Chrome 扩展程序。
JxBrowser 提供了 Extensions API（扩展程序 API），允许您安装、更新和卸载 Chrome 扩展程序。这些扩展程序基于每个 Profile 工作，不会与其他 Profiles 共享。要访问特定 Profile 的扩展程序，请使用以下方法：
Extensions extensions = profile.extensions();
如果您删除 Profile，则该 Profile 下所有已安装的扩展程序也会被删除。
安装扩展程序
您可以从 Chrome 应用商店手动安装 Chrome 扩展程序，或从 CRX 文件以编程方式安装。
如果您信任扩展程序的来源，我们建议您从 CRX 文件安装扩展程序。与从 Chrome 应用商店安装扩展程序相比，该方法具有以下优点：
- 您可以控制安装的扩展程序版本。您可以使用特定的 JxBrowser 版本测试扩展程序，并确保其与 JxBrowser 使用的 Chromium 构建版本兼容。如果您从 Chrome 应用商店安装扩展程序，您将安装最新版本的扩展程序，该版本可能与您使用的 JxBrowser 版本不兼容。
- 您可以将扩展程序与您的应用程序一起部署并自动安装。因此，您不需要要求用户从 Chrome 应用商店手动安装扩展程序。
- 您可以安装在 Chrome 应用商店不可用的扩展程序。如果您开发了一个希望在 JxBrowser 中使用的扩展程序，并且不想将其发布在 Chrome 应用商店，您可以将其打包成 CRX 文件并使用它。
要从 CRX 文件安装扩展程序，请使用以下方法：
Extension extension =
extensions.install(Paths.get("path/to/extension.crx"));
该方法会返回已安装扩展程序的实例。扩展程序所需的所有权限都将自动授予。
重要：请对您正在安装的扩展程序保持高度警惕。在 Chrome 中，要安装扩展程序，CRX 文件必须具有发布者证明。发布者证明是在 Chrome 应用商店发布扩展程序时获得的。在 JxBrowser 中，我们允许用户安装没有发布者证明的扩展程序，因此请谨慎选择获取 CRX 文件的资源。
出于安全原因，默认情况下禁用从 Chrome 应用商店安装扩展程序。如果您希望允许用户从 Chrome 应用商店安装扩展程序，则需要使用以下方法允许安装：
extensions.set(InstallExtensionCallback.class, (params, tell) -> tell.install());
每次用户点击 Chrome 应用商店页面上的 “添加到 Chrome” 按钮时，InstallExtensionCallback 调都会被调用。您可以从 params 对象中获取用户想要安装的扩展程序的信息，并决定是否允许安装：
extensions.set(InstallExtensionCallback.class, (params, tell) -> {
String name = params.extensionName();
String version = params.extensionVersion();
if (name.equals("uBlock Origin") && version.equals("1.35.2")) {
tell.install();
} else {
tell.cancel();
}
});
要在扩展程序安装时收到通知，请使用 ExtensionInstalled 事件：
extensions.on(ExtensionInstalled.class, event -> {
Extension installedExtension = event.extension();
});
更新扩展程序
如果您从 CRX 文件安装了一个扩展程序，并且想要用新版本更新它，您只需要从新的 CRX 文件安装即可：
Extension extension =
extensions.install(Paths.get("path/to/updated_extension.crx"));
您不需要删除扩展程序的先前版本。JxBrowser 会自动将扩展程序更新到最新版本。
重要：在安装没有发布者证明的扩展程序时，请确保使用相同的私钥 (.pem 文件) 进行打包。如果使用不同的私钥或根本没有使用私钥，该扩展程序将被视为新扩展程序，并会重新安装而不会进行更新。
如果您从 Chrome 应用商店安装扩展程序，则无法以编程方式更新它。用户应从 Chrome 应用商店的扩展程序页面手动更新扩展程序。
要在扩展程序更新时收到通知，请使用 ExtensionUpdated 事件：
extensions.on(ExtensionUpdated.class, event -> {
Extension updatedExtension = event.extension();
});
卸载扩展程序
您可以以编程方式卸载从 CRX 文件或 Chrome 应用商店安装的扩展：
extensions.uninstall(extension);
如果扩展程序是从 Chrome 应用商店手动安装的，用户可能也希望手动卸载它。默认情况下，出于安全原因，卸载来自 Chrome 应用商店的扩展程序是禁用的。如果您希望允许用户从 Chrome 应用商店或 chrome://extensions 页面卸载扩展程序，则需要启用卸载功能：
extensions.set(UninstallExtensionCallback.class, (params, tell) -> tell.uninstall());
要在扩展程序卸载时收到通知，请使用 ExtensionUninstalled 事件：
extensions.on(ExtensionUninstalled.class, event -> {
String uninstalledExtensionId = event.extensionId();
});
尝试操作已卸载的扩展程序将导致 ObjectClosedException。
扩展程序操作
Chrome 扩展程序可能提供仅在 “extension action popups（扩展程序操作弹出窗口）” 中可用的功能。这是您点击 Chrome 工具栏中的扩展程序图标时看到的对话框。尽管 JxBrowser 不显示 Chrome 工具栏，但它提供了与扩展程序操作弹出窗口交互的 API。
要模拟点击 Chrome 工具栏中某个标签页的扩展程序图标（扩展程序操作），请执行以下代码：
// 将 `browser` 对象视为当前打开的 Chrome 标签页。
extension.action(browser).ifPresent(ExtensionAction::click);
如果您希望在应用程序中显示扩展程序图标，您可以访问扩展程序操作的属性并订阅操作更新通知
extension.action(browser).ifPresent(action -> {
// 获取操作的属性。
Bitmap icon = action.icon();
String badge = action.badge();
String tooltip = action.tooltip();
boolean enabled = action.isEnabled();
// 当扩展程序操作更新时获取通知。
action.on(ExtensionActionUpdated.class, event -> {
ExtensionAction updatedAction = event.action();
});
});
扩展程序操作弹出窗口
当您创建一个 BrowserView 实例时，它将注册 OpenExtensionActionPopupCallback 回调的默认实现，以便在程序模拟点击扩展程序操作图标时显示扩展程序操作弹出窗口。
如果您想显示自定义的扩展程序操作弹出窗口，您需要注册自己的 OpenExtensionActionPopupCallback 回调实现：
browser.set(OpenExtensionActionPopupCallback.class, (params, tell) -> {
Browser extensionActionPopup = params.popupBrowser();
tell.proceed();
});
扩展程序弹出窗口
一些扩展程序可能希望打开弹出窗口以显示网站或其他内容。默认情况下，JxBrowser 会阻止这些弹出窗口。要允许扩展程序显示弹出窗口，请注册您自己的以下回调函数实现：
extension.set(OpenExtensionPopupCallback.class, (params, tell) -> {
Browser extensionPopup = params.popupBrowser();
tell.proceed();
});
或者使用默认实现：
import com.teamdev.jxbrowser.view.swing.callback.DefaultOpenExtensionPopupCallback;
...
extension.set(OpenExtensionPopupCallback.class,
new DefaultOpenExtensionPopupCallback());
请注意，”extension popups（扩展程序弹出窗口）” 和 “extension action popups（扩展程序操作弹出窗口）” 是不同的弹出窗口。
特殊性与限制
我们设计扩展程序 API 的目标是尽可能模拟 Chromium 的行为。但由于 JxBrowser 是一个嵌入式 Browser，我们无法保证在所有情况下都能实现相同的行为。因此，在处理扩展时需要注意以下特殊性和限制。
- 所有标签页都将作为新窗口打开。
chrome.tabs.query永远不会考虑扩展程序操作弹出窗口。- 扩展程序操作弹出窗口的窗口大小是自动可调整的。窗口大小由扩展程序操作控制。
- 当 JxBrowser 在用户数据目录或 Chromium 应用程序数据中找不到本地消息传递（
chrome.runtime.connectNative）的清单时，它会检查 Chrome 应用程序数据中是否存在。
与 Chromium 的标签页、窗口和其他 UI 元素相关存在一些限制。windows.Window 对象映射到 Browser 关联的本地窗口，而不是可能嵌入的 Java 窗口。因此，windows.Window 对象的方法和属性，如 Window.width、Window.height、Window.focused 等，都与该本地窗口绑定。
不支持的扩展程序 API
以下是在 JxBrowser 中不支持的 Chromium Extension APIs（扩展程序 API）列表：
chrome.tabs.discardchrome.tabs.removechrome.tabs.duplicatechrome.windows.removechrome.windows.updatechrome.window.create参数中包含超过一个 URLchrome.sessions.restorechrome.desktopCapture.chooseDesktopMedia.
如果扩展程序调用了一个不支持的返回 Promise 的方法，该承诺会被拒绝并返回错误。如果一个方法接受回调函数，chrome.runtime.lastError 属性将被设置为一个错误。
从 Chrome 应用商店下载 CRX 文件
如果您想要从 Chrome 应用商店下载一个扩展程序的 CRX 文件，您可以注册 InstallExtensionCallback 回调函数，在这里您可以获取到即将从 Chrome 应用商店安装的扩展程序的 CRX 文件的绝对路径，并将其复制到另一个位置：
extensions.set(InstallExtensionCallback.class, (params, tell) -> {
String name = params.extensionName();
String version = params.extensionVersion();
File sourceCrxFilePath = Paths.get(params.extensionCrxFile()).toFile();
File targetCrxFilePath = Paths.get(name + "-" + version + ".crx").toFile();
try {
Files.copy(sourceCrxFilePath, targetCrxFilePath);
} catch (IOException e) {
throw new RuntimeException(e);
}
tell.cancel();
});
现在，您可以在 Chrome 应用商店加载所需的扩展程序，并点击 “添加到 Chrome” 按钮。回调函数将会被调用，扩展程序的 CRX 文件将会被复制到指定的位置。