chrome.types

描述： chrome.types API 包含用于 Chrome 浏览器的类型声明。
可用版本： 从 Chrome 13 开始支持。

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 浏览器在不同的层面上管理设置。以下列表按照优先级递增的顺序描述了可能影响有效设置的不同层面。

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

这一列表暗含着策略可以覆盖您用扩展程序指定的任何更改，您可以使用 get() 函数来确定您的扩展程序能否提供设置或者设置是否会被覆盖。

如前面所讨论，Chrome 浏览器允许普通窗口与隐身窗口使用不同的设置。以下例子演示了这一行为。假设没有策略覆盖设置并且扩展程序可以分别为普通窗口（R）和隐身窗口（I）更改设置。

  • 如果只设置了（R），这些设置对普通窗口和隐身窗口都有效。
  • 如果只设置了（I），这些设置仅对隐身窗口有效。普通窗口使用更低的层面确定的设置（命令行参数和系统设置）。
  • 如果（R）和（I）都设置，将分别为普通窗口与隐身窗口使用相应的设置。

如果两个或更多的扩展程序需要将同一设置修改为不同的值，最近安装的扩展程序优先于其他扩展程序。如果最近安装的扩展程序只设置了（I），普通窗口的设置可以由之前安装的扩展程序定义。

设置的有效值是考虑到以上优先级规则之后的结果，Chrome 浏览器将会采用它。

摘要

类型
ChromeSetting
ImageDetails

类型

ChromeSetting

允许访问 Chrome 浏览器设置的接口，有关例子请参见 accessibilityFeatures。

onChange

设置更改后产生。

方法

get

ChromeSetting.get(object details, function callback)

获得设置的值。

参数
object details

考虑哪一项设置。

boolean （可选）
incognito

是否返回应用于隐身会话的值（默认为 false）。

function callback

callback 参数应该是一个如下形式的函数：

function(object details) {...};
object details

当前有效值的详情。

any value

设置的值。

enum of "not_controllable", "controlled_by_other_extensions", "controllable_by_this_extension", or "controlled_by_this_extension" levelOfControl

以下值之一：

  • "not_controllable"：无法由任何扩展程序控制。
  • "controlled_by_other_extensions"：由优先级更高的扩展程序控制。
  • "controllable_by_this_extension"：可以由该扩展程序控制。
  • "controlled_by_this_extension"：由该扩展程序控制。
boolean （可选）
incognitoSpecific

有效值是否只适用于隐身会话。
只有当 get() 方法的 details 参数中 incognito 属性为 true 时才存在。

set

ChromeSetting.set(object details, function callback)

修改设置的值。

参数
object details

考虑哪一项设置。

any value

设置的值。
注意每一项设置都有特定的值类型，与该设置一起描述。扩展程序不应该设置不同类型的值。

enum of "regular", "regular_only", "incognito_persistent", or "incognito_session_only" （可选）
scope

修改哪些范围的设置（默认为 "regular"）。以下值之一：

  • "regular"：用于普通用户配置文件（如果没有被其他地方的设置覆盖，也将由隐身窗口继承）；
  • "regular_only"：仅用于普通用户配置文件（不被隐身配置文件继承）；
  • "incognito_persistent"：用于隐身配置文件的设置，并且在浏览器重启后仍保留（覆盖 "regular" 设置）；
  • "incognito_session_only"：用于隐身配置文件的设置，并且只能在隐身会话中设置，在隐身会话结束时删除（覆盖 "regular" 和 "incognito_persistent" 设置）。
function （可选）
callback

设置操作完成后调用。

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function() {...};

clear

ChromeSetting.clear(object details, function callback)

清除设置，恢复默认值。

参数
object details

要清除哪一项设置。

enum of "regular", "regular_only", "incognito_persistent", or "incognito_session_only" （可选）
scope

清除哪些范围的设置（默认为 "regular"）。以下值之一：

  • "regular"：用于普通用户配置文件（如果没有被其他地方的设置覆盖，也将由隐身窗口继承）；
  • "regular_only"：仅用于普通用户配置文件（不被隐身配置文件继承）；
  • "incognito_persistent"：用于隐身配置文件的设置，并且在浏览器重启后仍保留（覆盖 "regular" 设置）；
  • "incognito_session_only"：用于隐身配置文件的设置，并且只能在隐身会话中设置，在隐身会话结束时删除（覆盖 "regular" 和 "incognito_persistent" 设置）。

function （可选）
callback

清除操作完成后调用。

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function() {...};
事件

addListener

onChange.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

function(object details) {...};
object details
any value

更改后的设置值。

enum of "not_controllable", "controlled_by_other_extensions", "controllable_by_this_extension", or "controlled_by_this_extension" levelOfControl

以下值之一：

  • "not_controllable"：无法由任何扩展程序控制。
  • "controlled_by_other_extensions"：由优先级更高的扩展程序控制。
  • "controllable_by_this_extension"：可以由该扩展程序控制。
  • "controlled_by_this_extension"：由该扩展程序控制。
boolean （可选）
incognitoSpecific

有效值是否只适用于隐身会话。
只有当用户允许这一扩展程序在隐身模式中运行时才会存在该属性。

ImageDetails

从 Chrome 33 开始支持。

图片格式和质量的有关详情。
属性
enum of "jpeg", or "png" （可选）
format

所得图像的格式，默认为 jpeg。

integer （可选）
quality

当格式为 "jpeg" 时，控制所得图像的质量。使用 PNG 图像时忽略该参数。随着质量下降，所得图像会更加粗糙，用于储存图像所需的字节数也会下降。