chrome.windows

说明

使用 chrome.windows API 与浏览器窗口进行交互。您可以使用此 API 在浏览器中创建、修改和重新排列窗口。

权限

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

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

概念和用法

当前窗口

扩展系统中的许多函数都接受可选的 windowId 参数，该参数默认为 。

“当前窗口”是包含当前正在执行的代码的窗口。时间是 请务必注意，该窗口可能不同于最顶层的窗口或聚焦的窗口。

例如，假设某个扩展程序根据一个 HTML 文件创建了几个标签页或窗口，并且 HTML 文件包含对 tabs.query() 的调用。当前窗口是包含 （无论最顶层的窗口在什么位置），

对于 Service Worker，当前窗口的值会退回到上一个活跃窗口 窗口。在某些情况下，后台网页可能没有当前窗口。

示例

若要试用此 API，请从 chrome-extension-samples 安装 chrome-extension-samples 存储库

<ph type="x-smartling-placeholder">
</ph> 两个窗口，每个窗口各有一个标签页
两个窗口，每个窗口各有一个标签页。

类型

CreateType

Chrome 44 及更高版本

指定要创建的浏览器窗口的类型。“panel”已弃用，仅适用于 Chrome 操作系统中已列入许可名单的现有扩展程序。

枚举

"normal"
将窗口指定为标准窗口。

"popup"
将窗口指定为弹出式窗口。

"panel"
将窗口指定为面板。

QueryOptions

Chrome 88 及更高版本

属性

  • populate

    布尔值（可选）

    如果为 true，windows.Window 对象具有 tabs 属性，其中包含 tabs.Tab 对象列表。如果扩展程序的清单文件包含 "tabs" 权限，则 Tab 对象仅包含 url、pendingUrl、title 和 favIconUrl 属性。

  • windowTypes

    WindowType[] 选填

    如果已设置，系统会根据返回的 windows.Window 的类型对其进行过滤。如果未设置，默认过滤条件将设置为 ['normal', 'popup']。

Window

属性

  • alwaysOnTop

    布尔值

    窗口是否设置为始终位于顶部。

  • 专注

    布尔值

    该窗口当前是否为聚焦窗口。

  • 高度

    编号（选填）

    窗口（包括框架）的高度（以像素为单位）。在某些情况下，不能为窗口分配 height 属性；例如，通过 sessions API 查询已关闭的窗口时。

  • id

    编号（选填）

    窗口的 ID。窗口 ID 在浏览器会话中是唯一的。在某些情况下，不能为窗口分配 ID 属性；例如，使用 sessions API 查询窗口时，此时可能存在会话 ID。

  • 无痕模式

    布尔值

    用于指明窗口是否处于无痕模式。

  • 左侧

    编号（选填）

    窗口与屏幕左边缘的偏移量（以像素为单位）。在某些情况下，不能为窗口分配 left 属性；例如，通过 sessions API 查询已关闭的窗口时。

  • sessionId

    字符串（可选）

    用于对窗口进行唯一标识的会话 ID，从 sessions API 获取。

  • 州

    WindowState（可选）

    此浏览器窗口的状态。

  • 标签页

    Tab[] 可选

    一组 tabs.Tab 对象，表示窗口中的当前标签页。

  • 顶部

    编号（选填）

    窗口与屏幕顶部边缘的偏移量（以像素为单位）。在某些情况下，不能为窗口分配 top 属性；例如，通过 sessions API 查询已关闭的窗口时。

  • 类型

    WindowType 选填

    浏览器窗口的类型。

  • width

    编号（选填）

    窗口（包括框架）的宽度（以像素为单位）。在某些情况下，不能为窗口分配 width 属性；例如，通过 sessions API 查询已关闭的窗口时。

WindowState

Chrome 44 及更高版本

此浏览器窗口的状态。在某些情况下，不能为窗口分配 state 属性；例如，通过 sessions API 查询已关闭的窗口时。

枚举

"normal"
正常窗口状态（非最小化、最大化或全屏）。

"minimized"
窗口状态最小化。

"maximized"
窗口状态最大化。

"fullscreen"
全屏窗口状态。

"locked-fullscreen"
锁定的全屏窗口状态。这种全屏状态无法通过用户操作退出，仅适用于 Chrome 操作系统中列入许可名单的扩展程序。

WindowType

Chrome 44 及更高版本

浏览器窗口的类型。在某些情况下，不能为窗口分配 type 属性；例如，通过 sessions API 查询已关闭的窗口时。

枚举

"normal"
正常的浏览器窗口。

"popup"
浏览器弹出式窗口。

"panel"
在此 API 中已弃用。一个 Chrome 应用面板样式的窗口。扩展程序只能查看自己的面板窗口。

"app"
在此 API 中已弃用。一个 Chrome 应用窗口。扩展程序只能查看应用自己的窗口。

"devtools"
开发者工具窗口。

属性

WINDOW_ID_CURRENT

表示当前窗口的 windowId 值。

值

-2

WINDOW_ID_NONE

windowId 值，表示没有 Chrome 浏览器窗口。

值

-1

方法

create()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.windows.create(
  createData?: object,
  callback?: function,
)

使用提供的任何可选尺寸、位置或默认网址创建（打开）新的浏览器窗口。

参数

  • createData

    对象（可选）

    • 专注

      布尔值（可选）

      如果为 true，则打开一个活动窗口。如果为 false，则打开处于非活动状态的窗口。

    • 高度

      编号（选填）

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

    • 无痕模式

      布尔值（可选）

      新窗口是否应设置为无痕式窗口。

    • 左侧

      编号（选填）

      新窗口距离屏幕左边缘的像素数。如果未指定，新窗口则会从上一个聚焦窗口自然偏移。对于面板，此值会被忽略。

    • setSelfAsOpener

      布尔值（可选）

      Chrome 64 及更高版本

      如果为 true，则新建窗口的“window.opener”设置为调用方，并且与调用方位于同一相关浏览上下文单元中。

    • 州

      WindowState（可选）

      Chrome 44 及更高版本

      窗口的初始状态。minimized、maximized 和 fullscreen 状态不能与 left、top、width 或 height 结合使用。

    • tabId

      编号（选填）

      要添加到新窗口的标签页的 ID。

    • 顶部

      编号（选填）

      新窗口距离屏幕顶部边缘的像素值。如果未指定，新窗口则会从上一个聚焦窗口自然偏移。对于面板，此值会被忽略。

    • 类型

      CreateType 可选

      指定要创建的浏览器窗口的类型。

    • 网址

      string |string[] 选填

      要在窗口中以标签页形式打开的网址或网址数组。完全限定网址必须包含架构，例如“http://www.google.com”，而不是“www.google.com”。在扩展程序中，非完全限定的网址会被视为相对网址。默认为“新标签页”。

    • width

      编号（选填）

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (window?: Window) => void

    • 窗口

      时间范围（可选）

      包含所创建窗口的相关详细信息。

返回

  • Promise&lt;Window |未定义>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

get()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.windows.get(
  windowId: number,
  queryOptions?: QueryOptions,
  callback?: function,
)

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

参数

  • windowId

    number

  • queryOptions

    QueryOptions 可选

    Chrome 88 及更高版本
  • callback

    函数（可选）

    callback 参数如下所示： 

    (window: Window) => void

返回

  • Promise&lt;Window&gt;

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getAll()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
)

获取所有窗口。

参数

  • queryOptions

    QueryOptions 可选

    Chrome 88 及更高版本
  • callback

    函数（可选）

    callback 参数如下所示： 

    (windows: Window[]) => void

返回

  • Promise&lt;Window[]&gt;

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getCurrent()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
)

获取当前窗口。

参数

  • queryOptions

    QueryOptions 可选

    Chrome 88 及更高版本
  • callback

    函数（可选）

    callback 参数如下所示： 

    (window: Window) => void

返回

  • Promise&lt;Window&gt;

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getLastFocused()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
)

获取最近获得焦点的窗口，通常是“位于顶部”的窗口。

参数

  • queryOptions

    QueryOptions 可选

    Chrome 88 及更高版本
  • callback

    函数（可选）

    callback 参数如下所示： 

    (window: Window) => void

返回

  • Promise&lt;Window&gt;

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

remove()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.windows.remove(
  windowId: number,
  callback?: function,
)

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

参数

  • windowId

    number

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

update()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.windows.update(
  windowId: number,
  updateInfo: object,
  callback?: function,
)

更新窗口的属性。仅指定要更改的属性；未指定的属性会保持不变。

参数

  • windowId

    number

  • updateInfo

    对象

    • drawAttention

      布尔值（可选）

      如果为 true，则以吸引用户注意窗口的方式显示窗口，而不会更改聚焦的窗口。该效果将持续到用户将焦点切换到窗口为止。如果窗口已具有焦点，则此选项无效。设置为 false 可取消之前的 drawAttention 请求。

    • 专注

      布尔值（可选）

      如果为 true，则将窗口置于前面；不能与状态“最小化”组合使用。如果为 false，则按 Z 轴顺序将下一个窗口移到前面；不能与状态“全屏”结合使用或“maximized”的值。

    • 高度

      编号（选填）

      要将窗口大小调整为以像素为单位的高度。对于面板，此值会被忽略。

    • 左侧

      编号（选填）

      要将窗口移动到的距离屏幕左边缘的偏移量（以像素为单位）。对于面板，此值会被忽略。

    • 州

      WindowState（可选）

      窗口的新状态。“最小化”“最大化”和“全屏”状态不能与“left”“top”“width”或“height”结合使用。

    • 顶部

      编号（选填）

      将窗口移动到屏幕顶部边缘的偏移量（以像素为单位）。对于面板，此值会被忽略。

    • width

      编号（选填）

      要将窗口大小调整为以像素为单位的宽度。对于面板，此值会被忽略。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (window: Window) => void

返回

  • Promise&lt;Window&gt;

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

事件

onBoundsChanged

Chrome 86 及更高版本 
chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

调整窗口大小时触发；只有在提交新边界时才会分派此事件，而不会针对正在进行的更改分派。

参数

  • callback

    函数

    callback 参数如下所示： 

    (window: Window) => void

onCreated

chrome.windows.onCreated.addListener(
  callback: function,
  filters?: object,
)

在创建窗口时触发。

参数

  • callback

    函数

    Chrome 46 及更高版本

    callback 参数如下所示： 

    (window: Window) => void

    • 窗口

      窗口

      所创建窗口的详细信息。

  • 过滤条件

    对象（可选）

    • windowTypes

      WindowType[]

      正在创建的窗口类型必须满足哪些条件。默认情况下，它满足 ['normal', 'popup']。

onFocusChanged

chrome.windows.onFocusChanged.addListener(
  callback: function,
  filters?: object,
)

在当前聚焦的窗口发生变化时触发。如果所有 Chrome 窗口都已失去焦点，则返回 chrome.windows.WINDOW_ID_NONE。注意：在某些 Linux 窗口管理器中，WINDOW_ID_NONE 始终会在切换 Chrome 窗口时立即发送。

参数

  • callback

    函数

    Chrome 46 及更高版本

    callback 参数如下所示： 

    (windowId: number) => void

    • windowId

      number

      新聚焦窗口的 ID。

  • 过滤条件

    对象（可选）

    • windowTypes

      WindowType[]

      要移除的窗口类型必须满足的条件。默认情况下，它满足 ['normal', 'popup']。

onRemoved

chrome.windows.onRemoved.addListener(
  callback: function,
  filters?: object,
)

移除（关闭）窗口时触发。

参数

  • callback

    函数

    Chrome 46 及更高版本

    callback 参数如下所示： 

    (windowId: number) => void

    • windowId

      number

      已移除的窗口的 ID。

  • 过滤条件

    对象（可选）

    • windowTypes

      WindowType[]

      要移除的窗口类型必须满足的条件。默认情况下，它满足 ['normal', 'popup']。