视窗 · Chrome 扩展开发文档

# 视窗 ## 内容 1. [清单](#manifest) 1. <a>h3Name</a> 2. [当前视窗](#current-window) 1. <a>h3Name</a> 3. [范例](#examples) 1. <a>h3Name</a> 4. [API 参考: chrome.windows](#apiReference) 1. [属性](#properties) 1. [WINDOW_ID_NONE](#property-WINDOW_ID_NONE) 2. [方法](#methods) 1. [create](#method-create) 2. [get](#method-get) 3. [getAll](#method-getAll) 4. [getCurrent](#method-getCurrent) 5. [getLastFocused](#method-getLastFocused) 6. [remove](#method-remove) 7. [update](#method-update) 3. [事件](#events) 1. [onCreated](#event-onCreated) 2. [onFocusChanged](#event-onFocusChanged) 3. [onRemoved](#event-onRemoved) 4. [类型](#types) 1. [Window](#type-Window) For information on how to use experimental APIs, see the [chrome.experimental.* APIs](experimental.html) page. ## 视窗使用chrome.windows模块与浏览器视窗进行交互。你可以使用这个模块在浏览器中创建、修改和重新排列视窗。 ![Two windows, each with one tab](https://box.kancloud.cn/2015-12-28_5680ab0f64a0e.png) ## 清单要使用视窗 API，你必须在[manifest.json](manifest.html)声明"tabs"的权限。（不，这不是一个错字 - 窗口和标签模块的互动如此密切，我们决定它们共享一个权限。）例如： ``` { "name": "My extension", ... **"permissions": ["tabs"]**, ... } ``` ## 当前视窗很多扩展系统的功能有一个可选的windowId参数，其默认值为当前视窗。 _当前视窗_是指包含当前正在执行的代码的视窗。重要的是要认识到，它可以跟最顶层或有焦点的视窗不一样。例如，假设一个扩展从一个单一的HTML文件中创建了一些标签或视窗，而这个HTML文件包含一个[chrome.tabs.getSelected](tabs.html#method-getSelected)的调用。当前视窗是指那个包含了发起调用的页面的视窗，不管它是不是最顶层视窗。在[背景页](background_pages.html)这个例子中，当前视窗就是最后一个活动视窗。在某些情况下，背景页可能没有当前视窗。 ## 范例你可以在[examples/api/windows](http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/windows/) 目录下找到一些使用windows模块的简单范例。另外一个范例是在[tabs_api.html](http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/tabs/inspector/tabs_api.html?content-type=text/plain)文件中的[检查器](http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/tabs/inspector/)范例。对于其他的例子和查看源代码的帮助，参见[示例](samples.html) 。 ## API 参考: chrome.windows ### 属性 #### WINDOW_ID_NONE chrome.windows.WINDOW_ID_NONE `WINDOW_ID_NONE`_( optional enumerated Type array of 整数 )_ Undocumented. 这个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](manifest.html#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`) Undocumented. 使用任何可选大小、位置或者默认提供的URL来创建（打开）一个新的浏览器。 #### 参数 `createData`_( optional enumerated 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `url`_( optional enumerated Type array of string or array of string 可选，字符串或者字符串数组)_ Undocumented. 一个或者一组在视窗作为标签打开的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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `tabId`_( optional enumerated Type array of integer可选，整数 )_ Undocumented. 你想要在新视窗选定的标签的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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `left`_( optional enumerated Type array of integer 可选，整数 )_ Undocumented. 新视窗相对于屏幕的左边缘的位置的像素值。如果没有指定，那么新的视窗从最后一个有焦点的视窗自然偏移。 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `top`_( optional enumerated Type array of integer可选，整数 )_ Undocumented. 新视窗相对于屏幕的上边缘的位置的像素值。如果没有指定，那么新的视窗从最后一个有焦点的视窗自然偏移。 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `width`_( optional enumerated Type array of integer可选，整数 )_ Undocumented. 新视窗的像素宽度。如果没有指定，默认为自然宽度。 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `height`_( optional enumerated Type array of integer可选，整数 )_ Undocumented. 新视窗的像素高度。如果没有指定，默认为自然高度。 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `incognito`_( optional enumerated Type array of boolean可选，Boolean类型 )_ Undocumented. 新视窗是否是隐身。 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](manifest.html#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"] )_ Undocumented. 指定新建浏览器视窗的类型。 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `callback`_( optional enumerated 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](manifest.html#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 enumerated [Window](windows.html#type-Window) 可选，视窗 array of paramType )_ Undocumented. 包含新创建视窗的详细信息。 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](manifest.html#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](manifest.html#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`) Undocumented. 获取有关窗口的详细信息。 #### 参数 `windowId`_( optional enumerated 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `callback`_( optional enumerated 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](manifest.html#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`_( optional enumerated [Window](windows.html#type-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](manifest.html#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](manifest.html#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`) Undocumented. 获得所有的视窗。 #### 参数 `getInfo`_( optional enumerated 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `populate`_( optional enumerated Type array of boolean 可选，Boolean类型)_ Undocumented. 如果是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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `callback`_( optional enumerated 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](manifest.html#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`_( optional enumerated Type array of [Window](windows.html#type-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](manifest.html#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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. #### getCurrent void chrome.windows.getCurrent(, function `callback`) Undocumented. 获得[当前视窗](#current-window)。 #### 参数 `callback`_( optional enumerated 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](manifest.html#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`_( optional enumerated [Window](windows.html#type-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](manifest.html#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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. #### getLastFocused void chrome.windows.getLastFocused(, function `callback`) Undocumented. 获取最近有焦点的视窗 — 一般是最顶层的视窗。 #### 参数 `callback`_( optional enumerated 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](manifest.html#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`_( optional enumerated [Window](windows.html#type-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](manifest.html#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](manifest.html#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`) Undocumented. 关闭一个视窗以及其包含的所有标签。 #### 参数 `windowId`_( optional enumerated 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `callback`_( optional enumerated 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](manifest.html#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](manifest.html#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`) Undocumented. 更新一个视窗的属性。只指定那些你希望修改的属性，未指定的属性将保持不变。 #### 参数 `windowId`_( optional enumerated 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `updateInfo`_( optional enumerated 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `left`_( optional enumerated Type array of integer 可选，整数 )_ Undocumented. 视窗相对屏幕左边界进行移动的像素偏移值。 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `top`_( optional enumerated Type array of integer 可选，整数 )_ Undocumented. 视窗相对屏幕上边界进行移动的像素偏移值。 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `width`_( optional enumerated Type array of integer可选，整数 )_ Undocumented. 视窗宽度调整的像素值。 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `height`_( optional enumerated Type array of integer可选，整数 )_ Undocumented. 视窗高度调整的像素值。 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `focused`_( optional enumerated Type array of boolean可选，Boolean类型 )_ Undocumented. 如果是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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `callback`_( optional enumerated 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](manifest.html#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 enumerated [Window](windows.html#type-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](manifest.html#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](manifest.html#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) {...}); Undocumented. 当一个新视窗被创建时触发。 #### 参数 `window`_( optional enumerated [Window](windows.html#type-Window) array of paramType )_ Undocumented. 被创建窗体的详细信息。 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](manifest.html#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) {...}); Undocumented. 当前获得焦点窗口改变时触发。Will be chrome.windows.WINDOW_ID_NONE if all chrome windows have lost focus. Note: On some Linux window managers, WINDOW_ID_NONE will always be sent immediately preceding a switch from one chrome window to another. #### Parameters `windowId`_( optional enumerated Type array of integer )_ Undocumented. ID of the newly focused window. 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. #### onRemoved chrome.windows.onRemoved.addListener(function(integer windowId) {...}); Undocumented. 当一个视窗被关闭时触发。 #### 参数 `windowId`_( optional enumerated Type array of integer 整数)_ Undocumented. 被关闭视窗的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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. ### 类型 #### Window `paramName`_( optional enumerated 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `id`_( optional enumerated Type array of integer 整数)_ Undocumented. 视窗的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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `focused`_( optional enumerated Type array of boolean )_ Undocumented. 该窗口是否当前焦点窗口。 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `top`_( optional enumerated Type array of integer_整数_ )_ Undocumented. 窗体相对屏幕上边缘的偏移像素值。 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `left`_( optional enumerated Type array of integer_整数_ )_ Undocumented. 窗体相对屏幕左边缘的偏移像素值。 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `width`_( optional enumerated Type array of integer_整数_ )_ Undocumented. 窗体宽度像素值。 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `height`_( optional enumerated Type array of integer_整数_ )_ Undocumented. 窗体高度像素值。 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `tabs`_( optional enumerated Type array of [Tab](tabs.html#type-Tab)可选，[标签](tabs.html#type-Tab)数组 array of paramType paramType )_ Undocumented. 表征窗体所包含[标签](tabs.html#type-Tab)的数组。 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `incognito`_( optional enumerated Type array of boolean )_ Undocumented. 窗体是否隐藏。 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](manifest.html#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", "app"] )_ Undocumented. 浏览器视窗类型。 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.