chrome.browserAction

更新日: 2026-09-25 robots: noindex

説明

ブラウザ アクションを使用すると、Google Chrome のメイン ツールバー（アドレスバーの右側）にアイコンを配置できます。ブラウザ アクションには、アイコンのほかに、ツールチップ、バッジ、ポップアップを設定できます。

対象

≤ MV2

次の図では、アドレスバーの右側にある色付きの四角形がブラウザ アクションのアイコンです。アイコンの下にポップアップが表示されている。

常にアクティブではないアイコンを作成する場合は、ブラウザ アクションではなくページ アクションを使用します。

マニフェスト

次のように、拡張機能マニフェストにブラウザ アクションを登録します。

{
  "name": "My extension",
  ...
  "browser_action": {
    "default_icon": {                // optional
      "16": "images/icon16.png",     // optional
      "24": "images/icon24.png",     // optional
      "32": "images/icon32.png"      // optional
    },
    "default_title": "Google Mail",  // optional, shown in tooltip
    "default_popup": "popup.html"    // optional
  },
  ...
}

Chrome で使用するアイコンは任意のサイズで指定できます。Chrome は、最も近いサイズを選択し、16 dip のスペースに合わせて適切なサイズにスケーリングします。ただし、正確なサイズが指定されていない場合、このスケーリングによってアイコンの詳細が失われたり、ぼやけたりすることがあります。

1.5 倍や 1.2 倍など、一般的でないスケーリング ファクタを持つデバイスが一般的になりつつあるため、アイコンには複数のサイズを用意することをおすすめします。また、アイコンの表示サイズが変更された場合でも、別のアイコンを用意する必要がなくなります。

デフォルトのアイコンを登録するための古い構文も引き続きサポートされています。

{
  "name": "My extension",
  ...
  "browser_action": {
    ...
    "default_icon": "images/icon32.png"  // optional
    // equivalent to "default_icon": { "32": "images/icon32.png" }
  },
  ...
}

UI の各部

ブラウザ アクションには、アイコン、ツールチップ、バッジ、ポップアップを設定できます。

アイコン

Chrome のブラウザ アクション アイコンの幅と高さは 16 dip（デバイス非依存ピクセル）です。これより大きいアイコンは、サイズが合うように変更されますが、最適な結果を得るには、16 dip の正方形のアイコンを使用してください。

アイコンを設定するには、静止画像を使用する方法と、HTML5 の canvas 要素を使用する方法の 2 つがあります。静止画像を使用する方が、シンプルなアプリケーションでは簡単ですが、canvas 要素を使用すると、スムーズなアニメーションなど、より動的な UI を作成できます。

静止画像は、WebKit で表示できる任意の形式（BMP、GIF、ICO、JPEG、PNG など）にすることができます。パッケージ化されていない拡張機能の場合、画像は PNG 形式にする必要があります。

アイコンを設定するには、マニフェストで default_icon の default_icon フィールドを使用するか、browserAction.setIcon メソッドを呼び出します。

画面のピクセル密度（比率 size_in_pixel / size_in_dip）が 1 以外の場合にアイコンを適切に表示するには、アイコンを異なるサイズの画像のセットとして定義します。表示する実際の画像は、16 dip のピクセルサイズに最も適合するようにセットから選択されます。アイコンセットには任意のサイズのアイコン仕様を含めることができ、Chrome は最も適切なものを選択します。

ツールチップ

ツールチップを設定するには、マニフェストで default_title の default_title フィールドを使用するか、browserAction.setTitle メソッドを呼び出します。default_title フィールドには、ロケール固有の文字列を指定できます。詳しくは、国際化をご覧ください。

バッジ

ブラウザ アクションでは、必要に応じてバッジ（アイコンの上に重ねて表示されるテキスト）を表示できます。 バッジを使用すると、ブラウザ アクションを簡単に更新して、拡張機能の状態に関する少量の情報を表示できます。

バッジのスペースは限られているため、4 文字以下にする必要があります。

browserAction.setBadgeText と browserAction.setBadgeBackgroundColor を使用して、バッジのテキストと色をそれぞれ設定します。

ブラウザ アクションにポップアップがある場合、ユーザーが拡張機能のアイコンをクリックするとポップアップが表示されます。ポップアップには任意の HTML コンテンツを含めることができ、コンテンツに合わせて自動的にサイズが調整されます。ポップアップのサイズは 25x25 以上、800x600 以下にする必要があります。

ブラウザ アクションにポップアップを追加するには、ポップアップのコンテンツを含む HTML ファイルを作成します。マニフェストの default_popup の default_popup フィールドで HTML ファイルを指定するか、browserAction.setPopup メソッドを呼び出します。

ヒント

視覚的な効果を最大限に高めるには、次のガイドラインに沿って作成してください。

  • 推奨: ほとんどのページで意味のある機能には、ブラウザ アクションを使用します。
  • 少数のページでのみ意味を持つ機能には、ブラウザ アクションを使用しないでください。代わりにページ アクションを使用してください。
  • 16x16 dip のスペースを最大限に活用した、大きくてカラフルなアイコンを使用します。ブラウザ アクション アイコンは、ページ アクション アイコンよりも少し大きく、重く見えるようにします。
  • Google Chrome のモノクロのメニュー アイコンを模倣しないでください。これはテーマとはうまく連携しません。いずれにしても、拡張機能は少し目立つようにする必要があります。
  • 推奨: アルファ透明度を使用して、アイコンにソフトなエッジを追加します。多くのユーザーがテーマを使用しているため、アイコンはさまざまな背景色に合うようにする必要があります。
  • アイコンを常にアニメーション化しないでください。これは面倒です。

例

ブラウザ アクションの使用例については、examples/api/browserAction ディレクトリをご覧ください。その他の例とソースコードの表示方法については、サンプルをご覧ください。

型

TabDetails

Chrome 88 以降

プロパティ

  • tabId

    number 省略可

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

メソッド

disable()

Promise 
chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
): Promise<void>

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

パラメータ

  • tabId

    number 省略可

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

  • callback

    function 省略可

    Chrome 67 以降

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Chrome 88 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

enable()

Promise 
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
): Promise<void>

タブのブラウザ アクションを有効にします。デフォルトは enabled です。

パラメータ

  • tabId

    number 省略可

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

  • callback

    function 省略可

    Chrome 67 以降

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Chrome 88 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

getBadgeBackgroundColor()

Promise 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
): Promise<extensionTypes.ColorArray>

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

パラメータ

  • 詳細

    TabDetails

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    (result: ColorArray) => void

戻り値

  • Chrome 88 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

getBadgeText()

Promise 
chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
): Promise<string>

ブラウザ アクションのバッジテキストを取得します。タブが指定されていない場合は、タブ固有でないバッジテキストが返されます。

パラメータ

  • 詳細

    TabDetails

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    (result: string) => void

    • 件の結果

      文字列

戻り値

  • Promise<string>

    Chrome 88 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

getPopup()

Promise 
chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
): Promise<string>

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

パラメータ

  • 詳細

    TabDetails

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    (result: string) => void

    • 件の結果

      文字列

戻り値

  • Promise<string>

    Chrome 88 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

getTitle()

Promise 
chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

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

パラメータ

  • 詳細

    TabDetails

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    (result: string) => void

    • 件の結果

      文字列

戻り値

  • Promise<string>

    Chrome 88 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

setBadgeBackgroundColor()

Promise 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
): Promise<void>

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

パラメータ

  • 詳細

    オブジェクト

    • 色

      文字列 | ColorArray

      バッジの RGBA カラーを構成する 0 ～ 255 の範囲の 4 つの整数の配列。CSS の 16 進数色コード値を含む文字列（#FF0000 や #F00（赤）など）にすることもできます。色を不透明度 100% でレンダリングします。

    • tabId

      number 省略可

      特定のタブが選択されたときにのみ変更を適用します。タブを閉じると自動的にリセットされます。

  • callback

    function 省略可

    Chrome 67 以降

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Chrome 88 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

setBadgeText()

Promise 
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
): Promise<void>

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

パラメータ

  • 詳細

    オブジェクト

    • tabId

      number 省略可

      特定のタブが選択されたときにのみ変更を適用します。タブを閉じると自動的にリセットされます。

    • テキスト

      文字列 省略可

      任意の数の文字を渡すことができますが、スペースに収まるのは 4 文字程度です。空の文字列（''）を渡すと、バッジテキストが消去されます。tabId が指定され、text が null の場合、指定されたタブのテキストは消去され、デフォルトでグローバル バッジのテキストになります。

  • callback

    function 省略可

    Chrome 67 以降

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Chrome 88 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

setIcon()

Promise 
chrome.browserAction.setIcon(
  details: object,
  callback?: function,
): 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 省略可

      特定のタブが選択されたときにのみ変更を適用します。タブを閉じると自動的にリセットされます。

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

setPopup()

Promise 
chrome.browserAction.setPopup(
  details: object,
  callback?: function,
): Promise<void>

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

パラメータ

  • 詳細

    オブジェクト

    • ポップアップ

      文字列

      ポップアップに表示する HTML ファイルの相対パス。空の文字列（''）に設定すると、ポップアップは表示されません。

    • tabId

      number 省略可

      特定のタブが選択されたときにのみ変更を適用します。タブを閉じると自動的にリセットされます。

  • callback

    function 省略可

    Chrome 67 以降

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Chrome 88 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

setTitle()

Promise 
chrome.browserAction.setTitle(
  details: object,
  callback?: function,
): Promise<void>

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

パラメータ

  • 詳細

    オブジェクト

    • tabId

      number 省略可

      特定のタブが選択されたときにのみ変更を適用します。タブを閉じると自動的にリセットされます。

    • title

      文字列

      マウスオーバー時にブラウザ アクションが表示する文字列。

  • callback

    function 省略可

    Chrome 67 以降

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Chrome 88 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

イベント

onClicked

chrome.browserAction.onClicked.addListener(
  callback: function,
)

ブラウザ アクション アイコンがクリックされたときに呼び出されます。ブラウザ アクションにポップアップがある場合は、起動しません。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (tab: tabs.Tab) => void