说明
chrome.types
API 包含 Chrome 的类型声明。
Chrome 浏览器设置
ChromeSetting
类型提供了一组常用的函数(get()
、set()
和 clear()
)以及一个事件发布器 (onChange
),用于设置 Chrome 浏览器。代理设置示例演示了这些函数的预期用途。
范围和生命周期
Chrome 区分浏览器设置的三种不同范围:
regular
- 在
regular
作用域中设置的设置会应用于常规浏览器窗口;如果未覆盖这些设置,无痕式窗口会沿用这些设置。这些设置会存储在磁盘中并一直存在,直到其被治理扩展程序清除,或者治理扩展程序被停用或卸载为止。 incognito_persistent
- 在
incognito_persistent
范围内设置的设置仅会应用于无痕式窗口。对于这些设置,它们将替换regular
设置。这些设置会存储到磁盘并一直存在,直到受治理扩展程序将其清除,或治理扩展程序被停用或卸载。 incognito_session_only
- 在
incognito_session_only
范围内设置的设置仅会应用于无痕式窗口。对于这些设置,它们将替换regular
和incognito_persistent
设置。这些设置不会存储到磁盘,并且在最后一个无痕式窗口关闭时会被清除。只有在至少打开一个无痕式窗口时,才能设置它们。
优先级
Chrome 会在不同的层管理设置。以下列表按优先级递增顺序介绍了可能影响有效设置的层。
- 操作系统提供的系统设置
- 命令行参数
- 扩展程序提供的设置
- 政策
如该列表所示,政策可能会优先于您通过扩展程序指定的任何更改。您可以使用 get()
函数来确定您的扩展程序是否能够提供设置,或者此设置是否会被替换。
如前所述,Chrome 允许对常规窗口和无痕式窗口使用不同的设置。以下示例说明了此行为。假设没有政策覆盖设置,并且扩展程序可以设定常规窗口的设置 (R) 和无痕式窗口的设置 (I)。
- 如果仅设置了 (R),则这些设置对常规窗口和无痕式窗口均有效。
- 如果仅设置了 (I),则这些设置仅对无痕式窗口有效。常规窗口使用由较低层确定的设置(命令行选项和系统设置)。
- 如果同时设置了 (R) 和 (I),系统会将各自的设置用于常规窗口和无痕式窗口。
如果两个或多个扩展程序想要将同一设置设为不同的值,最近安装的扩展程序将优先于其他扩展程序。如果最近安装的扩展程序仅设置 (I),则常规窗口的设置可以通过先前安装的扩展程序定义。
设置的“有效”值是指考虑优先规则后得出的值。供 Chrome 使用。
类型
ChromeSetting
允许访问 Chrome 浏览器设置的界面。相关示例请参见 accessibilityFeatures
。
属性
-
onChange
事件<functionvoid>
在设置更改后触发。
onChange.addListener
函数如下所示:(callback: function) => {...}
-
callback
功能
callback
参数如下所示:(details: object) => void
-
明细
对象
-
incognitoSpecific
布尔值 选填
发生更改的值是否特定于无痕模式会话。仅当用户在无痕模式下启用扩展程序时,此属性才会显示。
-
levelOfControl
设置的控制级别。
-
值
T
更改后设置的值。
-
-
-
-
清除
void
Promise清除设置,恢复所有默认值。
clear
函数如下所示:(details: object, callback?: function) => {...}
-
明细
对象
要清除哪项设置。
-
范围
清除设置的位置(默认:常规)。
-
-
callback
函数(可选)
callback
参数如下所示:() => void
-
返回
Promise<void>
Chrome 96 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
-
-
get
void
Promise获取设置的值。
get
函数如下所示:(details: object, callback?: function) => {...}
-
明细
对象
应考虑哪种设置。
-
无痕模式
布尔值 选填
是否返回适用于无痕模式会话的值(默认值为 false)。
-
-
callback
函数(可选)
callback
参数如下所示:(details: object) => void
-
明细
对象
当前有效值的详细信息。
-
incognitoSpecific
布尔值 选填
有效值是否特定于无痕模式会话。 仅当
get()
的details
参数中的incognito
属性为 true 时,此属性才会显示。 -
levelOfControl
设置的控制级别。
-
值
T
设置的值。
-
-
-
返回
Promise<object>
Chrome 96 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
-
-
set
void
Promise设定设置的值。
set
函数如下所示:(details: object, callback?: function) => {...}
-
明细
对象
要更改哪项设置。
-
范围
该设置的位置(默认:常规)。
-
值
T
设置的值。 请注意,每项设置都有特定的值类型,该值类型与设置一起进行说明。扩展程序不应设置其他类型的值。
-
-
callback
函数(可选)
callback
参数如下所示:() => void
-
返回
Promise<void>
Chrome 96 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
-
ChromeSettingScope
ChromeSetting 的范围。以下权限之一:
regular
:常规个人资料的设置(如果未在其他地方覆盖,则无痕式个人资料会继承该设置)。regular\_only
:仅针对常规个人资料的设置(不会由无痕模式个人资料沿用)。incognito\_persistent
:针对在浏览器重启后继续有效的无痕模式个人资料的设置(覆盖常规偏好设置)。incognito\_session\_only
:适用于无痕个人资料的设置,该设置只能在无痕会话期间设置,且会在无痕会话结束时删除(覆盖常规和 无痕模式永久保留偏好设置)。
枚举
"regular_only"
LevelOfControl
以下权限之一:
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"