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 函数如下所示:

    () => {...}

  • 隐藏

    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) => {...}

  • 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
    <ph type="x-smartling-placeholder"></ph> 已弃用

    使用 innerBounds 或 outerBounds。

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

  • 专注

    布尔值(可选)

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

  • string |FrameOptions 可选

    帧类型:nonechrome(默认为 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

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

    请注意,内外边界之间的内边距由操作系统决定。因此,为 innerBoundsouterBounds 设置相同的 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

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

    请注意,内外边界之间的内边距由操作系统决定。因此,为 innerBoundsouterBounds 设置相同的 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 中的框架着色是新功能。

  • 类型

    字符串(可选)

    帧类型:nonechrome(默认为 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,
)

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

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

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

参数

返回

  • Promise&lt;AppWindow&gt;

    Chrome 117 及更高版本

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

current()

chrome.app.window.current()

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

返回

get()

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

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

参数

  • id

    字符串

返回

getAll()

chrome.app.window.getAll()

获取一个包含当前创建的所有应用窗口的数组。此方法在 Chrome 33 中是新功能。

返回

事件

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