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 へのアクセスには制限があります。たとえば、chrome.runtime API はオフスクリーン ドキュメントでサポートされている唯一の 拡張機能 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 秒後にドキュメントが閉じられます。その他の理由では、有効期間の上限は設定されません。

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

次の例は、オフスクリーン ドキュメントが存在することを確認する方法を示しています。The 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>

    オフスクリーン ドキュメントが閉じられたときに解決される Promise。

createDocument()

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

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

パラメータ

  • パラメータ

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

戻り値

  • Promise<void>

    オフスクリーン ドキュメントが作成され、最初のページ読み込みが完了したときに解決される Promise。

hasDocument()

保留中
chrome.offscreen.hasDocument(): Promise<boolean>

拡張機能にアクティブなドキュメントがあるかどうかを判断します。

戻り値

  • Promise<boolean>

    拡張機能にアクティブなオフスクリーン ドキュメントがあるかどうかの結果で解決される Promise。