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

chrome.sidePanel

説明

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

権限

sidePanel

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

manifest.json:

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

対象

Chrome 114 以降 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() を使用すると、特定のタブでサイドパネルを有効にできます。この例では、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() が導入されました。これにより、拡張機能は、アクションアイコンのクリックなどの拡張機能のユーザー操作でサイドパネルを開くことができます。拡張機能ページやコンテンツスクリプトでのユーザー操作（ボタンのクリックなど）です。完全なデモについては、Open Side Panel サンプル拡張機能をご覧ください。

次のコードは、ユーザーがコンテキストメニューをクリックしたときに現在のウィンドウでグローバルサイドパネルを開く方法を示しています。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.tabs.onActivated.addListener(async ({ tabId }) => {
  const { path } = await chrome.sidePanel.getOptions({ tabId });
  if (path === welcomePage) {
    chrome.sidePanel.setOptions({ path: mainPage });
  }
});

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

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

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

サイドパネルを開く

サイドパネルメニューに移動する: ユーザーはサイドパネルメニューに、利用可能なサイドパネルが表示されます。プルダウンメニューから広告表示オプションを選択します。

ユーザー操作で開く

サイドパネルは、次のような sidePanel.open() と sidePanel.setPanelBehavior() を使用してユーザー操作から開くことができます。

例

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

型

GetPanelOptions

プロパティ

tabId

number（省略可）

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

OpenOptions

Chrome 116 以降

プロパティ

tabId

number（省略可）

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

number（省略可）

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

PanelBehavior

プロパティ

openPanelOnActionClick

ブール値（省略可）

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

PanelOptions

プロパティ

有効

ブール値（省略可）

サイドパネルを有効にするかどうかを指定します。これは省略可能です。デフォルト値は true です。
パス

string（省略可）

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

number（省略可）

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

SidePanel

プロパティ

default_path

文字列

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

Methods

getOptions()

Promise

chrome.sidePanel.getOptions(
  options: GetPanelOptions,
  callback?: function,
)

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

パラメータ

オプション

GetPanelOptions

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

関数（省略可）

callback パラメータは次のようになります。
```
(options: PanelOptions)=>void
```
- オプション
  
  PanelOptions

戻り値

Promise<PanelOptions>

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

getPanelBehavior()

Promise

chrome.sidePanel.getPanelBehavior(
  callback?: function,
)

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

パラメータ

callback

関数（省略可）

callback パラメータは次のようになります。
```
(behavior: PanelBehavior)=>void
```
- 動作
  
  PanelBehavior

戻り値

Promise<PanelBehavior>

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

open()

Promise Chrome 116 以降

chrome.sidePanel.open(
  options: OpenOptions,
  callback?: function,
)

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

パラメータ

オプション

OpenOptions

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

関数（省略可）

callback パラメータは次のようになります。
```
()=>void
```

戻り値

Promise<void>

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

setOptions()

Promise

chrome.sidePanel.setOptions(
  options: PanelOptions,
  callback?: function,
)

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

パラメータ

オプション

PanelOptions

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

関数（省略可）

callback パラメータは次のようになります。
```
()=>void
```

戻り値

Promise<void>

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

setPanelBehavior()

Promise

chrome.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
  callback?: function,
)

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

パラメータ

動作

PanelBehavior

設定する新しい動作。
callback

関数（省略可）

callback パラメータは次のようになります。
```
()=>void
```

戻り値

Promise<void>

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

chrome.sidePanel

説明

権限

対象

コンセプトと使用方法

使用例

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

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

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

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

別のパネルに切り替える

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

サイドパネルを開く

例

型

GetPanelOptions

プロパティ

OpenOptions

プロパティ

PanelBehavior

プロパティ

PanelOptions

プロパティ

SidePanel

プロパティ

Methods

getOptions()

パラメータ

戻り値

getPanelBehavior()

パラメータ

戻り値

open()

パラメータ

戻り値

setOptions()

パラメータ

戻り値

setPanelBehavior()

パラメータ

戻り値

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

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