このページは Cloud Translation API によって翻訳されました。

chrome.sidePanel

説明

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

権限

sidePanel

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

manifest.json:

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

対象

Chrome 114+ MV3+

コンセプトと使用方法

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

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

次のような機能があります。

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

ユースケース

以降のセクションでは、サイドパネル 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() を使用して、特定のタブでサイドパネルを有効にできます。この例では、chrome.tabs.onUpdated() を使用して、タブに加えられた更新をリッスンします。URL が www.google.com であるかどうかを確認し、サイドパネルを有効にします。それ以外の場合は無効にします。

service-worker.js:

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

chrome.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 chrome.sidePanel.setOptions({
      tabId,
      path: 'sidepanel.html',
      enabled: true
    });
  } else {
    // Disables the side panel on all other sites
    await chrome.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
chrome.sidePanel
  .setPanelBehavior({ openPanelOnActionClick: true })
  .catch((error) => console.error(error));
...

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

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

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

service-worker.js:

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

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

別のパネルに切り替える

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

service-worker.js:

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

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

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

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

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

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

サイドパネルを開く

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

サイドパネルを固定する

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

例

サイドパネル API 拡張機能のデモについては、次のいずれかの拡張機能をご覧ください。

型

CloseOptions

Chrome 141 以降

プロパティ

tabId

number 省略可

サイドパネルを閉じるタブ。指定されたタブでタブ固有のサイドパネルが開いている場合は、そのタブのサイドパネルが閉じられます。これまたは windowId のうち少なくとも 1 つを指定する必要があります。
windowId

number 省略可

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

GetPanelOptions

プロパティ

tabId

number 省略可

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

OpenOptions

Chrome 116 以降

プロパティ

tabId

number 省略可

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

number 省略可

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

PanelBehavior

プロパティ

openPanelOnActionClick

ブール値（省略可）

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

PanelClosedInfo

Chrome 142 以降

プロパティ

パス

文字列

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

number 省略可

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

数値

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

PanelLayout

Chrome 140 以降

プロパティ

side

Side

PanelOpenedInfo

Chrome 141 以降

プロパティ

パス

文字列

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

number 省略可

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

数値

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

PanelOptions

プロパティ

有効

boolean 省略可

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

文字列省略可

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

number 省略可

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

Side

Chrome 140 以降

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

列挙型

"left"

"right"

SidePanel

プロパティ

default_path

文字列

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

メソッド

getLayout()

Chrome 140 以降

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

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

戻り値

Promise<PanelLayout>

getOptions()

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

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

パラメータ

オプション

GetPanelOptions

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

戻り値

Promise<PanelOptions>

getPanelBehavior()

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

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

戻り値

Promise<PanelBehavior>

open()

Chrome 116 以降

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

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

パラメータ

オプション

OpenOptions

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

戻り値

Promise<void>

setOptions()

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

サイドパネルを設定します。

パラメータ

オプション

PanelOptions

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

戻り値

Promise<void>

setPanelBehavior()

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

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

パラメータ

動作

PanelBehavior

設定する新しい動作。

戻り値

Promise<void>

イベント

onOpened

Chrome 141 以降

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

拡張機能のサイドパネルが開いたときに発生します。

パラメータ

callback

関数

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

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

説明

権限

対象

コンセプトと使用方法

ユースケース

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

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

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

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

別のパネルに切り替える

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

サイドパネルを開く

サイドパネルを固定する

例

型

CloseOptions

プロパティ

GetPanelOptions

プロパティ

OpenOptions

プロパティ

PanelBehavior

プロパティ

PanelClosedInfo

プロパティ

PanelLayout

プロパティ

PanelOpenedInfo

プロパティ

PanelOptions

プロパティ

Side

列挙型

SidePanel

プロパティ

メソッド

getLayout()

戻り値

getOptions()

パラメータ

戻り値

getPanelBehavior()

戻り値

open()

パラメータ

戻り値

setOptions()

パラメータ

戻り値

setPanelBehavior()

パラメータ

戻り値

イベント

onOpened

パラメータ

chrome.sidePanel

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

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