chrome.action

説明

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

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

対象

Chrome 88 以降 MV3 以降 をご覧ください。

マニフェスト

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

"action"

chrome.action API を使用するには、"manifest_version" として 3 を指定し、 マニフェスト ファイルの "action" キー。

注: "action" キーがマニフェストに追加されていなくても、すべての拡張機能には Chrome ツールバーにアイコンが表示されます。

{
  "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 の一部

アイコン

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

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

1.5 倍や 1.2 倍など、あまり一般的でないスケール ファクタのデバイスは、 アイコンには複数のサイズを指定することをおすすめします。また、 アイコンの表示サイズの変化に対して拡張機能を将来にわたって保証します。ただし、 サイズを 1 つだけ指定する場合は、"default_icon" キーを ディクショナリではなく 1 つのアイコンへのパスに置き換える必要があります。

action.setIcon() を呼び出して、拡張機能のアイコンをプログラムで設定することもできます。 別の画像パスを指定するか、HTML キャンバスを使用して動的に生成されるアイコンを指定します。 要素で示されます。拡張機能の Service Worker から設定されている場合は、画面外 canvas 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);
chrome.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() を呼び出して、プログラムで設定します。マニフェストにデフォルトのバッジ設定はありません。バッジの色の値 は、0 ～ 255 の 4 つの整数の配列で、RGBA カラーです。 バッジや、CSS の色値を含む文字列です。

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

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

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

ポップアップ

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

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

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

ユースケース

タブごとの状態

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

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

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

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

有効状態

デフォルトでは、すべてのタブでツールバーのアクションが有効（クリック可能）になっています。これは、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
chrome.action.onClicked.addListener((tab) => {
  chrome.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
chrome.runtime.onInstalled.addListener(() => {
  // Page actions are disabled by default and enabled on select tabs
  chrome.action.disable();

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

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

型

OpenPopupOptions

Chrome 99 以降

プロパティ

• windowId

  数値（省略可）

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

TabDetails

プロパティ

• tabId

  number（省略可）

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

UserSettings

Chrome 91 以降

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

プロパティ

• isOnToolbar

  ブール値

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

UserSettingsChange

Chrome 130 以降

プロパティ

• isOnToolbar

  ブール値（省略可）

  拡張機能のアクション アイコンをブラウザ ウィンドウに表示するかどうかトップレベル ツールバー（ユーザーが拡張機能を「固定」しているかどうか）を確認します。

メソッド

disable()

<ph type="x-smartling-placeholder"></ph> 約束

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

タブの操作を無効にします。

パラメータ

• tabId

  数値（省略可）

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

• callback

  function 省略可

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

  () => void

戻り値

• 約束 <void>

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

enable()

Promise

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

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

パラメータ

• tabId

  数値（省略可）

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

• callback

  関数（省略可）

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

  () => void

戻り値

• 約束 <void>

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

getBadgeBackgroundColor()

<ph type="x-smartling-placeholder"></ph> 約束

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

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

パラメータ

• 詳細

  TabDetails

• callback

  関数（省略可）

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

  (result: ColorArray) => void

  • 件の結果

    ColorArray

戻り値

• Promise&lt;browserAction.ColorArray&gt;

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

getBadgeText()

<ph type="x-smartling-placeholder"></ph> 約束

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

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

パラメータ

• 詳細

  TabDetails

• callback

  関数（省略可）

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

  (result: string) => void

  • 件の結果

    文字列

戻り値

• Promise<string>

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

getBadgeTextColor()

Promise Chrome 110 以降

chrome.action.getBadgeTextColor(
  details: TabDetails,
  callback?: function,
)

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

パラメータ

• 詳細

  TabDetails

• callback

  関数（省略可）

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

  (result: ColorArray) => void

  • 件の結果

    ColorArray

戻り値

• Promise&lt;browserAction.ColorArray&gt;

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

getPopup()

<ph type="x-smartling-placeholder"></ph> 約束

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

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

パラメータ

• 詳細

  TabDetails

• callback

  関数（省略可）

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

  (result: string) => void

  • 件の結果

    文字列

戻り値

• Promise<string>

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

getTitle()

<ph type="x-smartling-placeholder"></ph> 約束

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

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

パラメータ

• 詳細

  TabDetails

• callback

  function 省略可

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

  (result: string) => void

  • 件の結果

    文字列

戻り値

• Promise<string>

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

getUserSettings()

<ph type="x-smartling-placeholder"></ph> 約束 Chrome 91 以降 をご覧ください。

chrome.action.getUserSettings(
  callback?: function,
)

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

パラメータ

• callback

  関数（省略可）

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

  (userSettings: UserSettings) => void

  • userSettings

    UserSettings

戻り値

• Promise&lt;UserSettings&gt;

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

isEnabled()

<ph type="x-smartling-placeholder"></ph> 約束 Chrome 110 以降 をご覧ください。

chrome.action.isEnabled(
  tabId?: number,
  callback?: function,
)

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

パラメータ

• tabId

  数値（省略可）

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

• callback

  関数（省略可）

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

  (isEnabled: boolean) => void

  • isEnabled

    ブール値

    拡張機能のアクションが有効になっている場合は true です。

戻り値

• Promise&lt;boolean&gt;

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

openPopup()

Promise Chrome 127 以降

chrome.action.openPopup(
  options?: OpenPopupOptions,
  callback?: function,
)

拡張機能のポップアップを開きます。Chrome 118～Chrome 126 では、ポリシーでインストールされた拡張機能でのみ使用できます。

パラメータ

• オプション

  OpenPopupOptions（省略可）

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

• callback

  関数（省略可）

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

  () => void

戻り値

• 約束 <void>

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

setBadgeBackgroundColor()

<ph type="x-smartling-placeholder"></ph> 約束

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

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

パラメータ

• 詳細

  オブジェクト

  • 色

    文字列 | ColorArray

    バッジの RGBA カラーを構成する [0,255] の範囲の 4 つの整数の配列。たとえば、不透明な赤は [255, 0, 0, 255] です。CSS 値を含む文字列にすることもできます（不透明な赤は #FF0000 または #F00）。

  • tabId

    number（省略可）

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

• callback

  関数（省略可）

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

  () => void

戻り値

• 約束 <void>

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

setBadgeText()

<ph type="x-smartling-placeholder"></ph> 約束

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

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

パラメータ

• 詳細

  オブジェクト

  • tabId

    number（省略可）

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

  • テキスト

    文字列（省略可）

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

• callback

  function 省略可

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

  () => void

戻り値

• 約束 <void>

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

setBadgeTextColor()

Promise Chrome 110 以降

chrome.action.setBadgeTextColor(
  details: object,
  callback?: function,
)

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

パラメータ

• 詳細

  オブジェクト

  • 色

    文字列 | ColorArray

    バッジの RGBA カラーを構成する [0,255] の範囲の 4 つの整数の配列。たとえば、不透明な赤は [255, 0, 0, 255] です。CSS 値を含む文字列にすることもできます（不透明な赤は #FF0000 または #F00）。この値を設定しないと、バッジの背景色と対照的な色が自動的に選択され、テキストが見えるようになります。アルファ値が 0 に相当する色は設定されず、エラーが返されます。

  • tabId

    number（省略可）

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

• callback

  関数（省略可）

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

  () => void

戻り値

• 約束 <void>

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

setIcon()

<ph type="x-smartling-placeholder"></ph> 約束

chrome.action.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}」と同じです。

  • パス

    文字列 | オブジェクト（省略可）

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

  • tabId

    number（省略可）

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

• callback

  function 省略可

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

  () => void

戻り値

• 約束 <void>

  Chrome 96 以降

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

setPopup()

<ph type="x-smartling-placeholder"></ph> 約束

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

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

パラメータ

• 詳細

  オブジェクト

  • ポップアップ

    文字列

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

  • tabId

    number（省略可）

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

• callback

  関数（省略可）

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

  () => void

戻り値

• 約束 <void>

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

setTitle()

Promise

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

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

パラメータ

• 詳細

  オブジェクト

  • tabId

    number（省略可）

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

  • title

    文字列

    マウスオーバーしたときにアクションに表示する文字列。

• callback

  関数（省略可）

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

  () => void

戻り値

• 約束 <void>

  Promise は Manifest V3 以降でサポートされていますが、 下位互換性が確保されます同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

イベント

onClicked

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

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

パラメータ

• callback

  関数

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

  (tab: tabs.Tab) => void

  • タブ

    tabs.Tab

onUserSettingsChanged

Chrome 130 以降

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

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

パラメータ

• callback

  関数

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

  (change: UserSettingsChange) => void

  • 変更

    UserSettingsChange