Chrome 扩展程序

本页面将介绍如何使用 Chrome 扩展程序。

本文描述的功能可在 DotNetBrowser 3.0.0 或更高版本中实现。

DotNetBrowser 提供了 Extensions API，允许安装、更新和卸载 Chrome 扩展程序。扩展程序在每个 Profile 中独立工作，不会与其他 Profile 共享。要访问特定 Profile 的扩展程序，请使用以下方法：

IExtensions extensions = profile.Extensions();

如果您删除了该 Profile，则该 Profile 中安装的所有扩展程序也将被删除。

安装扩展程序

您可以从 Chrome 应用商店手动安装 Chrome 扩展程序，也可以通过 CRX 文件以编程方式安装。

我们建议您在信任扩展程序来源的情况下，通过 CRX 文件安装扩展程序。与从 Chrome 应用商店安装扩展程序相比，这种方式具有以下优势：

1. 您可以控制所安装扩展程序的版本。您可以使用特定版本的 DotNetBrowser 测试该扩展程序，并确保其与 DotNetBrowser 使用的 Chromium 版本兼容。如果您从 Chrome 应用商店安装扩展程序，您将安装扩展程序的最新版本，该版本可能与您使用的 DotNetBrowser 版本不兼容。
2. 您可以将扩展程序与您的应用程序一起部署，并自动安装它。这样，您就不需要要求用户从 Chrome 应用商店手动安装扩展程序。
3. 您可以安装 Chrome 应用商店中未提供的扩展程序。如果您开发了一个希望在 DotNetBrowser 中使用的扩展程序，并且不想在 Chrome 应用商店中发布它，您可以将其打包成 CRX 文件并使用它。

要从 CRX 文件安装扩展，请使用以下方法：

string crxPath = Path.GetFullPath("path/to/extension.crx");
IExtension extension = await extensions.Install(crx);

该方法返回已安装扩展程序的实例。扩展程序所需的所有权限将自动授予。

重要提示：对您正在安装的扩展程序要非常谨慎。在 Chrome 应用商店中，CRX 文件必须具有发布者证明，该证明是在扩展程序发布时获得的。而在 DotNetBrowser 中，我们允许用户在没有发布者证明的情况下安装扩展程序，因此在获取 CRX 文件的资源时要格外小心。

出于安全原因，默认情况下禁止从 Chrome 应用商店安装扩展程序。如果您希望允许用户从 Chrome 应用商店安装扩展程序，需要使用以下方法启用安装：

extensions.InstallExtensionHandler =
    new Handler<InstallExtensionParameters, InstallExtensionResponse>(p => 
        InstallExtensionResponse.Install);

每次用户点击 Chrome 应用商店页面上的“添加到 Chrome”按钮时，都会调用 InstallExtensionHandler。您可以从 InstallExtensionParameters 对象中获取用户想要安装的扩展程序的信息，并决定是否允许安装：

extensions.InstallExtensionHandler =
    new Handler<InstallExtensionParameters, InstallExtensionResponse>(p => 
    {
        string name = p.ExtensionName;
        string version = p.ExtensionVersion;
        if (name.Equals("uBlock Origin") && version.Equals("1.35.2")) 
        {
            return InstallExtensionResponse.Install;
        } 
        else 
        {
            return InstallExtensionResponse.Cancel;
        }
    });

要在扩展程序安装时收到通知，请使用 ExtensionInstalled 事件：

extensions.ExtensionInstalled += (s, e) => 
{
    IExtension installedExtension = e.Extension;
});

更新扩展程序

如果您从 CRX 文件安装了扩展程序，并希望使用新版本进行更新，您只需从新的 CRX 文件安装即可：

string updatedCrxPath = Path.GetFullPath("path/to/updated_extension.crx");
IExtension extension = await extensions.Install(updatedCrxPath);

您无需删除扩展程序的旧版本。DotNetBrowser 会自动将扩展程序更新到最新版本。

重要提示：当您安装没有发布者证明的扩展程序时，确保使用相同的私钥（.pem 文件）进行打包。当使用不同的私钥或根本不使用私钥时，该扩展程序会被视为新扩展程序，会重新安装而不是更新。

如果您从 Chrome 应用商店安装扩展程序，则不能通过编程方式更新它。用户应从 Chrome 应用商店的扩展程序页面手动更新扩展程序。

要在扩展程序更新时收到通知，请使用 ExtensionUpdated 事件：

extensions.ExtensionUpdated += (s, e) => 
{
    IExtension updatedExtension = e.Extension;
});

卸载扩展程序

您可以以编程方式卸载从 CRX 文件或 Chrome 应用商店安装的扩展程序：

IExtension extension = 
    extensions.All.FirstOrDefault(ex => ex.Name.Equals("uBlock Origin"));
await extension.Uninstall();

如果扩展程序是从 Chrome 应用商店手动安装的，用户可能也希望手动卸载它。出于安全原因，默认情况下禁用从 Chrome 应用商店卸载扩展程序。如果您希望允许用户从 Chrome 应用商店或 chrome://extensions 页面卸载扩展程序，则需要启用卸载功能：

extensions.UninstallExtensionHandler =
    new Handler<UninstallExtensionParameters, UninstallExtensionResponse>(p => 
        UninstallExtensionResponse.Uninstall);

要在扩展程序被卸载时收到通知，请使用 ExtensionUninstalled 事件：

extensions.ExtensionUninstalled += (s, e) => 
{
    string extensionId = e.ExtensionId;
});

尝试操作已卸载的扩展程序将导致 ObjectDisposedException 异常。

扩展程序操作

Chrome 扩展程序可能提供仅在“扩展程序操作弹出窗口”中可用的功能。这是点击 Chrome 工具栏中的扩展程序图标时看到的对话框。虽然 DotNetBrowser 不显示 Chrome 工具栏，但它提供了一个 API 用于与扩展程序操作弹出窗口交互。

要模拟在特定标签页中点击 Chrome 工具栏中的扩展程序图标（扩展程序操作），请执行以下代码：

extension.GetAction(browser)?.Click();

扩展程序而不是 Chromium 负责选择要交互的 Browser。因此，扩展程序操作可能无法在获取它的 browser 上执行。

如果您希望在您的应用程序中显示扩展程序图标，您可以访问扩展程序操作的属性并订阅操作更新通知：

IExtensionAction action = extension.GetAction(browser);

if (action != null) 
{
    // 获取操作的属性。
    Bitmap icon = action.Icon;
    string badge = action.Badge;
    string tooltip = action.Tooltip;
    bool enabled = action.IsEnabled;

    // 获取扩展程序操作更新的通知。
    action.Updated += (s, e) => 
    {
        IExtensionAction updatedAction = e.ExtensionAction;
    });
});

扩展操作弹出窗口

当您创建 BrowserView 实例时，它将注册默认的 OpenExtensionActionPopupHandler 回调实现，该实现会在程序模拟点击扩展程序操作图标时显示扩展程序操作弹出窗口。

如果您想显示自定义的扩展程序操作弹出窗口，请注册您自己的 OpenExtensionActionPopupHandler 实现：

Browser.OpenExtensionActionPopupHandler = 
    new Handler<OpenExtensionActionPopupParameters>(p =>
    {
        IBrowser popupBrowser = p.PopupBrowser;
    });

扩展程序弹出窗口

一些扩展程序可能需要打开弹出窗口来显示网站或其他内容。默认情况下，DotNetBrowser 会阻止此类弹出窗口。要允许扩展程序显示弹出窗口，请注册您自己的以下回调实现：

extension.OpenExtensionPopupHandler = 
    new Handler<OpenExtensionPopupParameters>(p =>
    {
        IBrowser popupBrowser = p.PopupBrowser;
    });

或者使用默认实现：

extension.OpenExtensionPopupHandler = new DefaultOpenExtensionPopupHandler(browserView);

请注意，”extension popups（扩展程序弹出窗口）” 和 “extension action popups（扩展程序操作弹出窗口）”是不同的概念。

特点与限制

我们设计 Extensions API 的目的是使其尽可能地像 Chromium 一样运行。但由于 DotNetBrowser 是一个嵌入式 Browser，我们无法确保每种情况下的行为都相同。因此，在使用扩展程序时，您需要注意一些特点和限制。

1. 所有标签页都作为新窗口打开。
2. chrome.tabs.query 不会考虑扩展操作弹出窗口。
3. 扩展程序操作弹出窗口的大小是自动调整的，尺寸由扩展程序操作控制。
4. 当 DotNetBrowser 在用户数据目录或 Chromium 应用程序数据中找不到本机消息传递（chrome.runtime.connectNative）的清单时，它会在 Chrome 应用程序数据中检查。

与 Chromium 的标签页、窗口和其他用户界面元素相关的一些限制在于，windows.Window 被映射到与 Browser 关联的本机窗口，而不是它所嵌入的 .NET 窗口（如果有的话）。因此，windows.Window 对象的方法和属性，如 Window.width、Window.height、Window.focused 等，都绑定到那个本机窗口。

不支持的 Extensions APIs

以下是 DotNetBrowser 中不支持的 Chromium Extension APIs 列表：

• chrome.tabs.discard
• chrome.tabs.remove
• chrome.tabs.duplicate
• chrome.windows.remove
• chrome.windows.update
• chrome.window.create 参数中包含多个 URL
• chrome.sessions.restore
• chrome.desktopCapture.chooseDesktopMedia。

如果扩展程序调用了不受支持且返回 Promise 的方法，则会被拒绝并出现错误。如果方法接受回调，则 chrome.runtime.lastError 属性将设置为错误。

从 Chrome 应用商店下载 CRX

如果您想下载 Chrome 应用商店中扩展程序的 CRX 文件，您可以注册 InstallExtensionCallback 回调，在该回调中您可以获取即将从 Chrome 应用商店安装的扩展程序的 CRX 文件的绝对路径，并将其复制到其他位置：

extensions.InstallExtensionHandler =
    new Handler<InstallExtensionParameters, InstallExtensionResponse>(p =>
    { 
        string name = p.ExtensionName;
        string version = p.ExtensionVersion;
        string sourceCrxFilePath = Path.GetFullPath(p.ExtensionCrxFile);
        string targetCrxFilePath = Path.GetFullPath(name + "-" + version + ".crx");
        try {
            File.Copy(sourceCrxFilePath, targetCrxFilePath);
        } catch (IOException e) {
            throw new InvalidOperationException(e);
        }
        return InstallExtensionResponse.Cancel;
    });

现在，您可以在 Chrome 应用商店中加载所需的扩展程序并点击“添加到 Chrome”按钮。回调将被触发，扩展程序的 CRX 文件将被复制到指定的位置。