説明
chrome.action
API を使用すると、Google Chrome ツールバーの拡張機能のアイコンを制御できます。
対象
マニフェスト
chrome.action
API を使用するには、"manifest_version"
を 3
に指定し、マニフェスト ファイルに "action"
キーを含めます。
{
"name": "Action Extension",
...
"action": {
"default_icon": { // optional
"16": "images/icon16.png", // optional
"24": "images/icon24.png", // optional
"32": "images/icon32.png" // optional
},
"default_title": "Click Me", // optional, shown in tooltip
"default_popup": "popup.html" // optional
},
...
}
"action"
キーとその子は省略可能です。表示されていない場合は、拡張機能のメニューにアクセスできるようツールバーに引き続き表示されます。このため、常に少なくとも "action"
キーと "default_icon"
キーを含めることをおすすめします。
コンセプトと使用方法
UI の一部
icon
アイコンは拡張機能のツールバーに表示されるメイン画像で、マニフェストの "action"
キーの "default_icon"
キーで設定します。アイコンは、幅と高さが 16 個のデバイス非依存ピクセル(DIP)である必要があります。
"default_icon"
キーは、画像パスに対するサイズの辞書です。Chrome ではこれらのアイコンを使って
使用する画像スケールを選択します完全一致が見つからない場合は、最も近いものが選択され、画像に合わせて拡大縮小されます。これは画質に影響する可能性があります。
1.5x や 1.2x など、あまり一般的でないスケール係数を持つデバイスが一般的になりつつあるため、アイコンに複数のサイズを指定することをおすすめします。これにより、アイコンの表示サイズの変更に対しても拡張機能が対応します。
また、action.setIcon()
を呼び出して拡張機能のアイコンをプログラムで設定することもできます。そのためには、別の画像パスを指定するか、HTML キャンバス要素(拡張機能 Service Worker から設定する場合はオフスクリーン キャンバス API)を使用して動的に生成されるアイコンを指定します。
const canvas = new OffscreenCanvas(16, 16);
const context = canvas.getContext('2d');
context.clearRect(0, 0, 16, 16);
context.fillStyle = '#00FF00'; // Green
context.fillRect(0, 0, 16, 16);
const imageData = context.getImageData(0, 0, 16, 16);
chrome.action.setIcon({imageData: imageData}, () => { /* ... */ });
パッケージ化された拡張機能(.crx ファイルからインストール)の場合、画像は、PNG、JPEG、BMP、ICO など、Blink レンダリング エンジンで表示できるほとんどの形式を使用できます。SVG はサポートされていません。 パッケージ化されていない拡張機能では、PNG 画像を使用する必要があります。
ツールチップ(タイトル)
ツールチップ(タイトル)は、ユーザーがツールバーの拡張機能のアイコンにカーソルを合わせると表示されます。また、ボタンがフォーカスされたときにスクリーン リーダーによって読み上げられる、ユーザー補助機能用のテキストにも組み込まれます。
デフォルトのツールチップは、manifest.json
の "action"
キーの "default_title"
フィールドを使用して設定されます。action.setTitle()
を呼び出して、プログラムで設定することもできます。
バッジ
アクションでは、必要に応じて「バッジ」を表示できます。バッジとは、アイコンの上に重ねた少量のテキストです。これにより、アクションを更新して、拡張機能の状態に関する少量の情報(カウンタなど)を表示できます。バッジにはテキスト コンポーネントと背景色があります。スペースに限りがあるため、バッジテキストは 4 文字以下にすることをおすすめします。
バッジを作成するには、action.setBadgeBackgroundColor()
と action.setBadgeText()
を呼び出してプログラムでバッジを設定します。マニフェストにデフォルトのバッジ設定はありません。バッジの色の値は、バッジの RGBA カラーを構成する 0 ~ 255 の 4 つの整数の配列か、CSS の色値を含む文字列のいずれかです。
chrome.action.setBadgeBackgroundColor(
{color: [0, 255, 0, 0]}, // Green
() => { /* ... */ },
);
chrome.action.setBadgeBackgroundColor(
{color: '#00FF00'}, // Also green
() => { /* ... */ },
);
chrome.action.setBadgeBackgroundColor(
{color: 'green'}, // Also, also green
() => { /* ... */ },
);
ポップアップ
アクションのポップアップは、ユーザーがツールバーにある拡張機能のアクション ボタンをクリックしたときに表示されます。ポップアップには任意の HTML コンテンツを含めることができ、コンテンツに合わせてサイズが自動的に調整されます。ポップアップのサイズは 25x25 ~ 800x600 ピクセルにする必要があります。
ポップアップはまず、manifest.json
ファイルの "action"
キーの "default_popup"
プロパティで設定します。このプロパティが存在する場合は、拡張機能ディレクトリ内の相対パスを指す必要があります。action.setPopup()
メソッドを使用して、異なる相対パスを指すように動的に更新することもできます。
使用例
タブごとの状態
拡張機能の操作は、タブごとに異なるステータスになります。個々のタブの値を設定するには、action
API の設定メソッドの tabId
プロパティを使用します。たとえば、特定のタブのバッジテキストを設定するには、次のようにします。
function getTabId() { /* ... */}
function getTabBadge() { /* ... */}
chrome.action.setBadgeText(
{
text: getTabBadge(tabId),
tabId: getTabId(),
},
() => { ... }
);
tabId
プロパティを省略すると、設定はグローバル設定として扱われます。タブ固有の設定は、グローバル設定よりも優先されます。
有効状態
デフォルトでは、ツールバーの操作はすべてのタブで有効(クリック可能)になっています。これは、action.enable()
メソッドと action.disable()
メソッドを使用して制御できます。これは、ポップアップ(存在する場合)または action.onClicked
イベントが拡張機能に送信されるかどうかにのみ影響し、ツールバー内のアクションのプレゼンスには影響しません。
例
次の例は、拡張機能でアクションを使用する一般的な方法を示しています。この API を試すには、chrome-extension-samples リポジトリからアクション API の例をインストールします。
ポップアップを表示する
拡張機能のアクションがクリックされると、拡張機能がポップアップを表示するのは一般的です。独自の拡張機能でこれを実装するには、manifest.json
でポップアップを宣言し、Chrome がポップアップに表示するコンテンツを指定します。
// manifest.json
{
"name": "Action popup demo",
"version": "1.0",
"manifest_version": 3,
"action": {
"default_title": "Click to view a popup",
"default_popup": "popup.html"
}
}
<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
<style>
html {
min-height: 5em;
min-width: 10em;
background: salmon;
}
</style>
</head>
<body>
<p>Hello, world!</p>
</body>
</html>
クリック時にコンテンツ スクリプトを挿入する
拡張機能の一般的なパターンは、拡張機能のアクションを使用して主要な機能を公開することです。次の例は、このパターンを示しています。ユーザーがアクションをクリックすると、この拡張機能によって現在のページにコンテンツ スクリプトが挿入されます。コンテンツ スクリプトは、すべてが想定どおりに動作していることを確認するアラートを表示します。
// manifest.json
{
"name": "Action script injection demo",
"version": "1.0",
"manifest_version": 3,
"action": {
"default_title": "Click to show an alert"
},
"permissions": ["activeTab", "scripting"],
"background": {
"service_worker": "background.js"
}
}
// background.js
chrome.action.onClicked.addListener((tab) => {
chrome.scripting.executeScript({
target: {tabId: tab.id},
files: ['content.js']
});
});
// content.js
alert('Hello, world!');
declarativeContent を使用してアクションをエミュレートする
この例では、拡張機能のバックグラウンド ロジックで、(a)デフォルトでアクションを無効にし、(b)declarativeContent を使用して特定のサイトでアクションを有効にする方法を示しています。
// service-worker.js
// Wrap in an onInstalled callback to avoid unnecessary work
// every time the service worker is run
chrome.runtime.onInstalled.addListener(() => {
// Page actions are disabled by default and enabled on select tabs
chrome.action.disable();
// Clear all rules to ensure only our expected rules are set
chrome.declarativeContent.onPageChanged.removeRules(undefined, () => {
// Declare a rule to enable the action on example.com pages
let exampleRule = {
conditions: [
new chrome.declarativeContent.PageStateMatcher({
pageUrl: {hostSuffix: '.example.com'},
})
],
actions: [new chrome.declarativeContent.ShowAction()],
};
// Finally, apply our new array of rules
let rules = [exampleRule];
chrome.declarativeContent.onPageChanged.addRules(rules);
});
});
型
OpenPopupOptions
Properties
-
windowId
number(省略可)
アクションのポップアップを開くウィンドウの ID。指定しない場合のデフォルトは、現在アクティブなウィンドウです。
TabDetails
Properties
-
tabId
number(省略可)
状態をクエリするタブの ID。タブが指定されていない場合は、タブに固有ではない状態が返されます。
UserSettings
拡張機能のアクションに関連するユーザー指定の設定のコレクション。
Properties
-
isOnToolbar
boolean
ブラウザ ウィンドウの最上位のツールバーに拡張機能のアクション アイコンを表示するかどうか(ユーザーが拡張機能を「固定」しているかどうか)
Methods
disable()
chrome.action.disable(
tabId?: number,
callback?: function,
)
タブのアクションを無効にします。
パラメータ
-
tabId
number(省略可)
アクションを変更するタブの ID。
-
callback
関数(省略可)
callback
パラメータは次のようになります。()=>void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
enable()
chrome.action.enable(
tabId?: number,
callback?: function,
)
タブのアクションを有効にします。デフォルトでは、アクションは有効になっています。
パラメータ
-
tabId
number(省略可)
アクションを変更するタブの ID。
-
callback
関数(省略可)
callback
パラメータは次のようになります。()=>void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
getBadgeBackgroundColor()
chrome.action.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
アクションの背景色を取得します。
パラメータ
-
詳細
-
callback
関数(省略可)
callback
パラメータは次のようになります。(result: ColorArray)=>void
-
件の結果
-
戻り値
-
Promise<browserAction.ColorArray>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
getBadgeText()
chrome.action.getBadgeText(
details: TabDetails,
callback?: function,
)
アクションのバッジテキストを取得します。タブが指定されていない場合は、タブに固有ではないバッジテキストが返されます。displayActionCountAsBadgeText が有効になっている場合は、declarativeNetRequestFeedback 権限またはタブ固有のバッジテキストが指定されていない限り、プレースホルダ テキストが返されます。
パラメータ
-
詳細
-
callback
関数(省略可)
callback
パラメータは次のようになります。(result: string)=>void
-
件の結果
文字列
-
戻り値
-
Promise<文字列>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
getBadgeTextColor()
chrome.action.getBadgeTextColor(
details: TabDetails,
callback?: function,
)
アクションのテキストの色を取得します。
パラメータ
-
詳細
-
callback
関数(省略可)
callback
パラメータは次のようになります。(result: ColorArray)=>void
-
件の結果
-
戻り値
-
Promise<browserAction.ColorArray>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
getPopup()
chrome.action.getPopup(
details: TabDetails,
callback?: function,
)
このアクションのポップアップとして設定された html ドキュメントを取得します。
パラメータ
-
詳細
-
callback
関数(省略可)
callback
パラメータは次のようになります。(result: string)=>void
-
件の結果
文字列
-
戻り値
-
Promise<文字列>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
getTitle()
chrome.action.getTitle(
details: TabDetails,
callback?: function,
)
アクションのタイトルを取得します。
パラメータ
-
詳細
-
callback
関数(省略可)
callback
パラメータは次のようになります。(result: string)=>void
-
件の結果
文字列
-
戻り値
-
Promise<文字列>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
getUserSettings()
chrome.action.getUserSettings(
callback?: function,
)
拡張機能のアクションに関連するユーザー指定の設定を返します。
パラメータ
-
callback
関数(省略可)
callback
パラメータは次のようになります。(userSettings: UserSettings)=>void
-
userSettings
-
戻り値
-
Promise<UserSettings>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
isEnabled()
chrome.action.isEnabled(
tabId?: number,
callback?: function,
)
拡張機能のアクションがタブに対して有効かどうかを示します(tabId
が指定されていない場合はグローバル)。declarativeContent
のみを使用して有効にしたアクションは、常に false を返します。
パラメータ
-
tabId
number(省略可)
有効ステータスを確認するタブの ID。
-
callback
関数(省略可)
callback
パラメータは次のようになります。(isEnabled: boolean)=>void
-
isEnabled
boolean
拡張機能のアクションが有効な場合は true。
-
戻り値
-
Promise<boolean>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
openPopup()
chrome.action.openPopup(
options?: OpenPopupOptions,
callback?: function,
)
拡張機能のポップアップを開きます。
パラメータ
-
オプション
OpenPopupOptions 省略可
ポップアップを開くオプションを指定します。
-
callback
関数(省略可)
callback
パラメータは次のようになります。()=>void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
setBadgeBackgroundColor()
chrome.action.setBadgeBackgroundColor(
details: object,
callback?: function,
)
バッジの背景色を設定します。
パラメータ
-
詳細
オブジェクト
-
色
文字列|ColorArrayColorArray
バッジの RGBA カラーを構成する [0,255] の範囲の 4 つの整数の配列。たとえば、不透明な赤は
[255, 0, 0, 255]
です。CSS 値を含む文字列にすることもできます。不透明な赤は#FF0000
または#F00
です。 -
tabId
number(省略可)
特定のタブが選択された時点に限って変更します。タブを閉じると、自動的にリセットされます。
-
-
callback
関数(省略可)
callback
パラメータは次のようになります。()=>void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
setBadgeText()
chrome.action.setBadgeText(
details: object,
callback?: function,
)
アクションのバッジテキストを設定します。バッジはアイコンの上に表示されます。
パラメータ
-
詳細
オブジェクト
-
tabId
number(省略可)
特定のタブが選択された時点に限って変更します。タブを閉じると、自動的にリセットされます。
-
指定しています
string(省略可)
任意の数の文字を渡すことができますが、スペースに収まるのは約 4 文字のみです。空の文字列(
''
)が渡されると、バッジテキストはクリアされます。tabId
が指定され、text
が null の場合、指定したタブのテキストはクリアされ、デフォルトでグローバル バッジテキストになります。
-
-
callback
関数(省略可)
callback
パラメータは次のようになります。()=>void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
setBadgeTextColor()
chrome.action.setBadgeTextColor(
details: object,
callback?: function,
)
バッジのテキストの色を設定します。
パラメータ
-
詳細
オブジェクト
-
色
文字列|ColorArrayColorArray
バッジの RGBA カラーを構成する [0,255] の範囲の 4 つの整数の配列。たとえば、不透明な赤は
[255, 0, 0, 255]
です。CSS 値を含む文字列にすることもできます。不透明な赤は#FF0000
または#F00
です。この値を設定しない場合、バッジの背景色とコントラストが付く色が自動的に選択されるため、テキストが見えます。アルファ値が 0 の色は設定されず、エラーが返されます。 -
tabId
number(省略可)
特定のタブが選択された時点に限って変更します。タブを閉じると、自動的にリセットされます。
-
-
callback
関数(省略可)
callback
パラメータは次のようになります。()=>void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
setIcon()
chrome.action.setIcon(
details: object,
callback?: function,
)
アクションのアイコンを設定します。アイコンは、画像ファイルへのパス、キャンバス要素のピクセルデータ、またはこれらのいずれかの辞書として指定できます。path プロパティまたは imageData プロパティを指定する必要があります。
パラメータ
-
詳細
オブジェクト
-
imageData
ImageData|object(省略可)
ImageData オブジェクト、または設定するアイコンを表すディクショナリ {size -> ImageData}。アイコンを辞書として指定すると、画面のピクセル密度に応じて実際に使用される画像が選択されます。1 つの画面スペース ユニットに収まる画像のピクセル数が
scale
の場合、サイズがscale
× n の画像が選択されます。ここで、n は UI のアイコンのサイズです。画像を少なくとも 1 つ指定する必要があります。'details.imageData = foo' は 'details.imageData = {'16': foo}' と同等であることに注意してください。 -
パス
string|object(省略可)
相対画像パス、または設定するアイコンを指す辞書 {size -> 相対画像パス} のいずれか。アイコンを辞書として指定すると、画面のピクセル密度に応じて実際に使用される画像が選択されます。1 つの画面スペース ユニットに収まる画像のピクセル数が
scale
の場合、サイズがscale
× n の画像が選択されます。ここで、n は UI のアイコンのサイズです。画像を少なくとも 1 つ指定する必要があります。'details.path = foo' は 'details.path = {'16': foo}' と同等であることに注意してください。 -
tabId
number(省略可)
特定のタブが選択された時点に限って変更します。タブを閉じると、自動的にリセットされます。
-
-
callback
関数(省略可)
callback
パラメータは次のようになります。()=>void
戻り値
-
Promise<void>
Chrome 96 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
setPopup()
chrome.action.setPopup(
details: object,
callback?: function,
)
ユーザーがアクションのアイコンをクリックしたときにポップアップとして開く HTML ドキュメントを設定します。
パラメータ
-
詳細
オブジェクト
-
ポップアップ
文字列
ポップアップに表示する HTML ファイルの相対パス。空の文字列(
''
)に設定すると、ポップアップは表示されません。 -
tabId
number(省略可)
特定のタブが選択された時点に限って変更します。タブを閉じると、自動的にリセットされます。
-
-
callback
関数(省略可)
callback
パラメータは次のようになります。()=>void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
setTitle()
chrome.action.setTitle(
details: object,
callback?: function,
)
アクションのタイトルを設定します。これはツールチップに表示されます。
パラメータ
-
詳細
オブジェクト
-
tabId
number(省略可)
特定のタブが選択された時点に限って変更します。タブを閉じると、自動的にリセットされます。
-
title
文字列
マウスオーバー時にアクションに表示する文字列です。
-
-
callback
関数(省略可)
callback
パラメータは次のようになります。()=>void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。