Chrome で標準化された browser.* 名前空間がサポートされるようになりました（Chrome 148 以降で利用可能）。ドキュメントは順次更新されます。詳しくは、移行ガイドをご覧ください。

Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

browser.action

説明

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

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

対象

Chrome 88 以降 Chrome 148 以降の browser.* 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 はこれらのアイコンを使用して、使用する画像スケールを選択します。完全一致が見つからない場合、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}, () => { /* ... */ });

注: action.setIcon() API は、静止画像を設定することを目的としています。アイコンにアニメーション画像を使用しないでください。

パッケージ化された拡張機能（.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 コンテンツを含めることができ、コンテンツに合わせて自動的にサイズが調整されます。ポップアップのサイズは 25x25 ～ 800x600 ピクセルにする必要があります。

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

注: 拡張機能のアクションで、現在のタブをクリックしたときに表示されるポップアップが指定されている場合、action.onClicked イベントは送信されません。

ユースケース

タブごとの状態

拡張機能のアクションは、タブごとに異なる状態にすることができます。個々のタブに値を設定するには、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": "background.js"
  }
}

// background.js
browser.action.onClicked.addListener((tab) => {
  browser.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
browser.runtime.onInstalled.addListener(() => {
  // Page actions are disabled by default and enabled on select tabs
  browser.action.disable();

  // Clear all rules to ensure only our expected rules are set
  browser.declarativeContent.onPageChanged.removeRules(undefined, () => {
    // Declare a rule to enable the action on example.com pages
    let exampleRule = {
      conditions: [
        new browser.declarativeContent.PageStateMatcher({
          pageUrl: {hostSuffix: '.example.com'},
        })
      ],
      actions: [new browser.declarativeContent.ShowAction()],
    };

    // Finally, apply our new array of rules
    let rules = [exampleRule];
    browser.declarativeContent.onPageChanged.addRules(rules);
  });
});

型

OpenPopupOptions

Chrome 99 以降 Chrome 148 以降の browser.*

プロパティ

windowId

number 省略可

アクションポップアップを開くウィンドウの ID。指定しない場合、デフォルトで現在アクティブなウィンドウが使用されます。

TabDetails

プロパティ

tabId

number 省略可

状態をクエリするタブの ID。タブが指定されていない場合は、タブ固有ではない状態が返されます。

UserSettings

Chrome 91 以降 Chrome 148 以降の browser.*

拡張機能のアクションに関連するユーザー指定の設定のコレクション。

プロパティ

isOnToolbar

ブール値

拡張機能のアクションアイコンがブラウザウィンドウの最上位ツールバーに表示されるかどうか（つまり、拡張機能がユーザーによって「固定」されているかどうか）。

UserSettingsChange

Chrome 130 以降 Chrome 148 以降の browser.*

プロパティ

isOnToolbar

boolean 省略可

拡張機能のアクションアイコンがブラウザウィンドウの最上位ツールバーに表示されるかどうか（つまり、拡張機能がユーザーによって「固定」されているかどうか）。

メソッド

disable()

browser.action.disable(
  tabId?: number,
): Promise<void>

タブのアクションを無効にします。

パラメータ

tabId

number 省略可

アクションを変更するタブの ID。

戻り値

Promise<void>

enable()

browser.action.enable(
  tabId?: number,
): Promise<void>

タブのアクションを有効にします。デフォルトでは、アクションは有効になっています。

パラメータ

tabId

number 省略可

アクションを変更するタブの ID。

戻り値

Promise<void>

getBadgeBackgroundColor()

browser.action.getBadgeBackgroundColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

アクションの背景色を取得します。

パラメータ

詳細

TabDetails

戻り値

Promise<extensionTypes.ColorArray>

getBadgeText()

browser.action.getBadgeText(
  details: TabDetails,
): Promise<string>

アクションのバッジテキストを取得します。タブが指定されていない場合は、タブ固有ではないバッジテキストが返されます。displayActionCountAsBadgeText が有効になっている場合、declarativeNetRequestFeedback 権限が存在するか、タブ固有のバッジテキストが指定されていない限り、プレースホルダテキストが返されます。

パラメータ

詳細

TabDetails

戻り値

Promise<string>

getBadgeTextColor()

Chrome 110 以降 Chrome 148 以降の browser.*

browser.action.getBadgeTextColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

アクションのテキストの色を取得します。

パラメータ

詳細

TabDetails

戻り値

Promise<extensionTypes.ColorArray>

getPopup()

browser.action.getPopup(
  details: TabDetails,
): Promise<string>

このアクションのポップアップとして設定されている HTML ドキュメントを取得します。

パラメータ

詳細

TabDetails

戻り値

Promise<string>

getTitle()

browser.action.getTitle(
  details: TabDetails,
): Promise<string>

アクションのタイトルを取得します。

パラメータ

詳細

TabDetails

戻り値

Promise<string>

getUserSettings()

Chrome 91 以降 Chrome 148 以降の browser.*

browser.action.getUserSettings(): Promise<UserSettings>

拡張機能のアクションに関連するユーザー指定の設定を返します。

戻り値

Promise<UserSettings>

isEnabled()

Chrome 110 以降 Chrome 148 以降の browser.*

browser.action.isEnabled(
  tabId?: number,
): Promise<boolean>

拡張機能のアクションがタブで有効になっているかどうかを示します（tabId が指定されていない場合はグローバル）。declarativeContent のみを使用して有効にしたアクションは、常に false を返します。

パラメータ

tabId

number 省略可

有効なステータスを確認するタブの ID。

戻り値

Promise<boolean>

openPopup()

Chrome 127 以降 Chrome 148 以降の browser.*

browser.action.openPopup(
  options?: OpenPopupOptions,
): Promise<void>

拡張機能のポップアップを開きます。Chrome 118 から Chrome 126 の間は、ポリシーによってインストールされた拡張機能でのみ利用できます。

パラメータ

オプション

OpenPopupOptions 省略可

ポップアップを開くためのオプションを指定します。

戻り値

Promise<void>

setBadgeBackgroundColor()

browser.action.setBadgeBackgroundColor(
  details: object,
): Promise<void>

バッジの背景色を設定します。

パラメータ

詳細

オブジェクト
- 色
  
  文字列 | ColorArray
  
  バッジの RGBA カラーを構成する [0,255] の範囲の 4 つの整数の配列。たとえば、不透明な赤は [255, 0, 0, 255] です。CSS 値を含む文字列にすることもできます。不透明な赤は #FF0000 または #F00 です。
- tabId
  
  number 省略可
  
  特定のタブが選択されたときにのみ変更を適用します。タブを閉じると自動的にリセットされます。

戻り値

Promise<void>

setBadgeText()

browser.action.setBadgeText(
  details: object,
): Promise<void>

アクションのバッジテキストを設定します。バッジはアイコンの上に表示されます。

パラメータ

詳細

オブジェクト
- tabId
  
  number 省略可
  
  特定のタブが選択されたときにのみ変更を適用します。タブを閉じると自動的にリセットされます。
- テキスト
  
  文字列省略可
  
  任意の数の文字を渡すことができますが、スペースに収まるのは 4 文字程度です。空の文字列（''）を渡すと、バッジテキストが消去されます。tabId が指定され、text が null の場合、指定されたタブのテキストは消去され、デフォルトでグローバルバッジのテキストになります。

戻り値

Promise<void>

setBadgeTextColor()

Chrome 110 以降 Chrome 148 以降の browser.*

browser.action.setBadgeTextColor(
  details: object,
): Promise<void>

バッジのテキストの色を設定します。

パラメータ

詳細

オブジェクト
- 色
  
  文字列 | ColorArray
  
  バッジの RGBA カラーを構成する [0,255] の範囲の 4 つの整数の配列。たとえば、不透明な赤は [255, 0, 0, 255] です。CSS 値を含む文字列にすることもできます。不透明な赤は #FF0000 または #F00 です。この値を設定しないと、バッジの背景色と対照的な色が自動的に選択され、テキストが表示されます。アルファ値が 0 に相当する色は設定されず、エラーが返されます。
- tabId
  
  number 省略可
  
  特定のタブが選択されたときにのみ変更を適用します。タブを閉じると自動的にリセットされます。

戻り値

Promise<void>

setIcon()

browser.action.setIcon(
  details: object,
): Promise<void>

アクションのアイコンを設定します。アイコンは、画像ファイルへのパス、キャンバス要素のピクセルデータ、またはそのいずれかの辞書として指定できます。path プロパティまたは imageData プロパティのいずれかを指定する必要があります。

パラメータ

詳細

オブジェクト
- imageData
  
  ImageData | オブジェクト省略可
  
  ImageData オブジェクト、または設定するアイコンを表す辞書 {size -> ImageData}。アイコンを辞書として指定すると、画面のピクセル密度に応じて、使用する実際の画像が選択されます。1 つの画面スペース単位に収まる画像ピクセル数が scale の場合、サイズが scale * n の画像が選択されます。ここで、n は UI のアイコンのサイズです。画像を少なくとも 1 つ指定する必要があります。「details.imageData = foo」は「details.imageData = {'16': foo}」と同等です。
- パス
  
  文字列 | オブジェクト省略可
  
  相対画像パス、または設定するアイコンを指す辞書 {size -> relative image path}。アイコンを辞書として指定すると、画面のピクセル密度に応じて、使用する実際の画像が選択されます。1 つの画面スペース単位に収まる画像ピクセル数が scale の場合、サイズが scale * n の画像が選択されます。ここで、n は UI のアイコンのサイズです。画像を少なくとも 1 つ指定する必要があります。「details.path = foo」は「details.path = {'16': foo}」と同等です。
- tabId
  
  number 省略可
  
  特定のタブが選択されたときにのみ変更を適用します。タブを閉じると自動的にリセットされます。

戻り値

Promise<void>

Chrome 96 以降 Chrome 148 以降の browser.*

setPopup()

browser.action.setPopup(
  details: object,
): Promise<void>

ユーザーがアクションのアイコンをクリックしたときにポップアップとして開く HTML ドキュメントを設定します。

パラメータ

詳細

オブジェクト
- ポップアップ
  
  文字列
  
  ポップアップに表示する HTML ファイルの相対パス。空の文字列（''）に設定すると、ポップアップは表示されません。
- tabId
  
  number 省略可
  
  特定のタブが選択されたときにのみ変更を適用します。タブを閉じると自動的にリセットされます。

戻り値

Promise<void>

setTitle()

browser.action.setTitle(
  details: object,
): Promise<void>

アクションのタイトルを設定します。これはツールチップに表示されます。

パラメータ

詳細

オブジェクト
- tabId
  
  number 省略可
  
  特定のタブが選択されたときにのみ変更を適用します。タブを閉じると自動的にリセットされます。
- title
  
  文字列
  
  マウスオーバー時にアクションが表示する文字列。

戻り値

Promise<void>

イベント

onClicked

browser.action.onClicked.addListener(
  callback: function,
)

アクションアイコンがクリックされたときに呼び出されます。アクションにポップアップがある場合、このイベントは発生しません。

パラメータ

callback

関数

callback パラメータは次のようになります。
```
(tab: tabs.Tab) => void
```
- タブ
  
  tabs.Tab

onUserSettingsChanged

Chrome 130 以降 Chrome 148 以降の browser.*

browser.action.onUserSettingsChanged.addListener(
  callback: function,
)

拡張機能のアクションに関連するユーザー指定の設定が変更されたときに呼び出されます。

パラメータ

callback

関数

callback パラメータは次のようになります。
```
(change: UserSettingsChange) => void
```
- 変更
  
  UserSettingsChange

browser.action コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

説明

対象

マニフェスト

コンセプトと使用方法

UI の各部

アイコン

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

バッジ

ポップアップ

ユースケース

タブごとの状態

有効な状態

例

ポップアップを表示する

クリック時にコンテンツ スクリプトを挿入する

declarativeContent を使用してアクションをエミュレートする

型

OpenPopupOptions

プロパティ

TabDetails

プロパティ

UserSettings

プロパティ

UserSettingsChange

プロパティ

メソッド

disable()

パラメータ

戻り値

enable()

パラメータ

戻り値

getBadgeBackgroundColor()

パラメータ

戻り値

getBadgeText()

パラメータ

戻り値

getBadgeTextColor()

パラメータ

戻り値

getPopup()

パラメータ

戻り値

getTitle()

パラメータ

戻り値

getUserSettings()

戻り値

isEnabled()

パラメータ

戻り値

openPopup()

パラメータ

戻り値

setBadgeBackgroundColor()

パラメータ

戻り値

setBadgeText()

パラメータ

戻り値

setBadgeTextColor()

パラメータ

戻り値

setIcon()

パラメータ

戻り値

setPopup()

パラメータ

戻り値

setTitle()

パラメータ

戻り値

イベント

onClicked

パラメータ

onUserSettingsChanged

パラメータ

browser.action

クリック時にコンテンツスクリプトを挿入する