此页面由 Cloud Translation API 翻译。

chrome.types

说明

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
    
    LevelOfControl
    
    设置的控制级别。
    
    值
    
    T
    
    更改后设置的值。
清除

void

Promise

清除设置，恢复所有默认值。

clear 函数如下所示：
```
(details: object,callback?: function)=> {...}
```
- 明细
  
  对象
  
  要清除哪项设置。
  - 范围
    
    ChromeSettingScope 可选
    
    清除设置的位置（默认：常规）。
- 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
    
    LevelOfControl
    
    设置的控制级别。
    
    值
    
    T
    
    设置的值。
- 返回
  Promise<object>
  
  Chrome 96 及更高版本
  
  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
set

void

Promise

设定设置的值。

set 函数如下所示：
```
(details: object,callback?: function)=> {...}
```
- 明细
  
  对象
  
  要更改哪项设置。
  - 范围
    
    ChromeSettingScope 可选
    
    该设置的位置（默认：常规）。
  - 值
    
    T
    
    设置的值。请注意，每项设置都有特定的值类型，该值类型与设置一起进行说明。扩展程序不应设置其他类型的值。
- callback
  
  函数（可选）
  
  callback 参数如下所示：
```
()=>void
```
- 返回
  Promise<void>
  
  Chrome 96 及更高版本
  
  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

ChromeSettingScope

Chrome 44 及更高版本

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

regular：常规个人资料的设置（如果未在其他地方覆盖，则无痕式个人资料会继承该设置）。
regular\_only：仅针对常规个人资料的设置（不会由无痕模式个人资料沿用）。
incognito\_persistent：针对在浏览器重启后继续有效的无痕模式个人资料的设置（覆盖常规偏好设置）。
incognito\_session\_only：适用于无痕个人资料的设置，该设置只能在无痕会话期间设置，且会在无痕会话结束时删除（覆盖常规和无痕模式永久保留偏好设置）。

枚举

"regular_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"