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

chrome.sidePanel

説明

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

権限

sidePanel

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

manifest.json:

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

可用性

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

コンセプトと使用方法

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

サイドパネルのプルダウンメニュー — </ph> 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.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() を呼び出します。

アクションクリック
キーボードショートカット
コンテキストメニュー
拡張機能ページまたはコンテンツスクリプトでのユーザー操作。

サイドパネルを固定する

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

例

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

型

GetPanelOptions

プロパティ

tabId

数値（省略可）

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

OpenOptions

Chrome 116 以降

プロパティ

tabId

数値（省略可）

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

数値（省略可）

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

PanelBehavior

プロパティ

openPanelOnActionClick

ブール値（省略可）

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

PanelOptions

プロパティ

有効

ブール値（省略可）

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

文字列（省略可）

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

数値（省略可）

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

SidePanel

プロパティ

default_path

文字列

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

メソッド

getOptions()

<ph type="x-smartling-placeholder"></ph> 約束

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

アクティブなパネル設定を返します。

パラメータ

オプション

GetPanelOptions

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

関数（省略可）

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

戻り値

Promise<PanelOptions>

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

getPanelBehavior()

<ph type="x-smartling-placeholder"></ph> 約束

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

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

パラメータ

callback

関数（省略可）

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

戻り値

Promise<PanelBehavior>

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

open()

<ph type="x-smartling-placeholder"></ph> 約束 Chrome 116 以降をご覧ください。

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

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

パラメータ

オプション

OpenOptions

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

関数（省略可）

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

戻り値

約束 <void>

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

setOptions()

<ph type="x-smartling-placeholder"></ph> 約束

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

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

パラメータ

オプション

PanelOptions

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

関数（省略可）

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

戻り値

約束 <void>

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

setPanelBehavior()

<ph type="x-smartling-placeholder"></ph> 約束

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

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

パラメータ

動作

PanelBehavior

設定する新しい動作。
callback

関数（省略可）

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

戻り値

約束 <void>

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

chrome.sidePanel

説明

権限

可用性

コンセプトと使用方法

ユースケース

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

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

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

ユーザーの操作時にサイドパネルをプログラマティックに開く

別のパネルに切り替える

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

サイドパネルを開く

サイドパネルを固定する

例

型

GetPanelOptions

プロパティ

OpenOptions

プロパティ

PanelBehavior

プロパティ

PanelOptions

プロパティ

SidePanel

プロパティ

メソッド

getOptions()

パラメータ

戻り値

getPanelBehavior()

パラメータ

戻り値

open()

パラメータ

戻り値

setOptions()

パラメータ

戻り値

setPanelBehavior()

パラメータ

戻り値

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

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