browser.windows

説明

chrome.windows API を使用してブラウザ ウィンドウを操作します。この API を使用して、ブラウザでウィンドウを作成、変更、再配置できます。

権限

リクエストされると、windows.Window には tabs.Tab オブジェクトの配列が含まれます。tabs.Tab の url、pendingUrl、title、favIconUrl プロパティにアクセスする必要がある場合は、マニフェストで "tabs" 権限を宣言する必要があります。次に例を示します。

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

コンセプトと使用方法

現在のウィンドウ

拡張機能システムの多くの関数は、オプションの windowId 引数を取ります。この引数のデフォルトは現在のウィンドウです。

現在のウィンドウは、現在実行中のコードを含むウィンドウです。これは、最前面のウィンドウやフォーカスされたウィンドウとは異なる場合があることに注意してください。

たとえば、拡張機能が 1 つの HTML ファイルからいくつかのタブまたはウィンドウを作成し、その HTML ファイルに tabs.query() の呼び出しが含まれているとします。現在のウィンドウとは、最上位のウィンドウが何であるかにかかわらず、呼び出しを行ったページを含むウィンドウです。

Service Worker の場合、現在のウィンドウの値は、最後にアクティブだったウィンドウにフォールバックします。状況によっては、バックグラウンド ページに現在のウィンドウがない場合があります。

例

この API を試すには、chrome-extension-samples リポジトリから windows API の例をインストールします。

2 つのウィンドウ（それぞれに 1 つのタブ）
2 つのウィンドウ。それぞれに 1 つのタブがあります。

型

CreateType

Chrome 44 以降 Chrome 148 以降の browser.*

作成するブラウザ ウィンドウの種類を指定します。「panel」は非推奨であり、ChromeOS の既存の許可リストに登録されている拡張機能でのみ使用できます。

列挙型

"normal"
ウィンドウを標準ウィンドウとして指定します。

"popup"
ウィンドウをポップアップ ウィンドウとして指定します。

"panel"
ウィンドウをパネルとして指定します。

QueryOptions

Chrome 88 以降 Chrome 148 以降の browser.*

プロパティ

  • 入力

    boolean 省略可

    true の場合、windows.Window オブジェクトには、tabs.Tab オブジェクトのリストを含む tabs プロパティがあります。Tab オブジェクトに url、pendingUrl、title、favIconUrl プロパティが含まれるのは、拡張機能のマニフェスト ファイルに "tabs" 権限が含まれている場合のみです。

  • windowTypes

    WindowType[] 省略可

    設定すると、返される windows.Window はそのタイプに基づいてフィルタされます。設定されていない場合、デフォルトのフィルタは ['normal', 'popup'] に設定されます。

Window

プロパティ

  • alwaysOnTop

    ブール値

    ウィンドウを常に最前面に表示するかどうか。

  • 手厚い支援

    ブール値

    ウィンドウが現在フォーカスされているウィンドウかどうか。

  • height

    number 省略可

    ウィンドウの高さ（フレームを含む、ピクセル単位）。状況によっては、ウィンドウに height プロパティが割り当てられないことがあります。たとえば、sessions API から閉じられたウィンドウをクエリする場合などです。

  • id

    number 省略可

    ウィンドウの ID。ウィンドウ ID はブラウザ セッション内で一意です。状況によっては、ウィンドウに ID プロパティが割り当てられないことがあります。たとえば、sessions API を使用してウィンドウをクエリする場合、セッション ID が存在する可能性があります。

  • シークレット

    ブール値

    ウィンドウがシークレット モードかどうか。

  • 左

    number 省略可

    画面の左端からのウィンドウのオフセット（ピクセル単位）。状況によっては、ウィンドウに left プロパティが割り当てられないことがあります。たとえば、sessions API から閉じられたウィンドウをクエリする場合などです。

  • sessionId

    文字列 省略可

    ウィンドウを一意に識別するために使用されるセッション ID。sessions API から取得されます。

  • state

    WindowState 省略可

    このブラウザ ウィンドウの状態。

  • tabs

    Tab[] 省略可

    ウィンドウ内の現在のタブを表す tabs.Tab オブジェクトの配列。

  • 上

    number 省略可

    画面の上端からのウィンドウのオフセット（ピクセル単位）。状況によっては、ウィンドウに top プロパティが割り当てられないことがあります。たとえば、sessions API から閉じられたウィンドウをクエリする場合などです。

  • type

    WindowType 省略可

    ブラウザ ウィンドウのタイプ。

  • width

    number 省略可

    ウィンドウの幅（フレームを含む、ピクセル単位）。状況によっては、ウィンドウに width プロパティが割り当てられないことがあります。たとえば、sessions API から閉じられたウィンドウをクエリする場合などです。

WindowState

Chrome 44 以降 Chrome 148 以降の browser.*

このブラウザ ウィンドウの状態。状況によっては、ウィンドウに state プロパティが割り当てられないことがあります。たとえば、sessions API から閉じられたウィンドウをクエリする場合などです。

列挙型

"normal"
通常のウィンドウ状態（最小化、最大化、全画面表示ではない）。

"minimized"
最小化されたウィンドウの状態。

"maximized"
最大化されたウィンドウの状態。

"fullscreen"
全画面表示のウィンドウ状態。

WindowType

Chrome 44 以降 Chrome 148 以降の browser.*

ブラウザ ウィンドウのタイプ。状況によっては、ウィンドウに type プロパティが割り当てられない場合があります。たとえば、sessions API から閉じられたウィンドウをクエリする場合などです。

列挙型

"normal"
通常のブラウザ ウィンドウ。

"popup"
ブラウザのポップアップ。

"panel"
この API では非推奨。Chrome アプリのパネルスタイルのウィンドウ。拡張機能は、自身のパネル ウィンドウのみを表示できます。

"app"
この API では非推奨。Chrome アプリ ウィンドウ。拡張機能は、自身のアプリのウィンドウのみを表示できます。

"devtools"
デベロッパー ツール ウィンドウ。

プロパティ

WINDOW_ID_CURRENT

現在のウィンドウを表す windowId 値。

値

-2

WINDOW_ID_NONE

Chrome ブラウザ ウィンドウがないことを表す windowId 値。

値

-1

メソッド

create()

browser.windows.create(
  createData?: object,
): Promise<Window | undefined>

オプションのサイズ、位置、デフォルトの URL を指定して、新しいブラウザ ウィンドウを作成（オープン）します。

パラメータ

  • createData

    オブジェクト（省略可）

    • 手厚い支援

      boolean 省略可

      true の場合、アクティブなウィンドウを開きます。false の場合、非アクティブなウィンドウを開きます。

    • height

      number 省略可

      新しいウィンドウの高さ（ピクセル単位、フレームを含む）。指定しない場合、デフォルトで自然な高さになります。

    • シークレット

      boolean 省略可

      新しいウィンドウをシークレット ウィンドウにするかどうか。

    • 左

      number 省略可

      画面の左端から新しいウィンドウを配置するピクセル数。指定しない場合、新しいウィンドウは、最後にフォーカスされたウィンドウから自然にオフセットされます。この値はパネルでは無視されます。

    • setSelfAsOpener

      boolean 省略可

      Chrome 64 以降 Chrome 148 以降の browser.*

      true の場合、新しく作成されたウィンドウの「window.opener」は呼び出し元に設定され、呼び出し元と同じ関連するブラウジング コンテキストの単位にあります。

    • state

      WindowState 省略可

      Chrome 44 以降 Chrome 148 以降の browser.*

      ウィンドウの初期状態。minimized、maximized、fullscreen の状態を left、top、width、height と組み合わせることはできません。

    • tabId

      number 省略可

      新しいウィンドウに追加するタブの ID。

    • 上

      number 省略可

      画面の上端から新しいウィンドウを配置する位置までのピクセル数。指定しない場合、新しいウィンドウは、最後にフォーカスされたウィンドウから自然にオフセットされます。この値はパネルでは無視されます。

    • type

      CreateType 省略可

      作成するブラウザ ウィンドウのタイプを指定します。

    • URL

      string | string[] 省略可

      ウィンドウでタブとして開く URL または URL の配列。完全修飾 URL には、スキームを含める必要があります（例: 「www.google.com」ではなく「http://www.google.com」）。完全修飾 URL ではない URL は、拡張機能内で相対 URL と見なされます。デフォルトは新しいタブページです。

    • width

      number 省略可

      新しいウィンドウの幅（ピクセル単位、フレームを含む）。指定しない場合、デフォルトで自然な幅になります。

戻り値

  • Promise<Window | undefined>

    Chrome 88 以降 Chrome 148 以降の browser.*

get()

browser.windows.get(
  windowId: number,
  queryOptions?: QueryOptions,
): Promise<Window>

ウィンドウの詳細を取得します。

パラメータ

  • windowId

    数値

  • queryOptions

    QueryOptions 省略可

    Chrome 88 以降 Chrome 148 以降の browser.*

戻り値

  • Promise<Window>

    Chrome 88 以降 Chrome 148 以降の browser.*

getAll()

browser.windows.getAll(
  queryOptions?: QueryOptions,
): Promise<Window[]>

すべてのウィンドウを取得します。

パラメータ

  • queryOptions

    QueryOptions 省略可

    Chrome 88 以降 Chrome 148 以降の browser.*

戻り値

  • Promise<Window[]>

    Chrome 88 以降 Chrome 148 以降の browser.*

getCurrent()

browser.windows.getCurrent(
  queryOptions?: QueryOptions,
): Promise<Window>

現在のウィンドウを取得します。

パラメータ

  • queryOptions

    QueryOptions 省略可

    Chrome 88 以降 Chrome 148 以降の browser.*

戻り値

  • Promise<Window>

    Chrome 88 以降 Chrome 148 以降の browser.*

getLastFocused()

browser.windows.getLastFocused(
  queryOptions?: QueryOptions,
): Promise<Window>

最後にフォーカスされたウィンドウ（通常は「最前面」のウィンドウ）を取得します。

パラメータ

  • queryOptions

    QueryOptions 省略可

    Chrome 88 以降 Chrome 148 以降の browser.*

戻り値

  • Promise<Window>

    Chrome 88 以降 Chrome 148 以降の browser.*

remove()

browser.windows.remove(
  windowId: number,
): Promise<void>

ウィンドウとその中のすべてのタブを削除（終了）します。

パラメータ

  • windowId

    数値

戻り値

  • Promise<void>

    Chrome 88 以降 Chrome 148 以降の browser.*

update()

browser.windows.update(
  windowId: number,
  updateInfo: object,
): Promise<Window>

ウィンドウのプロパティを更新します。変更するプロパティのみを指定します。指定されていないプロパティは変更されません。

パラメータ

  • windowId

    数値

  • updateInfo

    オブジェクト

    • drawAttention

      boolean 省略可

      true の場合、フォーカスされているウィンドウを変更せずに、ユーザーの注意をウィンドウに引き付ける方法でウィンドウが表示されます。この効果は、ユーザーがウィンドウにフォーカスを切り替えるまで持続します。ウィンドウにすでにフォーカスがある場合、このオプションは効果がありません。以前の drawAttention リクエストをキャンセルするには、false に設定します。

    • 手厚い支援

      boolean 省略可

      true の場合、ウィンドウを前面に表示します。状態「minimized」と組み合わせることはできません。false の場合、Z オーダーの次のウィンドウを前面に表示します。状態「fullscreen」または「maximized」と組み合わせることはできません。

    • height

      number 省略可

      ウィンドウのサイズ変更後の高さ（ピクセル単位）。この値はパネルでは無視されます。

    • 左

      number 省略可

      ウィンドウを移動する画面の左端からのオフセット（ピクセル単位）。この値はパネルでは無視されます。

    • state

      WindowState 省略可

      ウィンドウの新しい状態。「minimized」、「maximized」、「fullscreen」の状態を「left」、「top」、「width」、「height」と組み合わせることはできません。

    • 上

      number 省略可

      ウィンドウを移動する画面の上端からのオフセット（ピクセル単位）。この値はパネルでは無視されます。

    • width

      number 省略可

      ウィンドウのサイズ変更後の幅（ピクセル単位）。この値はパネルでは無視されます。

戻り値

  • Promise<Window>

    Chrome 88 以降 Chrome 148 以降の browser.*

イベント

onBoundsChanged

Chrome 86 以降 Chrome 148 以降の browser.* 
browser.windows.onBoundsChanged.addListener(
  callback: function,
)

ウィンドウのサイズが変更されたときに呼び出されます。このイベントは、新しい境界が commit されたときにのみディスパッチされ、進行中の変更に対してはディスパッチされません。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (window: Window) => void

onCreated

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

ウィンドウが作成されたときに呼び出されます。

パラメータ

  • callback

    関数

    Chrome 46 以降 Chrome 148 以降の browser.*

    callback パラメータは次のようになります。 

    (window: Window) => void

    • 窓

      窓

      作成されたウィンドウの詳細。

  • フィルタ

    オブジェクト（省略可）

    • windowTypes

      WindowType[]

      作成されるウィンドウのタイプが満たす必要がある条件。デフォルトでは ['normal', 'popup'] を満たします。

onFocusChanged

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

現在フォーカスされているウィンドウが変更されたときに呼び出されます。すべての Chrome ウィンドウがフォーカスを失った場合は chrome.windows.WINDOW_ID_NONE を返します。注: 一部の Linux ウィンドウ マネージャーでは、Chrome ウィンドウの切り替え直前に WINDOW_ID_NONE が常に送信されます。

パラメータ

  • callback

    関数

    Chrome 46 以降 Chrome 148 以降の browser.*

    callback パラメータは次のようになります。 

    (windowId: number) => void

    • windowId

      数値

      新しくフォーカスされたウィンドウの ID。

  • フィルタ

    オブジェクト（省略可）

    • windowTypes

      WindowType[]

      削除されるウィンドウのタイプが満たす必要がある条件。デフォルトでは ['normal', 'popup'] を満たします。

onRemoved

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

ウィンドウが削除（終了）されたときに呼び出されます。

パラメータ

  • callback

    関数

    Chrome 46 以降 Chrome 148 以降の browser.*

    callback パラメータは次のようになります。 

    (windowId: number) => void

    • windowId

      数値

      削除されたウィンドウの ID。

  • フィルタ

    オブジェクト（省略可）

    • windowTypes

      WindowType[]

      削除されるウィンドウのタイプが満たす必要がある条件。デフォルトでは ['normal', 'popup'] を満たします。