chrome.app.window

说明

使用 chrome.app.window API 创建窗口。窗口有一个可选框架，其中包含标题栏和大小控件。它们不与任何 Chrome 浏览器窗口相关联。如需查看这些选项的演示，请参阅窗口状态示例。

类型

AppWindow

属性

• contentWindow

  窗口

  所创建子项的 JavaScript“window”对象。

• id

  字符串

  创建窗口时使用的 ID。

• innerBounds

  边界

  窗口内容的位置、大小和约束条件，不包括窗口装饰。此属性是 Chrome 36 中的新属性。

• outerBounds

  边界

  窗口的位置、大小和限制，包括窗口装饰（例如标题栏和框架）。此属性是 Chrome 36 中的新属性。

• clearAttention

  void

  清除对窗口的关注。

  clearAttention 函数如下所示：

  () => {...}

• 关闭

  void

  关闭窗口。

  close 函数如下所示：

  () => {...}

• drawAttention

  void

  将焦点移至窗口。

  drawAttention 函数如下所示：

  () => {...}

• 焦点

  void

  聚焦于窗口。

  focus 函数如下所示：

  () => {...}

• 全屏

  void

  将窗口全屏显示。

  用户可以通过按 ESC 键来恢复窗口。应用可以通过请求 app.window.fullscreen.overrideEsc 权限，并在 keydown 和 keyup 处理程序中调用 .preventDefault() 来取消事件，从而防止在按下 ESC 键时退出全屏状态，如下所示：

  window.onkeydown = window.onkeyup = function(e) { if (e.keyCode == 27 /* ESC *\/) { e.preventDefault(); } };

  请注意，window.fullscreen() 会导致整个窗口进入全屏模式，并且不需要用户手势。HTML5 全屏 API 也可用于进入全屏模式（如需了解详情，请参阅 Web API）。

  fullscreen 函数如下所示：

  () => {...}

• getBounds

  void

  已弃用

  请使用 innerBounds 或 outerBounds。

  以 ContentBounds 对象的形式获取窗口的内部边界。

  getBounds 函数如下所示：

  () => {...}

  • 返回

    ContentBounds

• 隐藏

  void

  隐藏窗口。如果窗口已隐藏，则不执行任何操作。

  hide 函数如下所示：

  () => {...}

• isAlwaysOnTop

  void

  窗口是否始终置顶？

  isAlwaysOnTop 函数如下所示：

  () => {...}

  • 返回

    布尔值

• isFullscreen

  void

  窗口是否全屏？如果窗口在创建时即为全屏，或通过 AppWindow 或 HTML5 全屏 API 设为全屏，则此值为 true。

  isFullscreen 函数如下所示：

  () => {...}

  • 返回

    布尔值

• isMaximized

  void

  窗口是否已最大化？

  isMaximized 函数如下所示：

  () => {...}

  • 返回

    布尔值

• isMinimized

  void

  窗口是否已最小化？

  isMinimized 函数如下所示：

  () => {...}

  • 返回

    布尔值

• maximize

  void

  最大化窗口。

  maximize 函数如下所示：

  () => {...}

• 最小化

  void

  最小化窗口。

  minimize 函数如下所示：

  () => {...}

• moveTo

  void

  自 Chrome 43 起已弃用

  使用 outerBounds。

  将窗口移至位置 (left, top)。

  moveTo 函数如下所示：

  (left: number, top: number) => {...}

  • 向左

    数值

  • 顶部

    数值

• resizeTo

  void

  自 Chrome 43 起已弃用

  使用 outerBounds。

  将窗口大小调整为 widthxheight 像素。

  resizeTo 函数如下所示：

  (width: number, height: number) => {...}

  • width

    数值

  • 高度

    数值

• 恢复

  void

  恢复窗口，退出最大化、最小化或全屏状态。

  restore 函数如下所示：

  () => {...}

• setAlwaysOnTop

  void

  设置窗口是否应保持在大多数其他窗口之上。需要 alwaysOnTopWindows 权限。

  setAlwaysOnTop 函数如下所示：

  (alwaysOnTop: boolean) => {...}

  • alwaysOnTop

    布尔值

• setBounds

  void

  已弃用

  请使用 innerBounds 或 outerBounds。

  设置窗口的内部边界。

  setBounds 函数如下所示：

  (bounds: ContentBounds) => {...}

  • bounds

    ContentBounds

• setVisibleOnAllWorkspaces

  void

  设置是否在所有工作区中显示该窗口。（仅适用于支持此功能的平台）。

  setVisibleOnAllWorkspaces 函数如下所示：

  (alwaysVisible: boolean) => {...}

  • alwaysVisible

    布尔值

• 显示

  void

  显示窗口。如果窗口已可见，则不执行任何操作。如果 focused 设置为 true 或省略，则聚焦窗口。

  show 函数如下所示：

  (focused?: boolean) => {...}

  • 专注

    布尔值 （可选）

Bounds

属性

• 高度

  数值

  此属性可用于读取或写入内容或窗口的当前高度。

• 向左

  数值

  此属性可用于读取或写入内容或窗口的当前 X 坐标。

• maxHeight

  number 可选

  此属性可用于读取或写入内容或窗口的当前最大高度。值为 null 表示“未指定”。

• maxWidth

  number 可选

  此属性可用于读取或写入内容或窗口的当前最大宽度。值为 null 表示“未指定”。

• minHeight

  number 可选

  此属性可用于读取或写入内容或窗口的当前最小高度。值为 null 表示“未指定”。

• minWidth

  number 可选

  此属性可用于读取或写入内容或窗口的当前最小宽度。值为 null 表示“未指定”。

• 顶部

  数值

  此属性可用于读取或写入内容或窗口的当前 Y 坐标。

• width

  数值

  此属性可用于读取或写入内容或窗口的当前宽度。

• setMaximumSize

  void

  设置内容或窗口的大小上限。最大宽度或高度可设置为 null，以移除限制。值为 undefined 将使限制条件保持不变。

  setMaximumSize 函数如下所示：

  (maxWidth: number, maxHeight: number) => {...}

  • maxWidth

    数值

  • maxHeight

    数值

• setMinimumSize

  void

  设置内容或窗口的最小尺寸限制。您可以将最小宽度或高度设置为 null，以移除此限制。值为 undefined 将使限制条件保持不变。

  setMinimumSize 函数如下所示：

  (minWidth: number, minHeight: number) => {...}

  • minWidth

    数值

  • minHeight

    数值

• setPosition

  void

  设置内容或窗口的左侧和顶部位置。

  setPosition 函数如下所示：

  (left: number, top: number) => {...}

  • 向左

    数值

  • 顶部

    数值

• setSize

  void

  设置内容或窗口的宽度和高度。

  setSize 函数如下所示：

  (width: number, height: number) => {...}

  • width

    数值

  • 高度

    数值

BoundsSpecification

属性

• 高度

  number 可选

  内容或窗口的高度。

• 向左

  number 可选

  内容或窗口的 X 坐标。

• maxHeight

  number 可选

  内容或窗口的最大高度。

• maxWidth

  number 可选

  内容或窗口的最大宽度。

• minHeight

  number 可选

  内容或窗口的最小高度。

• minWidth

  number 可选

  内容或窗口的最小宽度。

• 顶部

  number 可选

  内容或窗口的 Y 坐标。

• width

  number 可选

  内容或窗口的宽度。

ContentBounds

属性

• 高度

  number 可选

• 向左

  number 可选

• 顶部

  number 可选

• width

  number 可选

CreateWindowOptions

属性

• alwaysOnTop

  布尔值 （可选）

  如果为 true，则该窗口将保持在大多数其他窗口之上。如果存在多个此类窗口，则当前获得焦点的窗口将位于前台。需要 alwaysOnTopWindows 权限。默认值为 false。

  在窗口创建后，对其调用 setAlwaysOnTop() 即可更改此属性。

• bounds

  ContentBounds 可选

  已弃用

  请使用 innerBounds 或 outerBounds。

  窗口中内容的大小和位置（不包括标题栏）。如果还指定了 ID，并且之前已显示具有匹配 ID 的窗口，则系统会改用窗口的记忆边界。

• 专注

  布尔值 （可选）

  如果为 true，则窗口在创建时将获得焦点。默认值为 true。

• 帧

  字符串 | FrameOptions 可选

  框架类型：none 或 chrome（默认为 chrome）。对于 none，-webkit-app-region CSS 属性可用于为应用窗口应用可拖动性。-webkit-app-region: drag 可用于将区域标记为可拖动。no-drag 可用于在嵌套元素上停用此样式。

  FrameOptions 是 M36 中的新功能。

• 已隐藏

  布尔值 （可选）

  如果为 true，则窗口将在隐藏状态下创建。在窗口创建完成后，调用 show() 即可显示该窗口。默认值为 false。

• 图标

  字符串 可选

  Chrome 54 及更高版本

  窗口图标的网址。当 showInShelf 设为 true 时，窗口可以有自己的图标。该网址应为全局网址或扩展程序本地网址。

• id

  字符串 可选

  用于标识窗口的 ID。此 ID 将用于记住窗口的大小和位置，并在稍后打开具有相同 ID 的窗口时恢复该几何图形。如果创建具有给定 ID 的窗口时，已存在具有相同 ID 的另一个窗口，则系统会聚焦于当前打开的窗口，而不是创建新窗口。

• innerBounds

  BoundsSpecification 可选

  用于指定窗口内容（不包括窗口装饰）的初始位置、初始大小和限制。如果还指定了 id，并且之前显示过具有匹配 id 的窗口，则系统会改用记住的边界。

  请注意，内边界和外边界之间的内边距由操作系统决定。因此，为 innerBounds 和 outerBounds 设置相同的 bounds 属性会导致错误。

  此属性是 Chrome 36 中的新属性。

• maxHeight

  number 可选

  已弃用

  请使用 innerBounds 或 outerBounds。

  窗口的最大高度。

• maxWidth

  number 可选

  已弃用

  请使用 innerBounds 或 outerBounds。

  窗口的最大宽度。

• minHeight

  number 可选

  已弃用

  请使用 innerBounds 或 outerBounds。

  窗口的最小高度。

• minWidth

  number 可选

  已弃用

  请使用 innerBounds 或 outerBounds。

  窗口的最小宽度。

• outerBounds

  BoundsSpecification 可选

  用于指定窗口（包括标题栏和框架等窗口装饰）的初始位置、初始大小和约束条件。如果还指定了 id，并且之前显示过具有匹配 id 的窗口，则系统会改用记住的边界。

  请注意，内边界和外边界之间的内边距由操作系统决定。因此，为 innerBounds 和 outerBounds 设置相同的 bounds 属性会导致错误。

  此属性是 Chrome 36 中的新属性。

• resizable

  布尔值 （可选）

  如果为 true，则用户可以调整窗口大小。默认值为 true。

• showInShelf

  布尔值 （可选）

  Chrome 54 及更高版本

  如果为 true，则该窗口将有自己的任务栏图标。否则，该窗口将与该应用关联的其他窗口一起在任务栏中分组。默认值为 false。如果 showInShelf 设为 true，您需要为窗口指定一个 ID。

• 单例

  布尔值 （可选）

  已弃用

  不再支持多个窗口使用同一 ID。

  默认情况下，如果您为窗口指定了 ID，则只有在不存在具有相同 ID 的其他窗口时，系统才会创建该窗口。如果已存在具有相同 ID 的窗口，则会改为激活该窗口。如果您确实想创建多个具有相同 ID 的窗口，可以将此属性设置为 false。

• 州

  State（州/省/自治区/直辖市）可选

  窗口的初始状态，允许在创建时即处于全屏、最大化或最小化状态。默认值为“normal”。

• 类型

  WindowType 可选

  Chrome 45 及更高版本 自 Chrome 69 起已弃用

  所有应用窗口都使用“shell”窗口类型

  要创建的窗口类型。

• visibleOnAllWorkspaces

  布尔值 （可选）

  如果为 true 且平台支持，则窗口将在所有工作区中可见。

FrameOptions

属性

• activeColor

  字符串 可选

  允许设置窗口处于活动状态时的边框颜色。仅当框架类型为 chrome 时，框架着色才可用。

  仅当框架类型为 chrome 时，框架着色才可用。

  Chrome 36 中新增了框架着色功能。

• 颜色

  字符串 可选

  允许设置边框颜色。仅当框架类型为 chrome 时，框架着色才可用。

  Chrome 36 中新增了框架着色功能。

• inactiveColor

  字符串 可选

  允许将窗口处于非活动状态时的边框颜色设置为与活动状态时的颜色不同。仅当框架类型为 chrome 时，框架着色才可用。

  inactiveColor 必须与 color 结合使用。

  Chrome 36 中新增了框架着色功能。

• 类型

  字符串 可选

  帧类型：none 或 chrome（默认为 chrome）。

  对于 none，-webkit-app-region CSS 属性可用于为应用窗口应用可拖动性。

  -webkit-app-region: drag 可用于将区域标记为可拖动。no-drag 可用于在嵌套元素上停用此样式。

State

窗口的状态：正常、全屏、最大化、最小化。

枚举

"normal"

"fullscreen"

"maximized"

"minimized"

WindowType

Chrome 45 及更高版本

指定要创建的窗口类型。

枚举

"shell"
默认窗口类型。

“panel”
操作系统管理的窗口（已弃用）。

方法

canSetVisibleOnAllWorkspaces()

chrome.app.window.canSetVisibleOnAllWorkspaces(): boolean

当前平台是否支持在所有工作区中显示窗口。

返回

• 布尔值

create()

Promise

chrome.app.window.create(
  url: string,
  options?: CreateWindowOptions,
  callback?: function,
): Promise<AppWindow>

您可以通过多种不同的方式指定窗口的大小和位置。最简单的选项是完全不指定任何内容，在这种情况下，系统将使用默认大小和取决于平台的位置。

如需设置窗口的位置、大小和限制，请使用 innerBounds 或 outerBounds 属性。内部边界不包括窗口装饰。外边界包括窗口的标题栏和框架。请注意，内边界和外边界之间的内边距由操作系统决定。因此，为内部和外部边界设置相同的属性会被视为错误（例如，同时设置 innerBounds.left 和 outerBounds.left）。

如需自动记住窗口的位置，您可以为其指定 ID。如果窗口有 ID，则每当窗口移动或调整大小时，系统都会使用此 ID 来记住窗口的大小和位置。随后，当再次打开具有相同 ID 的窗口时，系统会使用此大小和位置，而不是指定的边界。如果您需要在非默认位置打开具有 ID 的窗口，可以先将其隐藏，然后将其移至所需位置，最后再显示。

参数

• url

  字符串

• 选项

  CreateWindowOptions 可选

• callback

  函数可选

  callback 参数如下所示：

  (createdWindow: AppWindow) => void

  • createdWindow

    AppWindow

返回

• Promise<AppWindow>

  Chrome 117 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

current()

chrome.app.window.current(): AppWindow | undefined

返回当前脚本上下文（即 JavaScript“window”对象）的 AppWindow 对象。您也可以在另一个页面的脚本上下文的句柄上调用此方法，例如：otherWindow.chrome.app.window.current()。

返回

• AppWindow | undefined

get()

chrome.app.window.get(
  id: string,
): AppWindow | undefined

获取具有给定 ID 的 AppWindow。如果不存在具有给定 ID 的窗口，则返回 null。此方法是 Chrome 33 中的新方法。

参数

• id

  字符串

返回

• AppWindow | undefined

getAll()

chrome.app.window.getAll(): AppWindow[]

获取当前创建的所有应用窗口的数组。此方法是 Chrome 33 中的新方法。

返回

• AppWindow[]

事件

onBoundsChanged

chrome.app.window.onBoundsChanged.addListener(
  callback: function,
)

在窗口大小调整时触发。

参数

• callback

  函数

  callback 参数如下所示：

  () => void

onClosed

chrome.app.window.onClosed.addListener(
  callback: function,
)

在窗口关闭时触发。请注意，您应该从正在关闭的窗口以外的窗口（例如后台页面）监听此事件。这是因为，在触发事件时，要关闭的窗口将处于销毁过程中，这意味着窗口脚本上下文中的部分 API 将无法正常运行。

参数

• callback

  函数

  callback 参数如下所示：

  () => void

onFullscreened

chrome.app.window.onFullscreened.addListener(
  callback: function,
)

在窗口全屏显示时（通过 AppWindow 或 HTML5 API）触发。

参数

• callback

  函数

  callback 参数如下所示：

  () => void

onMaximized

chrome.app.window.onMaximized.addListener(
  callback: function,
)

在窗口最大化时触发。

参数

• callback

  函数

  callback 参数如下所示：

  () => void

onMinimized

chrome.app.window.onMinimized.addListener(
  callback: function,
)

在窗口最小化时触发。

参数

• callback

  函数

  callback 参数如下所示：

  () => void

onRestored

chrome.app.window.onRestored.addListener(
  callback: function,
)

窗口从最小化或最大化状态恢复时触发。

参数

• callback

  函数

  callback 参数如下所示：

  () => void