chrome.types

说明

chrome.types API 包含 Chrome 的类型声明。

Chrome 浏览器设置

ChromeSetting 原型提供了一组通用函数（get()、set() 和 clear()），以及 Chrome 浏览器设置的事件发布者 (onChange)。代理设置示例演示了这些函数的预期使用方式。

范围和生命周期

Chrome 会区分三种不同的浏览器设置范围：

regular
在 regular 范围内设置的设置适用于常规浏览器窗口，如果未被覆盖，则会被无痕式窗口继承。这些设置会存储到磁盘，并且在被管理扩展程序清除或管理扩展程序被停用/卸载之前，会一直保留。
incognito_persistent
在 incognito_persistent 范围内设置的设置仅适用于无痕式窗口。对于这些，它们会替换 regular 设置。这些设置会存储到磁盘，并且会一直有效，直到被管理扩展程序清除，或者管理扩展程序被停用或卸载。
incognito_session_only
在 incognito_session_only 范围内设置的设置仅适用于无痕式窗口。对于这些，它们会替换 regular 和 incognito_persistent 设置。这些设置不会存储到磁盘，并且会在最后一个无痕式浏览窗口关闭时清除。只有在至少一个无痕式窗口处于打开状态时，才能设置这些偏好设置。

优先级

Chrome 会在不同层级管理设置。以下列表按优先级升序介绍了可能会影响有效设置的层。

  1. 操作系统提供的系统设置
  2. 命令行参数
  3. 由扩展程序提供的设置
  4. 政策

正如列表所示，政策可能会取代您通过扩展程序指定的任何更改。您可以使用 get() 函数来确定扩展程序是否能够提供设置，或者此设置是否会被覆盖。

如上所述，Chrome 允许为常规窗口和无痕窗口使用不同的设置。以下示例说明了此行为。假设没有政策会替换这些设置，并且扩展程序可以为常规窗口 (R) 设置设置，也可以为无痕式窗口 (I) 设置设置。

  • 如果仅设置了 (R)，这些设置将同时对常规窗口和无痕式窗口生效。
  • 如果仅设置了 (I)，则这些设置仅对无痕式窗口有效。常规窗口使用由较低层（命令行选项和系统设置）确定的设置。
  • 如果同时设置了 (R) 和 (I)，则会分别针对常规窗口和无痕窗口使用相应的设置。

如果有两个或更多扩展程序想要将同一设置设为不同的值，则最近安装的扩展程序优先于其他扩展程序。如果最近安装的扩展程序仅设置了 (I)，则常规窗口的设置可以由之前安装的扩展程序定义。

设置的有效值是指根据优先规则得出的值。它由 Chrome 使用。

类型

ChromeSetting

允许访问 Chrome 浏览器设置的界面。相关示例请参见 accessibilityFeatures。

属性

  • onChange

    Event<functionvoidvoid>

    在设置更改后触发。

    onChange.addListener 函数如下所示： 

    (callback: function) => {...}

    • callback

      函数

      callback 参数如下所示： 

      (details: object) => void

      • 详细信息

        对象

        • incognitoSpecific

          布尔值（可选）

          更改后的值是否仅适用于无痕式浏览会话。 仅当用户在无痕模式下启用了扩展程序时，此属性才会存在。

        • levelOfControl

          LevelOfControl

          相应设置的控制级别。

        • 值

          T

          更改后的设置值。

  • 清除

    void

    Promise

    清除设置，恢复任何默认值。

    clear 函数如下所示： 

    (details: object, callback?: function) => {...}

    • 详细信息

      对象

      要清除的设置。

    • callback

      函数 可选

      callback 参数如下所示： 

      () => void

    • 返回

      Promise<void>

      Chrome 96 及更高版本

      仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

  • get

    void

    Promise

    获取设置的值。

    get 函数如下所示： 

    (details: object, callback?: function) => {...}

    • 详细信息

      对象

      应考虑哪项设置。

      • 无痕

        布尔值（可选）

        是否返回适用于无痕会话的值（默认值为 false）。

    • callback

      函数 可选

      callback 参数如下所示： 

      (details: object) => void

      • 详细信息

        对象

        当前有效值的详细信息。

        • incognitoSpecific

          布尔值（可选）

          有效值是否特定于无痕式浏览会话。 仅当 get() 的 details 参数中的 incognito 属性为 true 时，才会显示此属性。

        • levelOfControl

          LevelOfControl

          相应设置的控制级别。

        • 值

          T

          相应设置的值。

    • 返回

      Promise<object>

      Chrome 96 及更高版本

      仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

  • set

    void

    Promise

    设置相应设置的值。

    set 函数如下所示： 

    (details: object, callback?: function) => {...}

    • 详细信息

      对象

      要更改的设置。

      • 范围

        ChromeSettingScope 可选

        设置的放置位置（默认值：常规）。

      • 值

        T

        相应设置的值。 请注意，每项设置都有特定的值类型，该类型会与设置一起说明。扩展程序不应设置其他类型的值。

    • callback

      函数 可选

      callback 参数如下所示： 

      () => void

    • 返回

      Promise<void>

      Chrome 96 及更高版本

      仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

ChromeSettingScope

Chrome 44 及更高版本

ChromeSetting 的范围。以下权限之一：

  • regular：常规配置文件的设置（如果未在其他位置替换，则由无痕式配置文件继承），
  • regular\_only：仅适用于常规配置文件的设置（不会由无痕式配置文件继承），
  • incognito\_persistent：无痕模式配置文件的设置，可在浏览器重启后继续生效（会替换常规偏好设置），
  • incognito\_session\_only：无痕式个人资料的设置，只能在无痕式会话期间设置，并在无痕式会话结束时删除（会替换常规偏好设置和 incognito_persistent 偏好设置）。

枚举

“常规”

"regular_only"

"incognito_persistent"

"incognito_session_only"

LevelOfControl

Chrome 44 及更高版本

以下权限之一：

  • not\_controllable：无法由任何扩展程序控制
  • controlled\_by\_other\_extensions：由优先级较高的扩展程序控制
  • controllable\_by\_this\_extension：可由此扩展程序控制
  • controlled\_by\_this\_extension：由相应扩展程序控制

枚举

"not_controllable"

"controlled_by_other_extensions"

"controllable_by_this_extension"

"controlled_by_this_extension"