視窗 · 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.