chrome.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() の呼び出しが含まれているとします。最上位のウィンドウが何であれ、現在のウィンドウは呼び出しを行ったページを含むウィンドウです。

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

例

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

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

型

CreateType

Chrome 44 以降

作成するブラウザ ウィンドウのタイプを指定します。「panel」は非推奨となり、Chrome OS の既存の許可リストに登録された拡張機能でのみ使用できます。

列挙型

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

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

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

QueryOptions

Chrome 88 以降

プロパティ

  • 入力する

    ブール値（省略可）

    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

    文字列 省略可

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

  • state

    WindowState 省略可

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

  • タブ

    Tab[] 省略可

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

  • 上

    number 省略可

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

  • type

    WindowType 省略可

    ブラウザ ウィンドウの種類。

  • 幅

    number 省略可

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

WindowState

Chrome 44 以降

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

列挙型

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

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

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

「fullscreen」
全画面ウィンドウの状態。

「locked-fullscreen」
ロックされた全画面表示ウィンドウの状態。この全画面表示状態はユーザー操作で終了できず、Chrome OS の許可リストに登録された拡張機能でのみ使用できます。

WindowType

Chrome 44 以降

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

列挙型

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

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

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

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

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

プロパティ

WINDOW_ID_CURRENT

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

値

-2

WINDOW_ID_NONE

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

値

-1

メソッド

create()

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

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

パラメータ

  • createData

    オブジェクト 省略可

    • 手厚い支援

      ブール値（省略可）

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

    • height

      number 省略可

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

    • シークレット

      ブール値（省略可）

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

    • 左

      number 省略可

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

    • setSelfAsOpener

      ブール値（省略可）

      Chrome 64 以降

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

    • state

      WindowState 省略可

      Chrome 44 以降

      ウィンドウの初期状態。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 とみなされます。デフォルトでは [新しいタブ] ページに設定されています。

    • 幅

      number 省略可

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

戻り値

  • Promise<Window | undefined>

    Chrome 88 以降

get()

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

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

パラメータ

  • windowId

    数値

  • queryOptions

    QueryOptions 省略可

    Chrome 88 以降

戻り値

  • Promise<Window>

    Chrome 88 以降

getAll()

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

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

パラメータ

戻り値

  • Promise<Window[]>

    Chrome 88 以降

getCurrent()

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

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

パラメータ

戻り値

  • Promise<Window>

    Chrome 88 以降

getLastFocused()

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

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

パラメータ

戻り値

  • Promise<Window>

    Chrome 88 以降

remove()

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

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

パラメータ

  • windowId

    数値

戻り値

  • Promise<void>

    Chrome 88 以降

update()

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

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

パラメータ

  • windowId

    数値

  • updateInfo

    オブジェクト

    • drawAttention

      ブール値（省略可）

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

    • 手厚い支援

      ブール値（省略可）

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

    • height

      number 省略可

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

    • 左

      number 省略可

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

    • state

      WindowState 省略可

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

    • 上

      number 省略可

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

    • 幅

      number 省略可

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

戻り値

  • Promise<Window>

    Chrome 88 以降

イベント

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

      数値

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

  • フィルタ

    オブジェクト 省略可

    • windowTypes

      WindowType[]

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

onRemoved

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

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

パラメータ

  • callback

    関数

    Chrome 46 以降

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

    (windowId: number) => void

    • windowId

      数値

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

  • フィルタ

    オブジェクト 省略可

    • windowTypes

      WindowType[]

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