chrome.windows

描述： 使用 chrome.windows API 与浏览器窗口交互。您可以使用该模块创建、修改和重新排列浏览器中的窗口。
可用版本： 从 Chrome 5 开始支持。
Permissions： chrome.windows API 不需要任何权限就能使用。然而， Tab 的 url、title 和 favIconUrl 属性需要有 "tabs" 权限后才会给出。

清单文件

当您请求时，windows.Window 对象会包含 tabs.Tab 对象数组。如果您需要访问 tabs.Tab 的 url、title 或 favIconUrl 属性，您必须在清单文件中声明 "tabs" 权限。例如： 

      {
      
        "name": "我的扩展程序",
        ...
        "permissions": ["tabs"],
        ...
      }

当前窗口

扩展程序系统中的许多函数有一个可选的 windowId 参数，默认为当前窗口。

当前窗口即包含当前正在执行的代码的窗口，值得注意的是这不一定是顶层窗口或拥有焦点的窗口。

例如，假设一个扩展程序在一个 HTML 文件中创建了几个标签页或窗口，该 HTML 文件中又调用了 tabs.query。当前窗口是包含发出调用的页面的窗口，无论顶层窗口是哪一个。

而在事件页面中，当前窗口的值则是最后一个活动的窗口。在某些情况下，后台页面可能没有当前窗口。

例子

Two windows, each with one tab
您可以在 examples/api/windows 目录中找到使用窗口模块的简单例子，另一个例子在 inspector 例子的 tabs_api.html 文件中。有关其他例子以及查看源代码的帮助，请参见示例。

摘要

类型
Window
属性
WINDOW_ID_NONE
WINDOW_ID_CURRENT
方法
get − chrome.windows.get(integer windowId, object getInfo, function callback)
getCurrent − chrome.windows.getCurrent(object getInfo, function callback)
getLastFocused − chrome.windows.getLastFocused(object getInfo, function callback)
getAll − chrome.windows.getAll(object getInfo, function callback)
create − chrome.windows.create(object createData, function callback)
update − chrome.windows.update(integer windowId, object updateInfo, function callback)
remove − chrome.windows.remove(integer windowId, function callback)
事件
onCreated
onRemoved
onFocusChanged

类型

Window

属性
integer （可选）
id

窗口标识符，窗口标识符在浏览器会话中唯一。在某些情况下，例如当您使用 sessions API 查询窗口时，窗口可能没有标识符，此时存在会话标识符。

boolean focused

是否为当前具有焦点的窗口。

integer （可选）
top

窗口与屏幕顶部的距离，以像素为单位。在某些情况下，例如当您使用 sessions API 查询关闭的窗口时，窗口可能没有 top 属性。

integer （可选）
left

窗口与屏幕左侧的距离，以像素为单位。在某些情况下，例如当您使用 sessions API 查询关闭的窗口时，窗口可能没有 left 属性。

integer （可选）
width

窗口的宽度（包含边框），以像素为单位。在某些情况下，例如当您使用 sessions API 查询关闭的窗口时，窗口可能没有 width 属性。

integer （可选）
height

窗口的高度（包含边框），以像素为单位。在某些情况下，例如当您使用 sessions API 查询关闭的窗口时，窗口可能没有 height 属性。

array of tabs.Tab （可选）
tabs

表示窗口中所有标签页的 tabs.Tab 对象数组。

boolean incognito

是否为隐身窗口。

enum of "normal", "popup", "panel", or "app" （可选）
type

浏览器窗口的类型。在某些情况下，例如当您使用 sessions 查询关闭的窗口时，窗口可能没有 type 属性。

enum of "normal", "minimized", "maximized", or "fullscreen" （可选）
state

从 Chrome 17 开始支持。

浏览器窗口的状态。在某些情况下，例如当您使用 sessions 查询关闭的窗口时，窗口可能没有 state 属性。

boolean alwaysOnTop

从 Chrome 19 开始支持。

窗口是否设置为前端显示。

string （可选）
sessionId

从 Chrome 31 开始支持。

会话标识符，用于唯一标识由 sessions API 获取的窗口。

属性

-1 chrome.windows.WINDOW_ID_NONE

从 Chrome 6 开始支持。

表示不存在Chrome浏览器窗口的windowId值。
-2 chrome.windows.WINDOW_ID_CURRENT

从 Chrome 18 开始支持。

代表当前窗口的windowId值。

方法

get

chrome.windows.get(integer windowId, object getInfo, function callback)

获取一个窗口的有关详情。

参数
integer windowId
object （可选）
getInfo

从 Chrome 18 开始支持。

boolean （可选）
populate

如果为 true，windows.Window 对象会有 tabs 属性，包含所有 tabs.Tab 对象的列表。只有当扩展程序清单文件中包含 "tabs" 权限时，Tab 对象才会包含 url、title 和 favIconUrl 属性。

function callback

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

function( Window window) {...};
Window window

getCurrent

chrome.windows.getCurrent(object getInfo, function callback)

获取当前窗口。

参数
object （可选）
getInfo

从 Chrome 18 开始支持。

boolean （可选）
populate

如果为 true，windows.Window 对象会有 tabs 属性，包含所有 tabs.Tab 对象的列表。只有当扩展程序清单文件中包含 "tabs" 权限时，Tab 对象才会包含 url、title 和 favIconUrl 属性。

function callback

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

function( Window window) {...};
Window window

getLastFocused

chrome.windows.getLastFocused(object getInfo, function callback)

获得最近获得焦点的窗口，通常为顶层窗口。

参数
object （可选）
getInfo

从 Chrome 18 开始支持。

boolean （可选）
populate

如果为 true，windows.Window 对象会有 tabs 属性，包含所有 tabs.Tab 对象的列表。只有当扩展程序清单文件中包含 "tabs" 权限时，Tab 对象才会包含 url、title 和 favIconUrl 属性。

function callback

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

function( Window window) {...};
Window window

getAll

chrome.windows.getAll(object getInfo, function callback)

获取所有窗口。

参数
object （可选）
getInfo

boolean （可选）
populate

如果为 true，windows.Window 对象会有 tabs 属性，包含所有 tabs.Tab 对象的列表。只有当扩展程序清单文件中包含 "tabs" 权限时，Tab 对象才会包含 url、title 和 favIconUrl 属性。

function callback

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

function(array of Window windows) {...};
array of Window windows

create

chrome.windows.create(object createData, function callback)

创建（打开）一个新的浏览器窗口，可以提供大小、位置或默认 URL 等可选参数。

参数
object （可选）
createData
string or array of string （可选）
url

要在窗口中打开的一个 URL 或 URL 数组。完整的 URL 必须包含协议（即 "http://www.google.com"，而不是 "www.google.com"），而相对 URL 相对于扩展程序中的当前页面。默认为“打开新的标签页”页面。

integer （可选）
tabId

从 Chrome 10 开始支持。

需要移动至新窗口的标签页标识符。

integer （可选）
left

新窗口与屏幕左侧的距离，以像素为单位。如果未指定，新窗口将自然地与最后一个活动窗口偏离一定的距离。对于面板将忽略这一值。

integer （可选）
top

新窗口与屏幕顶部的距离，以像素为单位。如果未指定，新窗口将自然地与最后一个活动窗口偏离一定的距离。对于面板将忽略这一值。

integer （可选）
width

新窗口的宽度（包含边框），以像素为单位，如果未指定则默认为自然宽度。

integer （可选）
height

新窗口的高度（包含边框），以像素为单位，如果未指定则默认为自然高度。

boolean （可选）
focused

从 Chrome 12 开始支持。

如果为true，则打开一个活动窗口；如果为false，则打开一个不活动窗口。

boolean （可选）
incognito

新窗口是否为隐身窗口。

enum of "normal", "popup", "panel", or "detached_panel" （可选）
type

指定要创建的浏览器窗口类型。除非设置了“--enable-panels”标志，"panel" 与 "detatched_panel" 类型都会创建弹出窗口。

function （可选）
callback

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

function( Window window) {...};
Window （可选）
window

包含已创建窗口的详情。

update

chrome.windows.update(integer windowId, object updateInfo, function callback)

更新窗口属性。仅指定您需要更改的属性，未指定的属性不会更改。

参数
integer windowId
object updateInfo
integer （可选）
left

窗口与屏幕左侧的距离，以像素为单位。对于面板将忽略这一值。

integer （可选）
top

窗口与屏幕顶部的距离，以像素为单位。对于面板将忽略这一值。

integer （可选）
width

窗口的宽度，以像素为单位。对于面板将忽略这一值。

integer （可选）
height

窗口的高度，以像素为单位。对于面板将忽略这一值。

boolean （可选）
focused

从 Chrome 8 开始支持。

如果为true，将窗口置于顶层；如果为false，将Z-顺序中的下一个窗口置于顶层。

boolean （可选）
drawAttention

从 Chrome 14 开始支持。

如果为true，使窗口以吸引用户注意的方式显示，而不更改活动窗口，这一效果将一直持续到用户将焦点移至这一窗口。如果窗口已经获得焦点则该选项无效，将这一属性设置为false可以取消上一次的突出显示请求。

enum of "normal", "minimized", "maximized", or "fullscreen" （可选）
state

从 Chrome 17 开始支持。

窗口的新状态。"minimized"（最小化）、"maximized"（最大化）与 "fullscreen"（全屏）状态不能与 left、top、width 或 height 属性一起使用。

function （可选）
callback

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

function( Window window) {...};
Window window

remove

chrome.windows.remove(integer windowId, function callback)

移除（关闭）一个窗口以及其中的所有标签页。

参数
integer windowId
function （可选）
callback

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

function() {...};

事件

onCreated

当窗口创建时产生。

addListener

chrome.windows.onCreated.addListener(function callback)
参数
function callback

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

function( Window window) {...};
Window window

有关已创建窗口的详情。

onRemoved

当窗口移除（关闭）时产生。

addListener

chrome.windows.onRemoved.addListener(function callback)
参数
function callback

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

function(integer windowId) {...};
integer windowId

已移除窗口的标识符。

onFocusChanged

在当前具有焦点的窗口改变时产生，如果所有 Chrome 浏览器窗口都没有焦点则为 windows.WINDOW_ID_NONE。注意：在某些 Linux 窗口管理器中，从一个 Chrome 浏览器窗口切换到另一个之前总是会发送 windows.WINDOW_ID_NONE 的该事件。

addListener

chrome.windows.onFocusChanged.addListener(function callback)
参数
function callback

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

function(integer windowId) {...};
integer windowId

获得焦点的新窗口的标识符。

示例扩展程序