chrome.browserAction

説明

ブラウザの操作を使用して、メインの 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 ディップのスペースを埋めるように適切なサイズに拡大縮小します。ただし、正確なサイズを指定しないと、このスケーリングにより、アイコンの細部が失われたり、不鮮明になったりすることがあります。

1.5x や 1.2x など、あまり一般的でないスケール係数を持つデバイスが一般的になりつつあるため、アイコンに複数のサイズを指定することをおすすめします。また、これにより、アイコンの表示サイズが変更された場合に、異なるアイコンを提供するために追加の作業を行う必要がなくなります。

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

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

UI の一部

ブラウザの操作には、アイコン、ツールチップ、バッジ、ポップアップなどがあります。

icon

Chrome のブラウザ操作アイコンは、幅 / 高さが 16 ディップ（デバイス非依存ピクセル）になっています。大きいアイコンは収まるようにサイズが変更されますが、16 のディップの正方形のアイコンを使用することをおすすめします。

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

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

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

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

ツールチップ

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

バッジ

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

バッジの文字数は限られているため、文字数は 4 文字以下にしてください。

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

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

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

ヒント

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

  • ほとんどのページで有効な機能にブラウザ アクションを使用する。
  • 少数のページでしか意味がない機能には、ブラウザ操作を使用しないでください。代わりにページ アクションを使用してください。
  • 16x16 のディップ領域を最大限に活用するため、大きくカラフルなアイコンを使用する。ブラウザ アクション アイコンは、ページ アクション アイコンよりも少し大きくて重いように見えるはずです。
  • Google Chrome のモノクロ メニュー アイコンを模倣しないでください。これはテーマには適していませんが、拡張機能は少し目立つ必要があります。
  • アルファ透明度を使用してアイコンに柔らかいエッジを追加してください。テーマは多くの人が使用するため、アイコンはさまざまな背景色で適切に表示される必要があります。
  • アイコンを常にアニメーション化しないでください。それはイライラするだけ。

例

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

型

ColorArray

タイプ

[数値,数値,数値,数値]

ImageDataType

画像のピクセルデータ。ImageData オブジェクト（canvas 要素など）にする必要があります。

タイプ

ImageData

TabDetails

Chrome 88 以降

プロパティ

  • tabId

    number（省略可）

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

Methods

disable()

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

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

パラメータ

  • tabId

    number（省略可）

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

  • callback

    関数（省略可）

    Chrome 67 以降

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

    ()=>void

戻り値

  • Promise<void>

    Chrome 88 以降

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

enable()

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

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

パラメータ

  • tabId

    number（省略可）

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

  • callback

    関数（省略可）

    Chrome 67 以降

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

    ()=>void

戻り値

  • Promise<void>

    Chrome 88 以降

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

getBadgeBackgroundColor()

Promise 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

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

パラメータ

  • 詳細

    TabDetails

  • callback

    関数（省略可）

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

    (result: ColorArray)=>void

戻り値

  • Promise<ColorArray>

    Chrome 88 以降

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

getBadgeText()

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

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

パラメータ

  • 詳細

    TabDetails

  • callback

    関数（省略可）

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

    (result: string)=>void

    • 件の結果

      文字列

戻り値

  • Promise<文字列>

    Chrome 88 以降

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

getPopup()

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

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

パラメータ

  • 詳細

    TabDetails

  • callback

    関数（省略可）

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

    (result: string)=>void

    • 件の結果

      文字列

戻り値

  • Promise<文字列>

    Chrome 88 以降

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

getTitle()

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

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

パラメータ

  • 詳細

    TabDetails

  • callback

    関数（省略可）

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

    (result: string)=>void

    • 件の結果

      文字列

戻り値

  • Promise<文字列>

    Chrome 88 以降

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

setBadgeBackgroundColor()

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

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

パラメータ

  • 詳細

    オブジェクト

    • 色

      文字列|ColorArrayColorArray

      バッジの RGBA カラーを構成する 0 ～ 255 の範囲の 4 つの整数の配列。CSS の 16 進数色コードを持つ文字列も使用できます（例: #FF0000、#F00（赤）。）完全な不透明度で色をレンダリングします。

    • tabId

      number（省略可）

      特定のタブが選択された時点に限って変更します。タブを閉じると、自動的にリセットされます。

  • callback

    関数（省略可）

    Chrome 67 以降

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

    ()=>void

戻り値

  • Promise<void>

    Chrome 88 以降

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

setBadgeText()

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

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

パラメータ

  • 詳細

    オブジェクト

    • tabId

      number（省略可）

      特定のタブが選択された時点に限って変更します。タブを閉じると、自動的にリセットされます。

    • 指定しています

      string（省略可）

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

  • callback

    関数（省略可）

    Chrome 67 以降

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

    ()=>void

戻り値

  • Promise<void>

    Chrome 88 以降

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

setIcon()

Promise 
chrome.browserAction.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 116 以降

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

setPopup()

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

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

パラメータ

  • 詳細

    オブジェクト

    • ポップアップ

      文字列

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

    • tabId

      number（省略可）

      特定のタブが選択された時点に限って変更します。タブを閉じると、自動的にリセットされます。

  • callback

    関数（省略可）

    Chrome 67 以降

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

    ()=>void

戻り値

  • Promise<void>

    Chrome 88 以降

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

setTitle()

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

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

パラメータ

  • 詳細

    オブジェクト

    • tabId

      number（省略可）

      特定のタブが選択された時点に限って変更します。タブを閉じると、自動的にリセットされます。

    • title

      文字列

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

  • callback

    関数（省略可）

    Chrome 67 以降

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

    ()=>void

戻り値

  • Promise<void>

    Chrome 88 以降

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

イベント

onClicked

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

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

パラメータ

  • callback

    機能

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

    (tab: tabs.Tab)=>void