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

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

例

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

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

型

CreateType

Chrome 44 以降

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

Enum

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

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

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

QueryOptions

Chrome 88 以降

プロパティ

• 入力

  ブール値（省略可）

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

• windowTypes

  WindowType[] 省略可

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

Window

プロパティ

• alwaysOnTop

  boolean

  ウィンドウを常に上部に表示するかどうかを設定します。

• 手厚い支援

  boolean

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

• 身長

  number（省略可）

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

• id

  number（省略可）

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

• シークレット モード

  boolean

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

• 左

  number（省略可）

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

• sessionId

  string（省略可）

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

• state

  WindowState 省略可

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

• タブ

  Tab[] 省略可

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

• 上

  number（省略可）

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

• タイプ

  WindowType 省略可

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

• 幅

  number（省略可）

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

WindowState

Chrome 44 以降

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

Enum

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

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

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

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

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

WindowType

Chrome 44 以降

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

Enum

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

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

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

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

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

プロパティ

WINDOW_ID_CURRENT

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

値

-2

WINDOW_ID_NONE

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

値

-1

Methods

create()

Promise

chrome.windows.create(
  createData?: object,
  callback?: function,
)

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

パラメータ

• createData

  オブジェクト 省略可

  • 手厚い支援

    ブール値（省略可）

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

  • 身長

    number（省略可）

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

  • シークレット モード

    ブール値（省略可）

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

  • 左

    number（省略可）

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

  • setSelfAsOpener

    ブール値（省略可）

    Chrome 64 以降

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

  • state

    WindowState 省略可

    Chrome 44 以降

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

  • tabId

    number（省略可）

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

  • 上

    number（省略可）

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

  • タイプ

    CreateType 省略可

    作成するブラウザ ウィンドウの種類を指定します。

  • URL

    string|string[] optional

    ウィンドウ内にタブとして開く URL または URL の配列。完全修飾 URL には、「www.google.com」ではなく「http://www.google.com」を指定してください。完全修飾でない URL は、拡張機能内での相対 URL と見なされます。デフォルトは新しいタブページです。

  • 幅

    number（省略可）

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

• callback

  関数（省略可）

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

  (window?: Window)=>void

  • クリックします。

    期間 省略可

    作成されたウィンドウの詳細が含まれます。

戻り値

• Promise<Window|未定義>

  Chrome 88 以降

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

get()

Promise

chrome.windows.get(
  windowId: number,
  queryOptions?: QueryOptions,
  callback?: function,
)

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

パラメータ

• windowId

  数値

• queryOptions

  QueryOptions 省略可

  Chrome 88 以降
• callback

  関数（省略可）

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

  (window: Window)=>void

  • クリックします。

    窓

戻り値

• Promise<Window>

  Chrome 88 以降

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

getAll()

Promise

chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
)

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

パラメータ

• queryOptions

  QueryOptions 省略可

  Chrome 88 以降
• callback

  関数（省略可）

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

  (windows: Window[])=>void

  • 窓

    ウィンドウ[]

戻り値

• Promise<Window[]>

  Chrome 88 以降

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

getCurrent()

Promise

chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
)

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

パラメータ

• queryOptions

  QueryOptions 省略可

  Chrome 88 以降
• callback

  関数（省略可）

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

  (window: Window)=>void

  • クリックします。

    窓

戻り値

• Promise<Window>

  Chrome 88 以降

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

getLastFocused()

Promise

chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
)

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

パラメータ

• queryOptions

  QueryOptions 省略可

  Chrome 88 以降
• callback

  関数（省略可）

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

  (window: Window)=>void

  • クリックします。

    窓

戻り値

• Promise<Window>

  Chrome 88 以降

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

remove()

Promise

chrome.windows.remove(
  windowId: number,
  callback?: function,
)

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

パラメータ

• windowId

  数値

• callback

  関数（省略可）

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

  ()=>void

戻り値

• Promise<void>

  Chrome 88 以降

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

update()

Promise

chrome.windows.update(
  windowId: number,
  updateInfo: object,
  callback?: function,
)

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

パラメータ

• windowId

  数値

• updateInfo

  オブジェクト

  • drawAttention

    ブール値（省略可）

    true の場合、フォーカスされているウィンドウを変更せずに、ユーザーの注意をウィンドウに向けるようにウィンドウを表示します。この効果は、ユーザーがウィンドウにフォーカスを変更するまで継続します。ウィンドウにすでにフォーカスがある場合、このオプションは無効です。以前の drawAttention リクエストをキャンセルするには、false に設定します。

  • 手厚い支援

    ブール値（省略可）

    true の場合、ウィンドウが前面に表示されます。「最小化」状態と組み合わせることはできません。false の場合、Z オーダーの次のウィンドウが前面に移動します。「全画面表示」や「最大化」の状態と組み合わせることはできません。

  • 身長

    number（省略可）

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

  • 左

    number（省略可）

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

  • state

    WindowState 省略可

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

  • 上

    number（省略可）

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

  • 幅

    number（省略可）

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

• callback

  関数（省略可）

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

  (window: Window)=>void

  • クリックします。

    窓

戻り値

• Promise<Window>

  Chrome 88 以降

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

イベント

onBoundsChanged

Chrome 86 以降

chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

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

パラメータ

• 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 ウィンドウ マネージャーでは、Chrome ウィンドウを切り替える直前に WINDOW_ID_NONE が常に送信されます。

パラメータ

• 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'] を満たしています。