Chrome で標準化された browser.* 名前空間がサポートされるようになりました（Chrome 148 以降で利用可能）。ドキュメントは順次更新されます。詳しくは、移行ガイドをご覧ください。

Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

browser.sidePanel

説明

chrome.sidePanel API を使用して、ウェブページのメインコンテンツとともにブラウザのサイドパネルでコンテンツをホストします。

権限

sidePanel

Side Panel API を使用するには、拡張機能のマニフェストファイルに "sidePanel" 権限を追加します。

manifest.json:

{
  "name": "My side panel extension",
  ...
  "permissions": [
    "sidePanel"
  ]
}

対象

Chrome 114 以降 Chrome 148 以降の browser.* MV3 以降

コンセプトと使用方法

Side Panel API を使用すると、拡張機能はサイドパネルに独自の UI を表示し、ユーザーのブラウジングを補完する永続的なエクスペリエンスを実現できます。

サイドパネルのプルダウンメニュー — Chrome ブラウザのサイドパネル UI。

主な機能は次のとおりです。

タブを切り替えても、サイドパネルは開いたままになります（そのように設定されている場合）。
特定のウェブサイトでのみ利用可能。
拡張機能ページとして、サイドパネルはすべての Chrome API にアクセスできます。
ユーザーは、Chrome の設定でパネルを表示する側を指定できます。

ユースケース

以降のセクションでは、Side Panel API の一般的なユースケースをいくつか紹介します。拡張機能の完全な例については、拡張機能のサンプルをご覧ください。

すべてのサイトで同じサイドパネルを表示する

サイドパネルは、マニフェストの "side_panel" キーの "default_path" プロパティから最初に設定して、すべてのサイトで同じサイドパネルを表示できます。これは、拡張機能ディレクトリ内の相対パスを指している必要があります。

manifest.json:

{
  "name": "My side panel extension",
  ...
  "side_panel": {
    "default_path": "sidepanel.html"
  }
  ...
}

sidepanel.html:

<!DOCTYPE html>
<html>
  <head>
    <title>My Sidepanel</title>
  </head>
  <body>
    <h1>All sites sidepanel extension</h1>
    <p>This side panel is enabled on all sites</p>
  </body>
</html>

特定のサイトでサイドパネルを有効にする

拡張機能は、sidepanel.setOptions() を使用して、特定のタブでサイドパネルを有効にできます。この例では、browser.tabs.onUpdated() を使用して、タブに加えられた更新をリッスンします。URL が www.google.com であるかどうかを確認し、サイドパネルを有効にします。それ以外の場合は無効にします。

service-worker.js:

const GOOGLE_ORIGIN = 'https://www.google.com';

browser.tabs.onUpdated.addListener(async (tabId, info, tab) => {
  if (!tab.url) return;
  const url = new URL(tab.url);
  // Enables the side panel on google.com
  if (url.origin === GOOGLE_ORIGIN) {
    await browser.sidePanel.setOptions({
      tabId,
      path: 'sidepanel.html',
      enabled: true
    });
  } else {
    // Disables the side panel on all other sites
    await browser.sidePanel.setOptions({
      tabId,
      enabled: false
    });
  }
});

サイドパネルが有効になっていないタブに一時的に切り替えると、サイドパネルは非表示になります。ユーザーが以前に開いていたタブに切り替えると、自動的に再度表示されます。

ユーザーがサイドパネルが有効になっていないサイトに移動すると、サイドパネルが閉じ、拡張機能はサイドパネルのプルダウンメニューに表示されなくなります。

完全な例については、タブ固有のサイドパネルのサンプルをご覧ください。

ツールバーアイコンをクリックしてサイドパネルを開く

デベロッパーは、sidePanel.setPanelBehavior() を使用して、ユーザーがアクションツールバーアイコンをクリックしたときにサイドパネルを開くように設定できます。まず、マニフェストで "action" キーを宣言します。

manifest.json:

{
  "name": "My side panel extension",
  ...
  "action": {
    "default_title": "Click to open panel"
  },
  ...
}

ここで、前の例に次のコードを追加します。

service-worker.js:

const GOOGLE_ORIGIN = 'https://www.google.com';

// Allows users to open the side panel by clicking on the action toolbar icon
browser.sidePanel
  .setPanelBehavior({ openPanelOnActionClick: true })
  .catch((error) => console.error(error));
...

ユーザー操作時にプログラムでサイドパネルを開く

Chrome 116 では、sidePanel.open() が導入されます。これにより、拡張機能は、アクションアイコンのクリックなどの拡張機能のユーザージェスチャーによってサイドパネルを開くことができます。または、ボタンのクリックなど、拡張機能ページまたはコンテンツスクリプトでのユーザー操作。完全なデモについては、Open Side Panel サンプル拡張機能をご覧ください。

次のコードは、ユーザーがコンテキストメニューをクリックしたときに、現在のウィンドウでグローバルサイドパネルを開く方法を示しています。sidePanel.open() を使用する場合は、開くコンテキストを選択する必要があります。windowId を使用して、グローバルサイドパネルを開きます。または、tabId を設定して、特定のタブでのみサイドパネルを開くようにします。

service-worker.js:

browser.runtime.onInstalled.addListener(() => {
  browser.contextMenus.create({
    id: 'openSidePanel',
    title: 'Open side panel',
    contexts: ['all']
  });
});

browser.contextMenus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === 'openSidePanel') {
    // This will open the panel in all the pages on the current window.
    browser.sidePanel.open({ windowId: tab.windowId });
  }
});

別のパネルに切り替える

拡張機能は、sidepanel.getOptions() を使用して現在のサイドパネルを取得できます。次の例では、runtime.onInstalled() にウェルカムサイドパネルを設定しています。ユーザーが別のタブに移動すると、メインのサイドパネルに置き換えられます。

service-worker.js:

const welcomePage = 'sidepanels/welcome-sp.html';
const mainPage = 'sidepanels/main-sp.html';

browser.runtime.onInstalled.addListener(() => {
  browser.sidePanel.setOptions({ path: welcomePage });
  browser.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
});

browser.tabs.onActivated.addListener(async ({ tabId }) => {
  const { path } = await browser.sidePanel.getOptions({ tabId });
  if (path === welcomePage) {
    browser.sidePanel.setOptions({ path: mainPage });
  }
});

完全なコードについては、複数のサイドパネルのサンプルをご覧ください。

サイドパネルのユーザーエクスペリエンス

ユーザーには、まず Chrome の組み込みサイドパネルが表示されます。各サイドパネルには、サイドパネルメニューに拡張機能のアイコンが表示されます。アイコンが含まれていない場合は、拡張機能の名前の最初の文字を含むプレースホルダアイコンが表示されます。

サイドパネルを開く

ユーザーがサイドパネルを開けるようにするには、アクションアイコンと sidePanel.setPanelBehavior() を組み合わせて使用します。または、次のようなユーザー操作の後に sidePanel.open() を呼び出します。

サイドパネルを固定する

サイドパネルが開いているときに、サイドパネルツールバーに固定アイコンが表示されます。アイコンをクリックすると、拡張機能のアクションアイコンが固定されます。固定されたアクションアイコンをクリックすると、アクションアイコンのデフォルトのアクションが実行されます。サイドパネルが開くのは、明示的に構成されている場合のみです。

例

Side Panel API 拡張機能のその他のデモについては、次の拡張機能をご覧ください。

型

CloseOptions

Chrome 141 以降 Chrome 148 以降の browser.*

プロパティ

tabId

number 省略可

サイドパネルを閉じるタブ。指定したタブでタブ固有のサイドパネルが開いている場合、そのタブのサイドパネルは閉じられます。グローバルサイドパネルのみが開いている場合、close() の呼び出しによって返される Promise はエラーで拒否されます。この動作は Chrome 145 で変更されました。以前のバージョンでは、グローバルパネルを閉じる動作にフォールバックします。これまたは windowId のうち少なくとも 1 つを指定する必要があります。
windowId

number 省略可

サイドパネルを閉じるウィンドウ。指定したウィンドウでグローバルサイドパネルが開いている場合、タブ固有のパネルがアクティブになっていないそのウィンドウのすべてのタブで、グローバルサイドパネルが閉じられます。これまたは tabId のうち少なくとも 1 つを指定する必要があります。

GetPanelOptions

プロパティ

tabId

number 省略可

指定すると、指定したタブのサイドパネルオプションが返されます。それ以外の場合は、デフォルトのサイドパネルオプション（特定の設定がないタブに使用）を返します。

OpenOptions

Chrome 116 以降 Chrome 148 以降の browser.*

プロパティ

tabId

number 省略可

サイドパネルを開くタブ。対応するタブにタブ固有のサイドパネルがある場合、そのパネルはそのタブでのみ開きます。タブ固有のパネルがない場合、グローバルパネルは、指定されたタブと、現在開いているタブ固有のパネルがない他のタブで開きます。これにより、対応するタブで現在アクティブなサイドパネル（グローバルまたはタブ固有）がオーバーライドされます。これまたは windowId のうち少なくとも 1 つを指定する必要があります。
windowId

number 省略可

サイドパネルを開くウィンドウ。これは、拡張機能にグローバル（タブ固有ではない）サイドパネルがある場合、または tabId も指定されている場合にのみ適用されます。これにより、ユーザーが指定されたウィンドウで開いている、現在アクティブなグローバルサイドパネルがオーバーライドされます。これまたは tabId のうち少なくとも 1 つを指定する必要があります。

PanelBehavior

プロパティ

openPanelOnActionClick

boolean 省略可

拡張機能のアイコンをクリックすると、サイドパネルに拡張機能のエントリが表示されるかどうかを切り替えます。デフォルトは false です。

PanelClosedInfo

Chrome 142 以降 Chrome 148 以降の browser.*

プロパティ

パス

文字列

拡張機能パッケージ内のローカルリソースのパス。このリソースのコンテンツがパネルに表示されます。
tabId

number 省略可

サイドパネルが閉じられたタブの ID（省略可）。これは、パネルがタブ固有の場合にのみ提供されます。
windowId

数値

サイドパネルが閉じられたウィンドウの ID。これは、グローバルパネルとタブ固有のパネルの両方で使用できます。

PanelLayout

Chrome 140 以降 Chrome 148 以降の browser.*

プロパティ

side

側面

PanelOpenedInfo

Chrome 141 以降 Chrome 148 以降の browser.*

プロパティ

パス

文字列

拡張機能パッケージ内のローカルリソースのパス。このリソースのコンテンツがパネルに表示されます。
tabId

number 省略可

サイドパネルが開いているタブの ID（省略可）。これは、パネルがタブ固有の場合にのみ提供されます。
windowId

数値

サイドパネルが開いているウィンドウの ID。これは、グローバルパネルとタブ固有のパネルの両方で使用できます。

PanelOptions

プロパティ

有効

boolean 省略可

サイドパネルを有効にするかどうか。PIN の作成は省略することもできます。デフォルト値は true です。
パス

文字列省略可

使用するサイドパネルの HTML ファイルのパス。これは、拡張機能パッケージ内のローカルリソースである必要があります。
tabId

number 省略可

指定した場合、サイドパネルのオプションはこの ID のタブにのみ適用されます。省略した場合、これらのオプションはデフォルトの動作を設定します（特定の設定がないタブに使用されます）。注: この tabId とデフォルトの tabId に同じパスが設定されている場合、この tabId のパネルはデフォルトの tabId のパネルとは異なるインスタンスになります。

Side

Chrome 140 以降 Chrome 148 以降の browser.*

ブラウザ UI のサイドパネルの配置を定義します。

列挙型

"left"

"right"

SidePanel

プロパティ

default_path

文字列

サイドパネルの表示用にデベロッパーが指定したパス。

メソッド

close()

Chrome 141 以降 Chrome 148 以降の browser.*

browser.sidePanel.close(
  options: CloseOptions,
): Promise<void>

拡張機能のサイドパネルを閉じます。パネルがすでに閉じている場合、これは何もしません。

パラメータ

オプション

CloseOptions

サイドパネルを閉じるコンテキストを指定します。

戻り値

Promise<void>

サイドパネルが閉じられたときに解決される Promise を返します。

getLayout()

Chrome 140 以降 Chrome 148 以降の browser.*

browser.sidePanel.getLayout(): Promise<PanelLayout>

サイドパネルの現在のレイアウトを返します。

戻り値

Promise<PanelLayout>

PanelLayout で解決される Promise を返します。

getOptions()

browser.sidePanel.getOptions(
  options: GetPanelOptions,
): Promise<PanelOptions>

アクティブなパネル構成を返します。

パラメータ

オプション

GetPanelOptions

構成を返すコンテキストを指定します。

戻り値

Promise<PanelOptions>

アクティブなパネル構成で解決される Promise を返します。

getPanelBehavior()

browser.sidePanel.getPanelBehavior(): Promise<PanelBehavior>

拡張機能の現在のサイドパネルの動作を返します。

戻り値

Promise<PanelBehavior>

拡張機能のサイドパネルの動作で解決される Promise を返します。

open()

Chrome 116 以降 Chrome 148 以降の browser.*

browser.sidePanel.open(
  options: OpenOptions,
): Promise<void>

拡張機能のサイドパネルを開きます。これは、ユーザー操作に応じてのみ呼び出すことができます。

パラメータ

オプション

OpenOptions

サイドパネルを開くコンテキストを指定します。

戻り値

Promise<void>

サイドパネルが開いたときに解決される Promise を返します。

setOptions()

browser.sidePanel.setOptions(
  options: PanelOptions,
): Promise<void>

サイドパネルを構成します。

パラメータ

オプション

PanelOptions

パネルに適用する構成オプション。

戻り値

Promise<void>

オプションが設定されると解決される Promise を返します。

setPanelBehavior()

browser.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
): Promise<void>

拡張機能のサイドパネルの動作を構成します。これは upsert オペレーションです。

パラメータ

動作

PanelBehavior

設定する新しい動作。

戻り値

Promise<void>

新しい動作が設定されると解決される Promise を返します。

イベント

onClosed

Chrome 142 以降 Chrome 148 以降の browser.*

browser.sidePanel.onClosed.addListener(
  callback: function,
)

拡張機能のサイドパネルが閉じられたときに呼び出されます。

パラメータ

callback

関数

callback パラメータは次のようになります。
```
(info: PanelClosedInfo) => void
```
- 情報
  
  PanelClosedInfo

onOpened

Chrome 141 以降 Chrome 148 以降の browser.*

browser.sidePanel.onOpened.addListener(
  callback: function,
)

拡張機能のサイドパネルが開いたときに呼び出されます。

パラメータ

callback

関数

callback パラメータは次のようになります。
```
(info: PanelOpenedInfo) => void
```
- 情報
  
  PanelOpenedInfo

browser.sidePanel コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

説明

権限

対象

コンセプトと使用方法

ユースケース

すべてのサイトで同じサイドパネルを表示する

特定のサイトでサイドパネルを有効にする

ツールバー アイコンをクリックしてサイドパネルを開く

ユーザー操作時にプログラムでサイドパネルを開く

別のパネルに切り替える

サイドパネルのユーザー エクスペリエンス

サイドパネルを開く

サイドパネルを固定する

例

型

CloseOptions

プロパティ

GetPanelOptions

プロパティ

OpenOptions

プロパティ

PanelBehavior

プロパティ

PanelClosedInfo

プロパティ

PanelLayout

プロパティ

PanelOpenedInfo

プロパティ

PanelOptions

プロパティ

Side

列挙型

SidePanel

プロパティ

メソッド

close()

パラメータ

戻り値

getLayout()

戻り値

getOptions()

パラメータ

戻り値

getPanelBehavior()

戻り値

open()

パラメータ

戻り値

setOptions()

パラメータ

戻り値

setPanelBehavior()

パラメータ

戻り値

イベント

onClosed

パラメータ

onOpened

パラメータ

browser.sidePanel

ツールバーアイコンをクリックしてサイドパネルを開く

サイドパネルのユーザーエクスペリエンス