chrome.offscreen

説明

offscreen API を使用して、画面外ドキュメントを作成、管理します。

権限

offscreen

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

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

対象

Chrome 109 以降 MV3 以降 をご覧ください。

コンセプトと使用方法

Service Worker には DOM アクセスはなく、多くのウェブサイトには、 コンテンツ スクリプトの機能を制限する。Offscreen API を使用すると、拡張機能で DOM を使用できるようになります。 新しいウィンドウを開いたり、ユーザー エクスペリエンスを中断することなく、 できます。runtime API は唯一の拡張機能 API です オフライン ドキュメントでもサポートされています。

画面外のドキュメントとして読み込まれたページは、他の種類の拡張機能ページとは異なる方法で処理されます。 拡張機能の権限は画面外のドキュメントに引き継がれますが、拡張機能 API には制限があります できます。たとえば、chrome.runtime API は Extensions 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: '...'
  });
});

完全な例については、offscreen-clipboard と offscreen-dom デモ（GitHub）

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 await matchedClients.some(client => {
        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()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.offscreen.closeDocument(
  callback?: function,
)

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

パラメータ

  • callback

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

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

createDocument()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.offscreen.createDocument(
  parameters: CreateParameters,
  callback?: function,
)

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

パラメータ

  • パラメータ

    CreateParameters

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

  • callback

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

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