chrome.tabs

説明

chrome.tabs API を使用して、ブラウザのタブシステムを操作します。この API を使用すると、ブラウザのタブを作成、変更、並べ替えることができます。

Tabs API は、タブの操作と管理の機能を提供するだけでなく、タブの言語の検出、スクリーンショットの撮影、タブのコンテンツ スクリプトとの通信も可能です。

権限

ほとんどの機能は、使用するにあたって権限を必要としません。たとえば、新しいタブの作成、タブの再読み込み、別の URL への移動などです。

Tabs API を使用する際にデベロッパーが注意すべき権限は 3 つあります。

「tabs」権限

この権限では、chrome.tabs 名前空間へのアクセス権は付与されません。代わりに、拡張機能に tabs.Tab インスタンスの 4 つの機密情報プロパティ（url、pendingUrl、title、favIconUrl）に対して tabs.query() を呼び出す権限を付与します。

{
  "name": "My extension",
  ...
  "permissions": [
    "tabs"
  ],
  ...
}
ホスト権限

ホスト権限により、拡張機能は一致するタブの 4 つの機密性の高い tabs.Tab プロパティを読み取ってクエリできます。また、tabs.captureVisibleTab()、scripting.executeScript()、scripting.insertCSS()、scripting.removeCSS() などのメソッドを使用して、一致するタブと直接やり取りすることもできます。

{
  "name": "My extension",
  ...
  "host_permissions": [
    "http://*/*",
    "https://*/*"
  ],
  ...
}
「activeTab」権限

activeTab は、ユーザーの呼び出しに応じて、現在のタブに対する一時的なホスト権限を拡張機能に付与します。ホスト権限とは異なり、activeTab は警告をトリガーしません。

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

ユースケース

以降のセクションでは、一般的なユースケースについて説明します。

拡張機能のページを新しいタブで開く

拡張機能の一般的なパターンとして、拡張機能がインストールされたときに新しいタブでオンボーディング ページを開くことがあります。次の例はその方法を示しています。

background.js:

chrome.runtime.onInstalled.addListener(({reason}) => {
  if (reason === 'install') {
    chrome.tabs.create({
      url: "onboarding.html"
    });
  }
});

現在のタブを取得する

この例は、拡張機能のサービス ワーカーが現在フォーカスされているウィンドウ（Chrome ウィンドウがフォーカスされていない場合は、最後にフォーカスされたウィンドウ）からアクティブなタブを取得する方法を示しています。これは通常、ユーザーの現在のタブと考えることができます。

  async function getCurrentTab() {
    let queryOptions = { active: true, lastFocusedWindow: true };
    // `tab` will either be a `tabs.Tab` instance or `undefined`.
    let [tab] = await chrome.tabs.query(queryOptions);
    return tab;
  }


  function getCurrentTab(callback) {
    let queryOptions = { active: true, lastFocusedWindow: true };
    chrome.tabs.query(queryOptions, ([tab]) => {
      if (chrome.runtime.lastError)
      console.error(chrome.runtime.lastError);
      // `tab` will either be a `tabs.Tab` instance or `undefined`.
      callback(tab);
    });
  }

指定したタブをミュートする

この例は、拡張機能が特定のタブのミュート状態を切り替える方法を示しています。

  async function toggleMuteState(tabId) {
    const tab = await chrome.tabs.get(tabId);
    const muted = !tab.mutedInfo.muted;
    await chrome.tabs.update(tabId, {muted});
    console.log(`Tab ${tab.id} is ${muted ? "muted" : "unmuted"}`);
  }


  function toggleMuteState(tabId) {
    chrome.tabs.get(tabId, async (tab) => {
      let muted = !tab.mutedInfo.muted;
      await chrome.tabs.update(tabId, { muted });
      console.log(`Tab ${tab.id} is ${ muted ? "muted" : "unmuted" }`);
    });
  }

クリックしたときに現在のタブを最初の位置に移動する

この例は、ドラッグが進行中であるかどうかに関係なく、タブを移動する方法を示しています。この例では chrome.tabs.move を使用していますが、ドラッグ中にタブを変更する他の呼び出しにも同じ待機パターンを使用できます。

  chrome.tabs.onActivated.addListener(moveToFirstPosition);

  async function moveToFirstPosition(activeInfo) {
    try {
      await chrome.tabs.move(activeInfo.tabId, {index: 0});
      console.log("Success.");
    } catch (error) {
      if (error == "Error: Tabs cannot be edited right now (user may be dragging a tab).") {
        setTimeout(() => moveToFirstPosition(activeInfo), 50);
      } else {
        console.error(error);
      }
    }
  }


  chrome.tabs.onActivated.addListener(moveToFirstPositionMV2);

  function moveToFirstPositionMV2(activeInfo) {
    chrome.tabs.move(activeInfo.tabId, { index: 0 }, () => {
      if (chrome.runtime.lastError) {
        const error = chrome.runtime.lastError;
        if (error == "Error: Tabs cannot be edited right now (user may be dragging a tab).") {
          setTimeout(() => moveToFirstPositionMV2(activeInfo), 50);
        } else {
          console.error(error);
        }
      } else {
        console.log("Success.");
      }
    });
  }

選択したタブのコンテンツ スクリプトにメッセージを渡す

この例は、tabs.sendMessage() を使用して、特定のブラウザタブのコンテンツ スクリプトと拡張機能のサービス ワーカーが通信する方法を示しています。

function sendMessageToActiveTab(message) {
  const [tab] = await chrome.tabs.query({ active: true, lastFocusedWindow: true });
  const response = await chrome.tabs.sendMessage(tab.id, message);
  // TODO: Do something with the response.
}

拡張機能の例

Tabs API 拡張機能のデモについては、次のいずれかをご覧ください。

型

MutedInfo

Chrome 46 以降

タブのミュート状態と、最後の状態変更の理由。

プロパティ

  • extensionId

    文字列 省略可

    ミュート状態を変更した拡張機能の ID。拡張機能がミュート状態の最後の変更の理由でない場合は設定されません。

  • ミュート中

    ブール値

    タブがミュートされているかどうか（音声を再生しないように設定されているかどうか）。タブで音声が再生されていない場合や、現在再生されていない場合でも、タブがミュートされていることがあります。「ミュート」音声インジケーターが表示されているかどうかと同等です。

  • reason

    MutedInfoReason 省略可

    タブがミュートまたはミュート解除された理由。タブのミュート状態が一度も変更されていない場合は設定されません。

MutedInfoReason

Chrome 46 以降

ミュート状態の変更を引き起こしたイベント。

列挙型

「user」
ユーザー入力アクションでミュート状態が設定されました。

"capture"
タブのキャプチャが開始され、強制的にミュート状態が変更されました。

「extension」
extensionId フィールドで識別される拡張機能が、ミュート状態を設定しました。

Tab

プロパティ

  • アクティブ

    ブール値

    タブがウィンドウでアクティブかどうか。必ずしもウィンドウがフォーカスされていることを意味するわけではありません。

  • Audible

    ブール値（省略可）

    Chrome 45 以降

    過去数秒間にタブで音声が再生されたかどうか（ミュートされている場合は聞こえないことがあります）。「スピーカー音声」インジケーターが表示されているかどうかと同等です。

  • autoDiscardable

    ブール値

    Chrome 54 以降

    リソースが少ない場合に、ブラウザがタブを自動的に破棄できるかどうか。

  • 破棄されました

    ブール値

    Chrome 54 以降

    タブが破棄されているかどうか。破棄されたタブとは、コンテンツがメモリからアンロードされたものの、タブストリップにはまだ表示されているタブのことです。コンテンツは、次回アクティブ化されたときに再読み込みされます。

  • favIconUrl

    文字列 省略可

    タブのファビコンの URL。このプロパティは、拡張機能に "tabs" 権限がある場合、またはページのホスト権限がある場合にのみ存在します。タブが読み込み中の場合は、空の文字列になることもあります。

  • フリーズ

    ブール値

    Chrome 132 以降

    タブがフリーズしているかどうか。フリーズされたタブでは、イベント ハンドラやタイマーなどのタスクを実行できません。タブストリップに表示され、そのコンテンツがメモリに読み込まれます。有効化すると凍結が解除されます。

  • groupId

    数値

    Chrome 88 以降

    タブが属するグループの ID。

  • height

    number 省略可

    タブの高さ（ピクセル単位）。

  • 強調表示

    ブール値

    タブがハイライト表示されているかどうか。

  • id

    number 省略可

    タブの ID。タブ ID はブラウザ セッション内で一意です。タブに ID が割り当てられない場合もあります。たとえば、sessions API を使用して外部タブをクエリする場合などです。この場合、セッション ID が存在する可能性があります。アプリとデベロッパー ツール ウィンドウのタブ ID を chrome.tabs.TAB_ID_NONE に設定することもできます。

  • シークレット

    ブール値

    タブがシークレット ウィンドウにあるかどうか。

  • index

    数値

    ウィンドウ内のタブのゼロから始まるインデックス。

  • lastAccessed

    数値

    Chrome 121 以降

    タブがウィンドウで最後にアクティブになった時刻（エポックからのミリ秒数）。

  • mutedInfo

    MutedInfo 省略可

    Chrome 46 以降

    タブのミュート状態と、最後の状態変更の理由。

  • openerTabId

    number 省略可

    このタブを開いたタブの ID（存在する場合）。このプロパティは、開いたタブがまだ存在する場合にのみ存在します。

  • pendingUrl

    文字列 省略可

    Chrome 79 以降

    タブが移動する URL（確定前）。このプロパティは、拡張機能に "tabs" 権限があるか、ページのホスト権限があり、保留中のナビゲーションがある場合にのみ存在します。

  • 固定中

    ブール値

    タブが固定されているかどうか。

  • 選択済み

    ブール値

    非推奨

    tabs.Tab.highlighted を使用してください。

    タブが選択されているかどうか。

  • sessionId

    文字列 省略可

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

  • ステータス

    TabStatus 省略可

    タブの読み込みステータス。

  • title

    文字列 省略可

    タブのタイトル。このプロパティは、拡張機能に "tabs" 権限がある場合、またはページのホスト権限がある場合にのみ存在します。

  • URL

    文字列 省略可

    タブのメインフレームの最後にコミットされた URL。このプロパティは、拡張機能に "tabs" 権限がある場合、またはページのホスト権限がある場合にのみ存在します。タブがまだコミットされていない場合は、空の文字列になることがあります。Tab.pendingUrl もご覧ください。

  • 幅

    number 省略可

    タブの幅（ピクセル単位）。

  • windowId

    数値

    タブを含むウィンドウの ID。

TabStatus

Chrome 44 以降

タブの読み込みステータス。

列挙型

"unloaded"

"loading"

"complete"

WindowType

Chrome 44 以降

ウィンドウのタイプ。

列挙型

"normal"

"popup"

"panel"

"app"

"devtools"

ZoomSettings

タブのズーム変更がどのように処理されるか、またその範囲を定義します。

プロパティ

  • defaultZoomFactor

    number 省略可

    Chrome 43 以降

    tabs.getZoomSettings の呼び出しで、現在のタブのデフォルトのズームレベルを返すために使用されます。

  • モード

    ZoomSettingsMode 省略可

    ズームの変更がどのように処理されるか（ページの実際のスケーリングを担当するエンティティなど）を定義します。デフォルトは automatic です。

  • スコープ

    ZoomSettingsScope 省略可

    ズームの変更をページのオリジンに保持するか、このタブでのみ有効にするかを定義します。automatic モードの場合はデフォルトで per-origin、それ以外の場合は per-tab になります。

ZoomSettingsMode

Chrome 44 以降

ズームの変更がどのように処理されるか（ページの実際のスケーリングを担当するエンティティなど）を定義します。デフォルトは automatic です。

列挙型

「自動」
ズームの変更はブラウザによって自動的に処理されます。

「manual」
ズーム変更の自動処理をオーバーライドします。onZoomChange イベントは引き続きディスパッチされます。このイベントをリッスンしてページを手動でスケーリングするのは、拡張機能の責任です。このモードは per-origin ズームをサポートしていないため、scope ズーム設定を無視して per-tab を想定します。

「disabled」
タブのズームをすべて無効にします。タブがデフォルトのズームレベルに戻り、ズームの変更はすべて無視されます。

ZoomSettingsScope

Chrome 44 以降

ズームの変更をページのオリジンに保持するか、このタブでのみ有効にするかを定義します。automatic モードの場合はデフォルトで per-origin、それ以外の場合は per-tab になります。

列挙型

「per-origin」
ズームの変更は、ズームされたページのオリジンで保持されます。つまり、同じオリジンに移動した他のすべてのタブもズームされます。また、per-origin ズームの変更はオリジンとともに保存されます。つまり、同じオリジンの他のページに移動すると、すべて同じズーム率でズームされます。per-origin スコープは automatic モードでのみ使用できます。

「タブごと」
このタブでのみズーム変更が有効になり、他のタブでのズーム変更はこのタブのズームに影響しません。また、ナビゲーション時に per-tab ズームの変更がリセットされます。タブを移動すると、常に per-origin ズーム率でページが読み込まれます。

プロパティ

MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND

Chrome 92 以降

1 秒あたりに captureVisibleTab を呼び出すことができる最大回数。captureVisibleTab はコストが高いため、頻繁に呼び出すべきではありません。

値

2

TAB_ID_NONE

Chrome 46 以降

ブラウザタブがないことを表す ID。

値

-1

TAB_INDEX_NONE

Chrome 123 以降

tab_strip にタブインデックスがないことを表すインデックス。

値

-1

メソッド

captureVisibleTab()

Promise 
chrome.tabs.captureVisibleTab(
  windowId?: number,
  options?: ImageDetails,
  callback?: function,
)

指定されたウィンドウで現在アクティブなタブの表示領域をキャプチャします。このメソッドを呼び出すには、拡張機能に <all_urls> 権限または activeTab 権限のいずれかが必要です。このメソッドを使用すると、拡張機能が通常アクセスできるサイトに加えて、chrome:-scheme ページ、他の拡張機能のページ、data: URL など、通常は制限されている機密性の高いサイトもキャプチャできます。これらの機密性の高いサイトは、activeTab 権限でのみキャプチャできます。拡張機能にファイル アクセス権が付与されている場合にのみ、ファイル URL をキャプチャできます。

パラメータ

  • windowId

    number 省略可

    ターゲット ウィンドウ。デフォルトは現在のウィンドウです。

  • オプション

    ImageDetails 省略可

  • callback

    関数 省略可

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

    (dataUrl: string) => void

    • dataUrl

      文字列

      キャプチャされたタブの表示領域の画像をエンコードするデータ URL。表示用の HTML img 要素の「src」プロパティに割り当てることができます。

戻り値

  • Promise<string>

    Chrome 88 以降

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

connect()

chrome.tabs.connect(
  tabId: number,
  connectInfo?: object,
)

指定したタブのコンテンツ スクリプトに接続します。runtime.onConnect イベントは、現在の拡張機能の指定されたタブで実行されている各コンテンツ スクリプトで発生します。詳しくは、コンテンツ スクリプトのメッセージングをご覧ください。

パラメータ

  • tabId

    数値

  • connectInfo

    オブジェクト 省略可

    • documentId

      文字列 省略可

      Chrome 106 以降

      タブ内のすべてのフレームではなく、documentId で識別される特定のドキュメントへのポートを開きます。

    • frameId

      number 省略可

      タブ内のすべてのフレームではなく、frameId で識別される特定のフレームにポートを開きます。

    • name

      文字列 省略可

      接続イベントをリッスンしているコンテンツ スクリプトの onConnect に渡されます。

戻り値

  • 指定されたタブで実行されているコンテンツ スクリプトとの通信に使用できるポート。タブが閉じられた場合や存在しない場合は、ポートの runtime.Port イベントがトリガーされます。

create()

Promise 
chrome.tabs.create(
  createProperties: object,
  callback?: function,
)

新しいタブを作成します。

パラメータ

  • createProperties

    オブジェクト

    • アクティブ

      ブール値（省略可）

      タブをウィンドウのアクティブなタブにするかどうか。ウィンドウがフォーカスされているかどうかには影響しません（windows.update を参照）。デフォルトは true です。

    • index

      number 省略可

      ウィンドウ内でタブが占める位置。指定された値は、0 からウィンドウ内のタブ数までの範囲に制限されます。

    • openerTabId

      number 省略可

      このタブを開いたタブの ID。指定した場合、オープナー タブは新しく作成されたタブと同じウィンドウに存在する必要があります。

    • 固定中

      ブール値（省略可）

      タブを固定するかどうか。デフォルトは false です

    • 選択済み

      ブール値（省略可）

      非推奨

      アクティブを使用してください。

      タブをウィンドウで選択されたタブにするかどうか。デフォルトは true です

    • URL

      文字列 省略可

      タブの初期移動先の URL。完全修飾 URL にはスキーム（'www.google.com' ではなく 'http://www.google.com'）。相対 URL は、拡張機能内の現在のページを基準とする相対 URL です。デフォルトでは [新しいタブ] ページに設定されています。

    • windowId

      number 省略可

      新しいタブを作成するウィンドウ。デフォルトは現在のウィンドウです。

  • callback

    関数 省略可

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

    (tab: Tab) => void

    • タブ

      Tab

      作成されたタブ。

戻り値

  • Promise<Tab>

    Chrome 88 以降

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

detectLanguage()

Promise 
chrome.tabs.detectLanguage(
  tabId?: number,
  callback?: function,
)

タブ内のコンテンツの主要言語を検出します。

パラメータ

  • tabId

    number 省略可

    デフォルトでは、現在のウィンドウのアクティブなタブになります。

  • callback

    関数 省略可

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

    (language: string) => void

    • language

      文字列

      en や fr などの ISO 言語コード。このメソッドでサポートされている言語の完全なリストについては、kLanguageInfoTable をご覧ください。2 ～ 4 列がチェックされ、最初の非 NULL 値が返されます。ただし、簡体字中国語の場合は zh-CN が返されます。不明な言語または未定義の言語の場合は、und が返されます。

戻り値

  • Promise<string>

    Chrome 88 以降

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

discard()

Promise Chrome 54 以降 
chrome.tabs.discard(
  tabId?: number,
  callback?: function,
)

タブをメモリから破棄します。破棄されたタブはタブバーに表示され、アクティブになると再読み込みされます。

パラメータ

  • tabId

    number 省略可

    破棄するタブの ID。指定した場合、タブがアクティブであるか、すでに破棄されている場合を除き、タブは破棄されます。省略した場合、ブラウザは最も重要度の低いタブを破棄します。破棄可能なタブが存在しない場合、この処理は失敗することがあります。

  • callback

    関数 省略可

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

    (tab?: Tab) => void

    • タブ

      タブ 省略可

      破棄されたタブ（正常に破棄された場合）。それ以外の場合は未定義。

戻り値

  • Promise<Tab | undefined>

    Chrome 88 以降

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

duplicate()

Promise 
chrome.tabs.duplicate(
  tabId: number,
  callback?: function,
)

タブを複製します。

パラメータ

  • tabId

    数値

    複製するタブの ID。

  • callback

    関数 省略可

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

    (tab?: Tab) => void

    • タブ

      タブ 省略可

      複製されたタブの詳細。url、pendingUrl、title、favIconUrl プロパティは、拡張機能に "tabs" 権限がある場合、またはページのホスト権限がある場合にのみ、tabs.Tab オブジェクトに含まれます。

戻り値

  • Promise<Tab | undefined>

    Chrome 88 以降

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

get()

Promise 
chrome.tabs.get(
  tabId: number,
  callback?: function,
)

指定されたタブの詳細を取得します。

パラメータ

  • tabId

    数値

  • callback

    関数 省略可

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

    (tab: Tab) => void

戻り値

  • Promise<Tab>

    Chrome 88 以降

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

getCurrent()

Promise 
chrome.tabs.getCurrent(
  callback?: function,
)

このスクリプト呼び出しが行われているタブを取得します。タブ以外のコンテキスト（バックグラウンド ページやポップアップ ビューなど）から呼び出された場合は undefined を返します。

パラメータ

  • callback

    関数 省略可

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

    (tab?: Tab) => void

戻り値

  • Promise<Tab | undefined>

    Chrome 88 以降

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

getZoom()

Promise 
chrome.tabs.getZoom(
  tabId?: number,
  callback?: function,
)

指定されたタブの現在のズーム率を取得します。

パラメータ

  • tabId

    number 省略可

    現在のズーム率を取得するタブの ID。デフォルトは現在のウィンドウのアクティブなタブです。

  • callback

    関数 省略可

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

    (zoomFactor: number) => void

    • zoomFactor

      数値

      タブの現在のズーム率。

戻り値

  • Promise<number>

    Chrome 88 以降

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

getZoomSettings()

Promise 
chrome.tabs.getZoomSettings(
  tabId?: number,
  callback?: function,
)

指定されたタブの現在のズーム設定を取得します。

パラメータ

  • tabId

    number 省略可

    現在のズーム設定を取得するタブの ID。デフォルトでは、現在のウィンドウのアクティブなタブになります。

  • callback

    関数 省略可

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

    (zoomSettings: ZoomSettings) => void

    • zoomSettings

      ZoomSettings

      タブの現在のズーム設定。

戻り値

  • Promise<ZoomSettings>

    Chrome 88 以降

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

goBack()

Promise Chrome 72 以降 
chrome.tabs.goBack(
  tabId?: number,
  callback?: function,
)

前のページに戻ります（前のページがある場合）。

パラメータ

  • tabId

    number 省略可

    戻るタブの ID。デフォルトは現在のウィンドウで選択されているタブです。

  • callback

    関数 省略可

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

    () => void

戻り値

  • Promise<void>

    Chrome 88 以降

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

goForward()

Promise Chrome 72 以降 
chrome.tabs.goForward(
  tabId?: number,
  callback?: function,
)

次のページがある場合は、次のページに進みます。

パラメータ

  • tabId

    number 省略可

    前に移動するタブの ID。デフォルトでは、現在のウィンドウで選択されているタブになります。

  • callback

    関数 省略可

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

    () => void

戻り値

  • Promise<void>

    Chrome 88 以降

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

group()

Promise Chrome 88 以降 
chrome.tabs.group(
  options: object,
  callback?: function,
)

指定されたグループに 1 つ以上のタブを追加します。グループが指定されていない場合は、指定されたタブを新しく作成されたグループに追加します。

パラメータ

  • オプション

    オブジェクト

    • createProperties

      オブジェクト 省略可

      グループを作成するための構成。groupId がすでに指定されている場合は使用できません。

      • windowId

        number 省略可

        新しいグループのウィンドウ。デフォルトは現在のウィンドウです。

    • groupId

      number 省略可

      タブを追加するグループの ID。指定しない場合は、新しいグループが作成されます。

    • tabIds

      number | [number, ...number[]]

      指定したグループに追加するタブ ID またはタブ ID のリスト。

  • callback

    関数 省略可

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

    (groupId: number) => void

    • groupId

      数値

      タブが追加されたグループの ID。

戻り値

  • Promise<number>

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

highlight()

Promise 
chrome.tabs.highlight(
  highlightInfo: object,
  callback?: function,
)

指定されたタブをハイライトし、グループの最初のタブにフォーカスします。指定されたタブが現在アクティブな場合、何も行われません。

パラメータ

  • highlightInfo

    オブジェクト

    • タブ

      number | number[]

      ハイライトする 1 つ以上のタブ インデックス。

    • windowId

      number 省略可

      タブを含むウィンドウ。

  • callback

    関数 省略可

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

    (window: Window) => void

    • 窓

      窓

      タブがハイライト表示されたウィンドウの詳細が含まれます。

戻り値

  • Promise<windows.Window>

    Chrome 88 以降

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

move()

Promise 
chrome.tabs.move(
  tabIds: number | number[],
  moveProperties: object,
  callback?: function,
)

1 つ以上のタブをウィンドウ内の新しい位置に移動するか、新しいウィンドウに移動します。タブは、通常の（window.type === "normal"）ウィンドウとの間でしか移動できません。

パラメータ

  • tabIds

    number | number[]

    移動するタブの ID またはタブの ID のリスト。

  • moveProperties

    オブジェクト

    • index

      数値

      ウィンドウの移動先。-1 を使用して、タブをウィンドウの末尾に配置します。

    • windowId

      number 省略可

      デフォルトでは、タブが現在表示されているウィンドウになります。

  • callback

    関数 省略可

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

    (tabs: Tab | Tab[]) => void

    • タブ

      Tab | Tab[]

      移動したタブの詳細。

戻り値

  • Promise<Tab | Tab[]>

    Chrome 88 以降

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

query()

Promise 
chrome.tabs.query(
  queryInfo: object,
  callback?: function,
)

指定されたプロパティを持つすべてのタブを取得します。プロパティが指定されていない場合は、すべてのタブを取得します。

パラメータ

  • queryInfo

    オブジェクト

    • アクティブ

      ブール値（省略可）

      タブがウィンドウでアクティブかどうか。

    • Audible

      ブール値（省略可）

      Chrome 45 以降

      タブが聴取可能かどうか。

    • autoDiscardable

      ブール値（省略可）

      Chrome 54 以降

      リソースが不足している場合に、ブラウザがタブを自動的に破棄できるかどうか。

    • currentWindow

      ブール値（省略可）

      タブが現在のウィンドウにあるかどうか。

    • 破棄されました

      ブール値（省略可）

      Chrome 54 以降

      タブが破棄されたかどうか。破棄されたタブとは、コンテンツがメモリからアンロードされたものの、タブストリップにはまだ表示されているタブのことです。コンテンツは、次回アクティブ化されたときに再読み込みされます。

    • フリーズ

      ブール値（省略可）

      Chrome 132 以降

      タブが固定されているかどうか。フリーズされたタブでは、イベント ハンドラやタイマーなどのタスクを実行できません。タブストリップに表示され、そのコンテンツがメモリに読み込まれます。有効化すると凍結が解除されます。

    • groupId

      number 省略可

      Chrome 88 以降

      タブが属するグループの ID。グループ化されていないタブの場合は tabGroups.TAB_GROUP_ID_NONE。

    • 強調表示

      ブール値（省略可）

      タブがハイライト表示されているかどうか。

    • index

      number 省略可

      ウィンドウ内のタブの位置。

    • lastFocusedWindow

      ブール値（省略可）

      タブが最後にフォーカスされたウィンドウにあるかどうか。

    • ミュート中

      ブール値（省略可）

      Chrome 45 以降

      タブがミュートされているかどうか。

    • 固定中

      ブール値（省略可）

      タブが固定されているかどうか。

    • splitViewId

      number 省略可

      保留中

      タブが配置されている分割表示の ID。分割表示に配置されていないタブの場合は tabs.SPLIT_VIEW_ID_NONE。

    • ステータス

      TabStatus 省略可

      タブの読み込みステータス。

    • title

      文字列 省略可

      ページタイトルをパターンと照合します。拡張機能に "tabs" 権限またはページのホスト権限がない場合、このプロパティは無視されます。

    • URL

      string | string[] 省略可

      1 つ以上の URL パターンに対してタブを照合します。フラグメント識別子は一致しません。拡張機能に "tabs" 権限またはページのホスト権限がない場合、このプロパティは無視されます。

    • windowId

      number 省略可

      親ウィンドウの ID。現在のウィンドウの場合は windows.WINDOW_ID_CURRENT。

    • windowType

      WindowType 省略可

      タブが表示されているウィンドウの種類。

  • callback

    関数 省略可

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

    (result: Tab[]) => void

    • 件の結果

      Tab[]

戻り値

  • Promise<Tab[]>

    Chrome 88 以降

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

reload()

Promise 
chrome.tabs.reload(
  tabId?: number,
  reloadProperties?: object,
  callback?: function,
)

タブを再読み込みします。

パラメータ

  • tabId

    number 省略可

    再読み込みするタブの ID。デフォルトでは、現在のウィンドウで選択されているタブになります。

  • reloadProperties

    オブジェクト 省略可

    • bypassCache

      ブール値（省略可）

      ローカル キャッシュをバイパスするかどうか。デフォルトは false です。

  • callback

    関数 省略可

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

    () => void

戻り値

  • Promise<void>

    Chrome 88 以降

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

remove()

Promise 
chrome.tabs.remove(
  tabIds: number | number[],
  callback?: function,
)

1 つ以上のタブを閉じます。

パラメータ

  • tabIds

    number | number[]

    閉じるタブの ID またはタブ ID のリスト。

  • callback

    関数 省略可

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

    () => void

戻り値

  • Promise<void>

    Chrome 88 以降

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

sendMessage()

Promise 
chrome.tabs.sendMessage(
  tabId: number,
  message: any,
  options?: object,
  callback?: function,
)

指定したタブのコンテンツ スクリプトに 1 つのメッセージを送信します。応答が返されたときに実行するコールバックは省略可能です。runtime.onMessage イベントは、現在の拡張機能の指定されたタブで実行されている各コンテンツ スクリプトで発生します。

パラメータ

  • tabId

    数値

  • メッセージ

    任意

    送信するメッセージ。このメッセージは JSON 化可能なオブジェクトである必要があります。

  • オプション

    オブジェクト 省略可

    • documentId

      文字列 省略可

      Chrome 106 以降

      タブ内のすべてのフレームではなく、documentId で識別される特定のドキュメントにメッセージを送信します。

    • frameId

      number 省略可

      タブ内のすべてのフレームではなく、frameId で識別される特定のフレームにメッセージを送信します。

  • callback

    関数 省略可

    Chrome 99 以降

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

    (response: any) => void

    • レスポンス

      任意

      メッセージのハンドラによって送信される JSON レスポンス オブジェクト。指定されたタブへの接続中にエラーが発生した場合、コールバックは引数なしで呼び出され、runtime.lastError はエラー メッセージに設定されます。

戻り値

  • Promise<any>

    Chrome 99 以降

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

setZoom()

Promise 
chrome.tabs.setZoom(
  tabId?: number,
  zoomFactor: number,
  callback?: function,
)

指定されたタブをズームします。

パラメータ

  • tabId

    number 省略可

    ズームするタブの ID。デフォルトは現在のウィンドウのアクティブなタブです。

  • zoomFactor

    数値

    新しいズーム倍率。値 0 は、タブを現在のデフォルトのズーム率に設定します。0 より大きい値は、タブの（デフォルト以外の可能性のある）ズーム率を指定します。

  • callback

    関数 省略可

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

    () => void

戻り値

  • Promise<void>

    Chrome 88 以降

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

setZoomSettings()

Promise 
chrome.tabs.setZoomSettings(
  tabId?: number,
  zoomSettings: ZoomSettings,
  callback?: function,
)

指定されたタブのズーム設定を設定します。ズームの変更の処理方法を定義します。これらの設定は、タブを移動するとデフォルトにリセットされます。

パラメータ

  • tabId

    number 省略可

    ズーム設定を変更するタブの ID。デフォルトは現在のウィンドウのアクティブなタブです。

  • zoomSettings

    ZoomSettings

    ズームの変更がどのように処理されるか、どの範囲で処理されるかを定義します。

  • callback

    関数 省略可

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

    () => void

戻り値

  • Promise<void>

    Chrome 88 以降

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

ungroup()

Promise Chrome 88 以降 
chrome.tabs.ungroup(
  tabIds: number | [number, ...number[]],
  callback?: function,
)

それぞれのグループから 1 つ以上のタブを削除します。空になったグループは削除されます。

パラメータ

  • tabIds

    number | [number, ...number[]]

    それぞれのグループから削除するタブ ID またはタブ ID のリスト。

  • callback

    関数 省略可

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

    () => void

戻り値

  • Promise<void>

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

update()

Promise 
chrome.tabs.update(
  tabId?: number,
  updateProperties: object,
  callback?: function,
)

タブのプロパティを変更します。updateProperties で指定されていないプロパティは変更されません。

パラメータ

  • tabId

    number 省略可

    デフォルトでは、現在のウィンドウの選択されたタブになります。

  • updateProperties

    オブジェクト

    • アクティブ

      ブール値（省略可）

      タブをアクティブにするかどうか。ウィンドウがフォーカスされているかどうかには影響しません（windows.update を参照）。

    • autoDiscardable

      ブール値（省略可）

      Chrome 54 以降

      リソースが不足している場合に、ブラウザによってタブが自動的に破棄されるかどうか。

    • 強調表示

      ブール値（省略可）

      現在の選択範囲からタブを追加または削除します。

    • ミュート中

      ブール値（省略可）

      Chrome 45 以降

      タブをミュートするかどうか。

    • openerTabId

      number 省略可

      このタブを開いたタブの ID。指定した場合、オープナー タブはこのタブと同じウィンドウにある必要があります。

    • 固定中

      ブール値（省略可）

      タブを固定するかどうか。

    • 選択済み

      ブール値（省略可）

      非推奨

      ハイライト表示を使用してください。

      タブを選択するかどうか。

    • URL

      文字列 省略可

      タブの移動先の URL。JavaScript URL はサポートされていません。代わりに scripting.executeScript を使用してください。

  • callback

    関数 省略可

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

    (tab?: Tab) => void

    • タブ

      タブ 省略可

      更新されたタブの詳細。url、pendingUrl、title、favIconUrl プロパティは、拡張機能に "tabs" 権限がある場合、またはページのホスト権限がある場合にのみ、tabs.Tab オブジェクトに含まれます。

戻り値

  • Promise<Tab | undefined>

    Chrome 88 以降

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

イベント

onActivated

chrome.tabs.onActivated.addListener(
  callback: function,
)

ウィンドウのアクティブなタブが変更されたときに発生します。このイベントが発火した時点ではタブの URL が設定されていない可能性がありますが、URL が設定されたときに通知を受け取るように onUpdated イベントをリッスンできます。

パラメータ

  • callback

    関数

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

    (activeInfo: object) => void

    • activeInfo

      オブジェクト

      • tabId

        数値

        アクティブになったタブの ID。

      • windowId

        数値

        アクティブなタブが変更されたウィンドウの ID。

onAttached

chrome.tabs.onAttached.addListener(
  callback: function,
)

タブがウィンドウにアタッチされたときに発生します。たとえば、ウィンドウ間で移動された場合などです。

パラメータ

  • callback

    関数

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

    (tabId: number, attachInfo: object) => void

    • tabId

      数値

    • attachInfo

      オブジェクト

      • newPosition

        数値

      • newWindowId

        数値

onCreated

chrome.tabs.onCreated.addListener(
  callback: function,
)

タブが作成されたときに呼び出されます。このイベントが発火した時点では、タブの URL とタブグループのメンバーシップが設定されていない可能性がありますが、onUpdated イベントをリッスンすることで、URL が設定されたときやタブがタブグループに追加されたときに通知を受け取ることができます。

パラメータ

  • callback

    関数

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

    (tab: Tab) => void

onDetached

chrome.tabs.onDetached.addListener(
  callback: function,
)

タブがウィンドウから切り離されたときに発生します。たとえば、ウィンドウ間で移動された場合などです。

パラメータ

  • callback

    関数

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

    (tabId: number, detachInfo: object) => void

    • tabId

      数値

    • detachInfo

      オブジェクト

      • oldPosition

        数値

      • oldWindowId

        数値

onHighlighted

chrome.tabs.onHighlighted.addListener(
  callback: function,
)

ウィンドウでハイライト表示または選択されているタブが変更されたときに発生します。

パラメータ

  • callback

    関数

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

    (highlightInfo: object) => void

    • highlightInfo

      オブジェクト

      • tabIds

        number[]

        ウィンドウ内のハイライト表示されたすべてのタブ。

      • windowId

        数値

        タブが変更されたウィンドウ。

onMoved

chrome.tabs.onMoved.addListener(
  callback: function,
)

タブがウィンドウ内で移動されたときに発生します。ユーザーが直接移動したタブを表す移動イベントが 1 つだけ発生します。手動で移動したタブに応じて移動する必要がある他のタブに対して、移動イベントが発火しません。タブがウィンドウ間で移動された場合、このイベントは発生しません。詳しくは、tabs.onDetached をご覧ください。

パラメータ

  • callback

    関数

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

    (tabId: number, moveInfo: object) => void

    • tabId

      数値

    • moveInfo

      オブジェクト

      • fromIndex

        数値

      • toIndex

        数値

      • windowId

        数値

onRemoved

chrome.tabs.onRemoved.addListener(
  callback: function,
)

タブが閉じられたときに呼び出されます。

パラメータ

  • callback

    関数

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

    (tabId: number, removeInfo: object) => void

    • tabId

      数値

    • removeInfo

      オブジェクト

      • isWindowClosing

        ブール値

        親ウィンドウが閉じられたためにタブが閉じられた場合は true。

      • windowId

        数値

        タブが閉じられたウィンドウ。

onReplaced

chrome.tabs.onReplaced.addListener(
  callback: function,
)

プリレンダリングまたはインスタントによってタブが別のタブに置き換えられたときに呼び出されます。

パラメータ

  • callback

    関数

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

    (addedTabId: number, removedTabId: number) => void

    • addedTabId

      数値

    • removedTabId

      数値

onUpdated

chrome.tabs.onUpdated.addListener(
  callback: function,
)

タブが更新されたときに発生します。

パラメータ

  • callback

    関数

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

    (tabId: number, changeInfo: object, tab: Tab) => void

    • tabId

      数値

    • changeInfo

      オブジェクト

      • Audible

        ブール値（省略可）

        Chrome 45 以降

        タブの新しい音声状態。

      • autoDiscardable

        ブール値（省略可）

        Chrome 54 以降

        タブの新しい自動破棄可能状態。

      • 破棄されました

        ブール値（省略可）

        Chrome 54 以降

        タブの新しい破棄状態。

      • favIconUrl

        文字列 省略可

        タブの新しいファビコンの URL。

      • フリーズ

        ブール値（省略可）

        Chrome 132 以降

        タブの新しいフリーズ状態。

      • groupId

        number 省略可

        Chrome 88 以降

        タブの新しいグループ。

      • mutedInfo

        MutedInfo 省略可

        Chrome 46 以降

        タブの新しいミュート状態と、変更の理由。

      • 固定中

        ブール値（省略可）

        タブの新しい固定状態。

      • splitViewId

        number 省略可

        保留中

        タブの新しい分割表示。

      • ステータス

        TabStatus 省略可

        タブの読み込みステータス。

      • title

        文字列 省略可

        Chrome 48 以降

        タブの新しいタイトル。

      • URL

        文字列 省略可

        タブの URL（変更されている場合）。

    • タブ

      Tab

onZoomChange

chrome.tabs.onZoomChange.addListener(
  callback: function,
)

タブがズームされたときに呼び出されます。

パラメータ

  • callback

    関数

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

    (ZoomChangeInfo: object) => void

    • ZoomChangeInfo

      オブジェクト

      • newZoomFactor

        数値

      • oldZoomFactor

        数値

      • tabId

        数値

      • zoomSettings

        ZoomSettings