视窗

使用chrome.windows模块与浏览器视窗进行交互。 你可以使用这个模块在浏览器中创建、修改和重新排列视窗。

Two windows, each with one tab

清单

要使用视窗 API，你必须在manifest.json声明"tabs"的权限 。（不，这不是一个错字 - 窗口和标签模块的互动如此密切，我们决定它们共享一个权限。）例如：

{
  "name": "My extension",
  ...
  "permissions": ["tabs"],
  ...
}

当前视窗

很多扩展系统的功能有一个可选的windowId参数，其默认值为当前视窗。

当前视窗是指包含当前正在执行的代码的视窗。重要的是要认识到，它可以跟最顶层或有焦点的视窗不一样。

例如，假设一个扩展从一个单一的HTML文件中创建了一些标签或视窗，而这个HTML文件包含一个chrome.tabs.getSelected的调用 。 当前视窗是指那个包含了发起调用的页面的视窗，不管它是不是最顶层视窗。

在背景页这个例子中 ，当前视窗就是最后一个活动视窗。在某些情况下，背景页可能没有当前视窗。

范例

你可以在examples/api/windows 目录下找到一些使用windows模块的简单范例。另外一个范例是在tabs_api.html文件中的检查器范例。 对于其他的例子和查看源代码的帮助，参见示例 。

API说明：chrome.windows

属性

WINDOW_ID_NONE

chrome.windows.WINDOW_ID_NONE
WINDOW_ID_NONE
( Type array of 整数 )
这个windowId值表示没有Chrome浏览器窗口的情况。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

方法

create

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

使用任何可选大小、位置或者默认提供的URL来创建（打开）一个新的浏览器。

参数

createData
( optional Type array of object可选，对象 )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
url
( optional Type array of string or array of string 可选，字符串或者字符串数组)
一个或者一组在视窗作为标签打开的URL。完全合格的URL必须包括一个类型（即'http://www.google.com'，不是'www.google.com'）。相对URL将与扩展内的当前页相关。默认为新的标签页面。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
tabId
( optional Type array of integer可选，整数 )
你想要在新视窗选定的标签的id。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
left
( optional Type array of integer 可选，整数 )
新视窗相对于屏幕的左边缘的位置的像素值。如果没有指定，那么新的视窗从最后一个有焦点的视窗自然偏移。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
top
( optional Type array of integer可选，整数 )
新视窗相对于屏幕的上边缘的位置的像素值。如果没有指定，那么新的视窗从最后一个有焦点的视窗自然偏移。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
width
( optional Type array of integer可选，整数 )
新视窗的像素宽度。如果没有指定，默认为自然宽度。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
height
( optional Type array of integer可选，整数 )
新视窗的像素高度。如果没有指定，默认为自然高度。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
incognito
( optional Type array of boolean可选，Boolean类型 )
新视窗是否是隐身。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
type
( optional enumerated Type array of string ["normal", "popup"]可选，枚举字符串["normal", "popup"] )
指定新建浏览器视窗的类型。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
callback
( optional Type array of function可选，函数 )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

回调函数

The callback parameter should specify a function that looks like this:

如果指定了回调参数，它应该指定一个如下所示函数： 

function(Window window) {...};
window
( optional Window 可选，视窗 array of paramType )
包含新创建视窗的详细信息。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

get

void chrome.windows.get(, integer windowId, function callback)

获取有关窗口的详细信息。

参数

windowId
( Type array of integer整数 )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
callback
( Type array of function函数 )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

Callback function

如果指定了回调参数，它应该指定一个如下所示函数：

If you specify the callback parameter, it should specify a function that looks like this: 

function(Window window) {...};
window
( Window array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

getAll

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

获得所有的视窗。

参数

getInfo
( optional Type array of object可选，对象 )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
populate
( optional Type array of boolean 可选，Boolean类型)
如果是true表示每个视窗对象都有一个包含该视窗所有标签的tabs属性。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
callback
( Type array of function函数 )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

回调函数

回调参数应该指定一个如下函数：

If you specify the callback parameter, it should specify a function that looks like this: 

function(array of Window windows) {...};
windows
( Type array of Window array of paramType paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

getCurrent

void chrome.windows.getCurrent(, function callback)

获得当前视窗。

参数

callback
( Type array of function 函数)
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

回调函数

如果指定了回调参数，它应该指定一个如下所示函数：

If you specify the callback parameter, it should specify a function that looks like this: 

function(Window window) {...};
window
( Window array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

getLastFocused

void chrome.windows.getLastFocused(, function callback)

获取最近有焦点的视窗 — 一般是最顶层的视窗。

参数

callback
( Type array of function 函数)
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

回调函数

如果指定了回调参数，它应该指定一个如下所示函数：

If you specify the callback parameter, it should specify a function that looks like this: 

function(Window window) {...};
window
( Window array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

remove

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

关闭一个视窗以及其包含的所有标签。

参数

windowId
( Type array of integer整数 )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
callback
( optional Type array of function 可选，函数 )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

回调函数

The callback parameter should specify a function that looks like this:

如果指定了回调参数，它应该指定一个如下所示函数：

function() {...};

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

update

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

更新一个视窗的属性。只指定那些你希望修改的属性，未指定的属性将保持不变。

参数

windowId
( Type array of integer整数 )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
updateInfo
( Type array of object对象 )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
left
( optional Type array of integer 可选，整数 )
视窗相对屏幕左边界进行移动的像素偏移值。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
top
( optional Type array of integer 可选，整数 )
视窗相对屏幕上边界进行移动的像素偏移值。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
width
( optional Type array of integer可选，整数 )
视窗宽度调整的像素值。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
height
( optional Type array of integer可选，整数 )
视窗高度调整的像素值。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
focused
( optional Type array of boolean可选，Boolean类型 )
如果是true，将该视窗提至前面。否则，将z-order上下一视窗提至前面。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
callback
( optional Type array of function 可选，函数)
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

回调函数

The callback parameter should specify a function that looks like this:

如果指定了回调参数，它应该指定一个如下所示函数：

function(Window window) {...};
window
( Window array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

事件

onCreated

chrome.windows.onCreated.addListener(function(Window window) {...});

当一个新视窗被创建时触发。

参数

window
( Window array of paramType )
被创建窗体的详细信息。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

onFocusChanged

chrome.windows.onFocusChanged.addListener(function(integer windowId) {...});

当前获得焦点窗口改变时触发。

Parameters

windowId
( Type array of integer )
新获取到焦点的窗口的ID。如果所有Chrome窗口都失去焦点，则为chrome.windows.WINDOW_ID_NONE。注意：在一些Linux的窗口管理器中，从一个Chrome窗口切换到另一个窗口的时候，WINDOW_ID_NONE总是会被先发送出去。

onRemoved

chrome.windows.onRemoved.addListener(function(integer windowId) {...});

当一个视窗被关闭时触发。

参数

windowId
( Type array of integer 整数)
被关闭视窗的ID。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

类型

Window

paramName
( Type array of object视窗，对象 )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
id
( Type array of integer 整数)
视窗的ID。视窗ID在一个浏览器会话中是唯一的。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
focused
( Type array of boolean )
该窗口是否当前焦点窗口。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
top
( Type array of integer整数 )
窗体相对屏幕上边缘的偏移像素值。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
left
( Type array of integer整数 )
窗体相对屏幕左边缘的偏移像素值。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
width
( Type array of integer整数 )
窗体宽度像素值。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
height
( Type array of integer整数 )
窗体高度像素值。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
tabs
( optional Type array of Tab可选，标签数组 array of paramType paramType )
表征窗体所包含标签的数组。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
incognito
( Type array of boolean )
窗体是否隐藏。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
type
( enumerated Type array of string ["normal", "popup", "app"] )
浏览器视窗类型。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.