説明
chrome.sidePanel
API を使用すると、ウェブページのメイン コンテンツとともにブラウザのサイドパネルでコンテンツをホストできます。
権限
sidePanel
Side Panel API を使用するには、拡張機能 manifest ファイルに "sidePanel"
権限を追加します。
manifest.json:
{
"name": "My side panel extension",
...
"permissions": [
"sidePanel"
]
}
可用性
コンセプトと使用方法
Side Panel API を使用すると、拡張機能がサイドパネルに独自の 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
number(省略可)
指定すると、そのタブのサイドパネル オプションが返されます。それ以外の場合は、デフォルトのサイドパネル オプションを返します(特定の設定がないタブに使用されます)。
OpenOptions
プロパティ
-
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
文字列
デベロッパーがサイドパネル ディスプレイのパスを指定しました。
メソッド
getOptions()
chrome.sidePanel.getOptions(
options: GetPanelOptions,
callback?: function,
)
アクティブなパネル構成を返します。
パラメータ
-
オプション
構成を返すコンテキストを指定します。
-
callback
関数(省略可)
callback
パラメータは次のようになります。(options: PanelOptions) => void
-
オプション
-
戻り値
-
Promise<PanelOptions>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
getPanelBehavior()
chrome.sidePanel.getPanelBehavior(
callback?: function,
)
拡張機能の現在のサイドパネルの動作を返します。
パラメータ
-
callback
関数(省略可)
callback
パラメータは次のようになります。(behavior: PanelBehavior) => void
戻り値
-
Promise<PanelBehavior>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
open()
chrome.sidePanel.open(
options: OpenOptions,
callback?: function,
)
拡張機能のサイドパネルを開きます。ユーザーの操作に応じてのみ呼び出すことができます。
パラメータ
-
オプション
サイドパネルを開くコンテキストを指定します。
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
setOptions()
chrome.sidePanel.setOptions(
options: PanelOptions,
callback?: function,
)
サイドパネルを設定します。
パラメータ
-
オプション
パネルに適用する構成オプション。
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
setPanelBehavior()
chrome.sidePanel.setPanelBehavior(
behavior: PanelBehavior,
callback?: function,
)
拡張機能のサイドパネルの動作を設定します。これは upsert オペレーションです。
パラメータ
-
設定する新しい動作。
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。