chrome.browserAction

説明

ブラウザ操作を使用して、Google Chrome のメイン ツールバーのアドレスバーの右にアイコンを配置します。ブラウザのアクションには、アイコンに加えて、ツールチップ、バッジ、ポップアップを表示できます。

対象

<ph type="x-smartling-placeholder"></ph> &amp;leq;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.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 ディップ（デバイス非依存ピクセル）です。拡大 アイコンはサイズに合わせて調整されますが、最良の結果を得るには、16 ディップの正方形のアイコンを使用してください。

アイコンを設定するには、静止画像を使用する方法と、HTML5 のキャンバス要素を使用する方法があります。使用 シンプルなアプリケーションでは静的画像のほうが簡単ですが、 キャンバス要素を使用して、滑らかなアニメーションにできます。

静止画像は、WebKit で表示できるすべての形式（BMP、GIF、ICO、JPEG、PNG など）を使用できます。対象 画像は PNG 形式にする必要があります。

アイコンを設定するには、manifest の browser_action の default_icon フィールドを使用するか、 browserAction.setIcon メソッドを使用します。

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

ツールチップ

ツールチップを設定するには、manifest の browser_action の 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

    数値（省略可）

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

メソッド

disable()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
)

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

パラメータ

  • tabId

    数値（省略可）

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

  • callback

    関数（省略可）

    Chrome 67 以降

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

    () => void

戻り値

  • 約束 <void>

    Chrome 88 以降

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

enable()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
)

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

パラメータ

  • tabId

    数値（省略可）

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

  • callback

    関数（省略可）

    Chrome 67 以降

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

    () => void

戻り値

  • 約束 <void>

    Chrome 88 以降

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

getBadgeBackgroundColor()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

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

パラメータ

  • 詳細

    TabDetails

  • callback

    関数（省略可）

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

    (result: ColorArray) => void

戻り値

  • Promise&lt;ColorArray&gt;

    Chrome 88 以降

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

getBadgeText()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
)

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

パラメータ

  • 詳細

    TabDetails

  • callback

    関数（省略可）

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

    (result: string) => void

    • 件の結果

      文字列

戻り値

  • Promise<文字列>

    Chrome 88 以降

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

getPopup()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
)

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

パラメータ

  • 詳細

    TabDetails

  • callback

    関数（省略可）

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

    (result: string) => void

    • 件の結果

      文字列

戻り値

  • Promise<文字列>

    Chrome 88 以降

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

getTitle()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
)

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

パラメータ

  • 詳細

    TabDetails

  • callback

    関数（省略可）

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

    (result: string) => void

    • 件の結果

      文字列

戻り値

  • Promise<文字列>

    Chrome 88 以降

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

setBadgeBackgroundColor()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

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

パラメータ

  • 詳細

    オブジェクト

    • 色

      string |ColorArray

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

    • tabId

      数値（省略可）

      特定のタブが選択されている場合のみ変更を制限します。タブを閉じると、自動的にリセットされます。

  • callback

    関数（省略可）

    Chrome 67 以降

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

    () => void

戻り値

  • 約束 <void>

    Chrome 88 以降

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

setBadgeText()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
)

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

パラメータ

  • 詳細

    オブジェクト

    • tabId

      数値（省略可）

      特定のタブが選択されている場合のみ変更を制限します。タブを閉じると、自動的にリセットされます。

    • テキスト

      文字列（省略可）

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

  • callback

    関数（省略可）

    Chrome 67 以降

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

    () => void

戻り値

  • 約束 <void>

    Chrome 88 以降

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

setIcon()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.browserAction.setIcon(
  details: object,
  callback?: function,
)

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

パラメータ

  • 詳細

    オブジェクト

    • imageData

      ImageData |オブジェクト（省略可）

      ImageData オブジェクトまたは辞書 {size ->ImageData} です。アイコンを辞書として指定すると、画面のピクセル密度に応じて使用される画像が選択されます。1 つの画面スペース ユニットに収まる画像ピクセル数が scale の場合、scale × n のサイズの画像が選択されます。ここで、n は UI のアイコンのサイズです。画像を少なくとも 1 つ指定する必要があります。なお、「details.imageData = foo」'details.imageData = {'16': foo}' と同等です。

    • パス

      string |オブジェクト（省略可）

      相対画像パスまたは辞書 {size ->相対画像パス} で、設定するアイコンを指します。アイコンを辞書として指定すると、画面のピクセル密度に応じて使用される画像が選択されます。1 つの画面スペース ユニットに収まる画像ピクセル数が scale の場合、scale × n のサイズの画像が選択されます。ここで、n は UI のアイコンのサイズです。画像を少なくとも 1 つ指定する必要があります。なお、「details.path = foo」'details.path = {'16': foo}' と同等です。

    • tabId

      数値（省略可）

      特定のタブが選択されている場合のみ変更を制限します。タブを閉じると、自動的にリセットされます。

  • callback

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

    Chrome 116 以降

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

setPopup()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.browserAction.setPopup(
  details: object,
  callback?: function,
)

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

パラメータ

  • 詳細

    オブジェクト

    • ポップアップ

      文字列

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

    • tabId

      数値（省略可）

      特定のタブが選択されている場合のみ変更を制限します。タブを閉じると、自動的にリセットされます。

  • callback

    関数（省略可）

    Chrome 67 以降

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

    () => void

戻り値

  • 約束 <void>

    Chrome 88 以降

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

setTitle()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.browserAction.setTitle(
  details: object,
  callback?: function,
)

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

パラメータ

  • 詳細

    オブジェクト

    • tabId

      数値（省略可）

      特定のタブが選択されている場合のみ変更を制限します。タブを閉じると、自動的にリセットされます。

    • title

      文字列

      カーソルを合わせたときにブラウザ アクションを表示する文字列です。

  • callback

    関数（省略可）

    Chrome 67 以降

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

    () => void

戻り値

  • 約束 <void>

    Chrome 88 以降

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

イベント

onClicked

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

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

パラメータ

  • callback

    関数

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

    (tab: tabs.Tab) => void