browser.action

説明

chrome.action API を使用して、Google Chrome ツールバーの拡張機能のアイコンを制御します。

アクション アイコンは、ブラウザのツールバーのアドレスバーの横に表示されます。インストール後、拡張機能メニュー（パズルピース アイコン）に表示されます。ユーザーは拡張機能のアイコンをツールバーに固定できます。

対象

Chrome 88 以降 MV3 以降

マニフェスト

この API を使用するには、次のキーをマニフェストで宣言する必要があります。

"action"

browser.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 の各部分

アイコン

アイコンは、拡張機能のツールバーのメイン画像であり、マニフェストの "action" キーの "default_icon" キーで設定されます。アイコンの幅と高さは 16 デバイス独立ピクセル（DIP）にする必要があります。

"default_icon" キーは、サイズと画像パスのディクショナリです。Chrome はこれらのアイコンを使用して、使用する画像スケールを選択します。完全一致が見つからない場合は、最も近いものが選択され、画像に合わせてスケーリングされます。このため、画質に影響する可能性があります。

1.5 倍や 1.2 倍などの一般的でないスケール ファクタを持つデバイスが増えているため、アイコンの複数のサイズを提供することをおすすめします。これにより、アイコンの表示サイズが変更される可能性にも対応できます。ただし、1 つのサイズのみを指定する場合は、"default_icon" キーを辞書ではなく、1 つのアイコンのパスを含む文字列に設定することもできます。

また、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);
browser.action.setIcon({imageData: imageData}, () => { /* ... */ });

パッケージ化された拡張機能（.crx ファイルからインストールされたもの）の場合、画像は Blink レンダリング エンジンで表示できるほとんどの形式（PNG、JPEG、BMP、ICO など）で指定できます。SVG はサポートされていません。展開された拡張機能では PNG 画像を使用する必要があります。

ツールチップ（タイトル）

ツールチップ（タイトル）は、ユーザーがツールバーで拡張機能のアイコンにマウスポインタを合わせたときに表示されます。また、ボタンにフォーカスが当たったときにスクリーン リーダーが読み上げるユーザー補助機能テキストにも含まれます。

デフォルトのツールチップは、manifest.json の "action" キーの "default_title" フィールドを使用して設定されます。action.setTitle() を呼び出してプログラムで設定することもできます。

バッジ

アクションでは、アイコンの上に重ねて表示されるテキスト「バッジ」をオプションで表示できます。これにより、アクションを更新して、拡張機能の状態に関する少量の情報（カウンタなど）を表示できます。バッジにはテキスト コンポーネントと背景色があります。スペースが限られているため、バッジのテキストは 4 文字以下にすることをおすすめします。

バッジを作成するには、action.setBadgeBackgroundColor() と action.setBadgeText() を呼び出してプログラムで設定します。マニフェストにデフォルトのバッジ設定はありません。バッジの色値は、バッジの RGBA 色を構成する 0 ～ 255 の 4 つの整数の配列、または CSS 色の値を含む文字列のいずれかです。

browser.action.setBadgeBackgroundColor(
  {color: [0, 255, 0, 0]},  // Green
  () => { /* ... */ },
);

browser.action.setBadgeBackgroundColor(
  {color: '#00FF00'},  // Also green
  () => { /* ... */ },
);

browser.action.setBadgeBackgroundColor(
  {color: 'green'},  // Also, also green
  () => { /* ... */ },
);

ユーザーがツールバーの拡張機能の操作ボタンをクリックすると、アクションのポップアップが表示されます。ポップアップには任意の HTML コンテンツを含めることができ、コンテンツに合わせて自動的にサイズが調整されます。ポップアップのサイズは 25×25 ～ 800×600 ピクセルの範囲で指定する必要があります。

ポップアップは、最初は manifest.json ファイルの "action" キーの "default_popup" プロパティによって設定されます。存在する場合、このプロパティは拡張機能ディレクトリ内の相対パスを指す必要があります。また、action.setPopup() メソッドを使用して、別の相対パスを指すように動的に更新することもできます。

ユースケース

タブごとの状態

拡張機能のアクションは、タブごとに異なる状態を持つことができます。個々のタブの値を設定するには、action API の設定メソッドで tabId プロパティを使用します。たとえば、特定のタブのバッジ テキストを設定するには、次のようにします。

function getTabId() { /* ... */}
function getTabBadge() { /* ... */}

browser.action.setBadgeText(
  {
    text: getTabBadge(tabId),
    tabId: getTabId(),
  },
  () => { ... }
);

tabId プロパティが省略されている場合、設定はグローバル設定として扱われます。タブ固有の設定は、グローバル設定よりも優先されます。

有効状態

デフォルトでは、ツールバーの操作はすべてのタブで有効（クリック可能）になっています。このデフォルトを変更するには、マニフェストの action キーで default_state プロパティを設定します。default_state が "disabled" に設定されている場合、アクションはデフォルトで無効になっており、クリック可能にするにはプログラムで有効にする必要があります。default_state が "enabled"（デフォルト）に設定されている場合、アクションはデフォルトで有効になり、クリック可能になります。

action.enable() メソッドと action.disable() メソッドを使用すると、状態をプログラムで制御できます。これは、ポップアップ（存在する場合）または action.onClicked イベントが拡張機能に送信されるかどうかにのみ影響します。ツールバーでのアクションの存在には影響しません。

例

次の例は、拡張機能でアクションが使用される一般的な方法を示しています。この API を試すには、chrome-extension-samples リポジトリから Action 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":