chrome.app.window

说明

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

类型

AppWindow

属性

• contentWindow

  窗口

  JavaScript“窗口”对象。

• id

  字符串

  创建窗口时所用的 ID。

• innerBounds

  边界

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

• outerBounds

  边界

  窗口的位置、大小和约束条件，包括标题栏和框架等窗口装饰。这是 Chrome 36 中的新属性。

• clearAttention

  void

  吸引用户注意窗口。

  clearAttention 函数如下所示：

  () => {...}

• 关闭

  void

  关闭窗口。

  close 函数如下所示：

  () => {...}

• drawAttention

  void

  注意窗口。

  drawAttention 函数如下所示：

  () => {...}

• 焦点

  void

  将焦点置于窗口。

  focus 函数如下所示：

  () => {...}

• 全屏

  void

  全屏显示窗口。

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

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

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

  fullscreen 函数如下所示：

  () => {...}

• getBounds

  void

  <ph type="x-smartling-placeholder"></ph> 已弃用

  使用 innerBounds 或 outerBounds。

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

  getBounds 函数如下所示：

  () => {...}

  • 返回

    ContentBounds

• 隐藏

  void

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

  hide 函数如下所示：

  () => {...}

• isAlwaysOnTop

  void

  窗口始终位于顶部吗？

  isAlwaysOnTop 函数如下所示：

  () => {...}

  • 返回

    布尔值

• isFullscreen

  void

  窗口是否为全屏窗口？如果窗口是通过 AppWindow 或 HTML5 全屏 API 创建为全屏窗口或设为全屏，结果将为 true。

  isFullscreen 函数如下所示：

  () => {...}

  • 返回

    布尔值

• isMaximized

  void

  窗口是否已最大化？

  isMaximized 函数如下所示：

  () => {...}

  • 返回

    布尔值

• isMinimized

  void

  窗口是否已最小化？

  isMinimized 函数如下所示：

  () => {...}

  • 返回

    布尔值

• 最大化

  void

  最大化窗口。

  maximize 函数如下所示：

  () => {...}

• 最小化

  void

  最小化窗口。

  minimize 函数如下所示：

  () => {...}

• moveTo

  void

  <ph type="x-smartling-placeholder"></ph> 自 Chrome 43 起弃用

  使用 outerBounds。

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

  moveTo 函数如下所示：

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

  • 左侧

    number

  • 顶部

    number

• resizeTo

  void

  <ph type="x-smartling-placeholder"></ph> 自 Chrome 43 起弃用

  使用 outerBounds。

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

  resizeTo 函数如下所示：

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

  • width

    number

  • 高度

    number

• 恢复

  void

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

  restore 函数如下所示：

  () => {...}

• setAlwaysOnTop

  void

  设置窗口是否应位于大多数其他窗口的上方。需要 alwaysOnTopWindows 权限。

  setAlwaysOnTop 函数如下所示：

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

  • alwaysOnTop

    布尔值

• setBounds

  void

  <ph type="x-smartling-placeholder"></ph> 已弃用

  使用 innerBounds 或 outerBounds。

  设置窗口的内边界。

  setBounds 函数如下所示：

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

  • bounds

    ContentBounds

• setVisibleOnAllWorkspaces

  void

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

  setVisibleOnAllWorkspaces 函数如下所示：

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

  • alwaysVisible

    布尔值

• 显示

  void

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

  show 函数如下所示：

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

  • 专注

    布尔值（可选）

Bounds

属性

• 高度

  number

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

• 左侧

  number

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

• maxHeight

  编号（选填）

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

• maxWidth

  编号（选填）

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

• minHeight

  编号（选填）

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

• minWidth

  编号（选填）

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

• 顶部

  number

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

• width

  number

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

• setMaximumSize

  void

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

  setMaximumSize 函数如下所示：

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

  • maxWidth

    number

  • maxHeight

    number

• setMinimumSize

  void

  设置内容或窗口的最小尺寸约束条件。可以将最小宽度或高度设置为 null 以移除约束条件。如果值为 undefined，约束条件将保持不变。

  setMinimumSize 函数如下所示：

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

  • minWidth

    number

  • minHeight

    number

• setPosition

  void

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

  setPosition 函数如下所示：

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

  • 左侧

    number

  • 顶部

    number

• setSize

  void

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

  setSize 函数如下所示：

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

  • width

    number

  • 高度

    number

BoundsSpecification

属性

• 高度

  编号（选填）

  内容或窗口的高度。

• 左侧

  编号（选填）

  内容或窗口的 X 坐标。

• maxHeight

  编号（选填）

  内容或窗口的最大高度。

• maxWidth

  编号（选填）

  内容或窗口的最大宽度。

• minHeight

  编号（选填）

  内容或窗口的最小高度。

• minWidth

  编号（选填）

  内容或窗口的最小宽度。

• 顶部

  编号（选填）

  内容或窗口的 Y 坐标。

• width

  编号（选填）

  内容或窗口的宽度。

ContentBounds

属性

• 高度

  编号（选填）

• 左侧

  编号（选填）

• 顶部

  编号（选填）

• width

  编号（选填）

CreateWindowOptions

属性

• alwaysOnTop

  布尔值（可选）

  如果为 true，相应窗口将停留在大多数其他窗口的上方。如果存在多个这种类型的窗口，则当前聚焦的窗口将位于前台。需要 alwaysOnTopWindows 权限。默认值为 false。

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

• bounds

  ContentBounds 可选

  <ph type="x-smartling-placeholder"></ph> 已弃用

  使用 innerBounds 或 outerBounds。

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

• 专注

  布尔值（可选）

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

• 帧

  string |FrameOptions 可选

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

  M36 中新增了使用 FrameOptions 的功能。

• 已隐藏

  布尔值（可选）

  如果为 true，则创建该窗口时将处于隐藏状态。创建完成后，对窗口调用 show() 以显示该窗口。默认值为 false。

• 图标

  字符串（可选）

  Chrome 54 及更高版本

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

• id

  字符串（可选）

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

• innerBounds

  BoundsSpecification 可选

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

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

  这是 Chrome 36 中的新属性。

• maxHeight

  编号（选填）

  <ph type="x-smartling-placeholder"></ph> 已弃用

  使用 innerBounds 或 outerBounds。

  窗口的最大高度。

• maxWidth

  编号（选填）

  <ph type="x-smartling-placeholder"></ph> 已弃用

  使用 innerBounds 或 outerBounds。

  窗口的最大宽度。

• minHeight

  编号（选填）

  <ph type="x-smartling-placeholder"></ph> 已弃用

  使用 innerBounds 或 outerBounds。

  窗口的最小高度。

• minWidth

  编号（选填）

  <ph type="x-smartling-placeholder"></ph> 已弃用

  使用 innerBounds 或 outerBounds。

  窗口的最小宽度。

• outerBounds

  BoundsSpecification 可选

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

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

  这是 Chrome 36 中的新属性。

• 可调整大小

  布尔值（可选）

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

• showInShelf

  布尔值（可选）

  Chrome 54 及更高版本

  如果为 true，该窗口将有自己的任务栏图标。否则，该窗口会与与应用相关联的其他窗口归入此任务栏。默认值为 false。如果 showInShelf 设置为 true，则需要为窗口指定 ID。

• 单例

  布尔值（可选）

  <ph type="x-smartling-placeholder"></ph> 已弃用

  不再支持具有相同 ID 的多个窗口。

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

• 州

  州/省级行政区（可选）

  窗口的初始状态，允许创建时已全屏、最大化或最小化窗口。默认值为“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”

“全屏”

"maximized"

"最小化"

WindowType

Chrome 45 及更高版本

指定要创建的窗口类型。

枚举

"shell"
默认窗口类型。

"panel"
操作系统管理窗口（已弃用）。

方法

canSetVisibleOnAllWorkspaces()

chrome.app.window.canSetVisibleOnAllWorkspaces()

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

返回

• 布尔值

create()

<ph type="x-smartling-placeholder"></ph> 承诺

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

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

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

如需自动记住窗口的位置，您可以为其指定 ID。如果某个窗口具有 ID，每当该窗口被移动或调整大小时，该 ID 将用于记住该窗口的大小和位置。然后，在具有相同 ID 的窗口后续打开时，将使用此大小和位置，而不是指定边界。如果您需要在记忆的默认位置以外的位置打开一个具有 ID 的窗口，则可以将其隐藏，然后将其移至所需位置，然后显示该窗口。

参数

• 网址

  字符串

• 选项

  CreateWindowOptions 可选

• callback

  函数（可选）

  callback 参数如下所示：

  (createdWindow: AppWindow) => void

  • createdWindow

    AppWindow

返回

• Promise&lt;AppWindow&gt;

  Chrome 117 及更高版本

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

current()

chrome.app.window.current()

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

返回

• AppWindow |未定义

get()

chrome.app.window.get(
  id: string,
)

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

参数

• id

  字符串

返回

• AppWindow |未定义

getAll()

chrome.app.window.getAll()

获取一个包含当前创建的所有应用窗口的数组。此方法在 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