chrome.offscreen

説明

offscreen API を使用して、オフスクリーン ドキュメントを作成、管理します。

権限

offscreen

Offscreen API を使用するには、拡張機能のマニフェストで "offscreen" 権限を宣言します。次に例を示します。

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

対象

Chrome 109 以降 MV3 以降

コンセプトと使用方法

サービス ワーカーには DOM へのアクセス権がなく、多くのウェブサイトにはコンテンツ スクリプトの機能を制限するコンテンツ セキュリティ ポリシーが設定されています。Offscreen API を使用すると、拡張機能は新しいウィンドウやタブを開いてユーザー エクスペリエンスを中断することなく、非表示のドキュメントで DOM API を使用できます。runtime API は、オフスクリーン ドキュメントでサポートされている唯一の拡張機能 API です。

オフスクリーン ドキュメントとして読み込まれたページは、他のタイプの拡張機能ページとは異なる方法で処理されます。拡張機能の権限はオフスクリーン ドキュメントに引き継がれますが、拡張機能 API へのアクセスには制限があります。たとえば、オフスクリーン ドキュメントでサポートされている拡張機能 API は chrome.runtime API のみであるため、メッセージングは、その API のメンバーを使用して処理する必要があります。

画面外ドキュメントは、通常のページと異なる動作をします。

  • 画面外ドキュメントの URL は、拡張機能にバンドルされている静的 HTML ファイルである必要があります。
  • 画面外のドキュメントにフォーカスできません。
  • オフスクリーン ドキュメントは window のインスタンスですが、その opener プロパティの値は常に null です。
  • 拡張機能パッケージには複数のオフスクリーン ドキュメントを含めることができますが、インストールされた拡張機能で同時に開くことができるのは 1 つだけです。拡張機能がアクティブなシークレット プロファイルで分割モードで実行されている場合、通常のプロファイルとシークレット プロファイルはそれぞれ 1 つの画面外ドキュメントを持つことができます。

chrome.offscreen.createDocument() と chrome.offscreen.closeDocument() を使用して、オフスクリーン ドキュメントを作成して閉じます。createDocument() には、ドキュメントの url、理由、正当性が必要です。

chrome.offscreen.createDocument({
  url: 'off_screen.html',
  reasons: ['CLIPBOARD'],
  justification: 'reason for needing the document',
});

理由

有効な理由の一覧については、理由のセクションをご覧ください。理由は、ドキュメントの有効期間を決定するためにドキュメントの作成時に設定されます。AUDIO_PLAYBACK の理由は、音声が再生されない状態で 30 秒後にドキュメントを閉じるように設定します。その他の理由では、ライフタイムの上限は設定されません。

例

オフスクリーン ドキュメントのライフサイクルを維持する

次の例は、オフスクリーン ドキュメントが存在することを確認する方法を示しています。setupOffscreenDocument() 関数は runtime.getContexts() を呼び出して、既存のオフスクリーン ドキュメントを検索します。ドキュメントが存在しない場合は、ドキュメントを作成します。

let creating; // A global promise to avoid concurrency issues
async function setupOffscreenDocument(path) {
  // Check all windows controlled by the service worker to see if one
  // of them is the offscreen document with the given path
  const offscreenUrl = chrome.runtime.getURL(path);
  const existingContexts = await chrome.runtime.getContexts({
    contextTypes: ['OFFSCREEN_DOCUMENT'],
    documentUrls: [offscreenUrl]
  });

  if (existingContexts.length > 0) {
    return;
  }

  // create offscreen document
  if (creating) {
    await creating;
  } else {
    creating = chrome.offscreen.createDocument({
      url: path,
      reasons: ['CLIPBOARD'],
      justification: 'reason for needing the document',
    });
    await creating;
    creating = null;
  }
}

オフスクリーン ドキュメントにメッセージを送信する前に、次の例に示すように setupOffscreenDocument() を呼び出して、ドキュメントが存在することを確認します。

chrome.action.onClicked.addListener(async () => {
  await setupOffscreenDocument('off_screen.html');

  // Send message to offscreen document
  chrome.runtime.sendMessage({
    type: '...',
    target: 'offscreen',
    data: '...'
  });
});

完全な例については、GitHub の offscreen-clipboard デモと offscreen-dom デモをご覧ください。

Chrome 116 より前: 画面外ドキュメントが開いているかどうかを確認する

runtime.getContexts() は Chrome 116 で追加されました。以前のバージョンの Chrome では、clients.matchAll() を使用して、既存のオフスクリーン ドキュメントを確認します。

async function hasOffscreenDocument() {
  if ('getContexts' in chrome.runtime) {
    const contexts = await chrome.runtime.getContexts({
      contextTypes: ['OFFSCREEN_DOCUMENT'],
      documentUrls: [OFFSCREEN_DOCUMENT_PATH]
    });
    return Boolean(contexts.length);
  } else {
    const matchedClients = await clients.matchAll();
    return matchedClients.some(client => {
      return client.url.includes(chrome.runtime.id);
    });
  }
}

型

CreateParameters

プロパティ

  • 両端揃え

    文字列

    バックグラウンド コンテキストの必要性を詳しく説明する、デベロッパーが提供する文字列。ユーザー エージェントは、ユーザーへの表示にこれを使用する場合があります。

  • 回答者

    理由[]

    拡張機能が画面外ドキュメントを作成する理由。

  • URL

    文字列

    ドキュメントに読み込む（相対）URL。

Reason

列挙型

"TESTING"
テスト専用の理由。

"AUDIO_PLAYBACK"
オフスクリーン ドキュメントが音声の再生を担当することを指定します。

「IFRAME_SCRIPTING」
iframe のコンテンツを変更するために、オフスクリーン ドキュメントで iframe を埋め込んでスクリプトを実行する必要があることを指定します。

「DOM_SCRAPING」
オフスクリーン ドキュメントで iframe を埋め込み、その DOM をスクレイピングして情報を抽出する必要があることを指定します。

「BLOBS」
オフスクリーン ドキュメントが Blob オブジェクト（URL.createObjectURL() を含む）とやり取りする必要があることを指定します。

「DOM_PARSER」
オフスクリーン ドキュメントで DOMParser API を使用する必要があることを指定します。

「USER_MEDIA」
オフスクリーン ドキュメントがユーザー メディア（getUserMedia() など）のメディア ストリームとやり取りする必要があることを指定します。

「DISPLAY_MEDIA」
オフスクリーン ドキュメントがディスプレイ メディア（getDisplayMedia() など）のメディア ストリームとやり取りする必要があることを指定します。

"WEB_RTC"
オフスクリーン ドキュメントで WebRTC API を使用する必要があることを指定します。

「CLIPBOARD」
オフスクリーン ドキュメントが Clipboard API とやり取りする必要があることを指定します。

"LOCAL_STORAGE"
オフスクリーン ドキュメントが localStorage にアクセスする必要があることを指定します。

「WORKERS」
オフスクリーン ドキュメントがワーカーを生成する必要があることを指定します。

"BATTERY_STATUS"
オフスクリーン ドキュメントで navigator.getBattery を使用する必要があることを指定します。

"MATCH_MEDIA"
オフスクリーン ドキュメントで window.matchMedia を使用する必要があることを指定します。

「GEOLOCATION」
オフスクリーン ドキュメントで navigator.geolocation を使用する必要があることを指定します。

メソッド

closeDocument()

chrome.offscreen.closeDocument(): Promise<void>

拡張機能で現在開いているオフスクリーン ドキュメントを閉じます。

戻り値

  • Promise<void>

createDocument()

chrome.offscreen.createDocument(
  parameters: CreateParameters,
): Promise<void>

拡張機能の新しいオフスクリーン ドキュメントを作成します。

パラメータ

  • パラメータ

    CreateParameters

    作成するオフスクリーン ドキュメントを記述するパラメータ。

戻り値

  • Promise<void>