説明
chrome.pageAction
API を使用すると、メインの Google Chrome ツールバー(アドレスバーの右側)にアイコンを配置できます。ページ操作は、現在のページで実行できる操作を表しますが、すべてのページに適用されるわけではありません。アクティブでないときは、ページ アクションがグレー表示になります。
可用性
たとえば次のような例が考えられます。
- このページの RSS フィードに登録
- このページの写真からスライドショーを作成できます
次のスクリーンショットの RSS アイコンは、現在のページの RSS フィードに登録できるページ アクションを表しています。
非表示のページ操作はグレー表示されます。たとえば、以下の RSS フィードはグレー表示されます。現在のページのフィードに登録できないためです。
代わりにブラウザ アクションを使用して、ユーザーが拡張機能を常に操作できるようにすることを検討してください。
マニフェスト
拡張機能のマニフェストにページ アクションを次のように登録します。
{
"name": "My extension",
...
"page_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
},
...
}
1.5x や 1.2x など、あまり一般的でないスケール係数を持つデバイスが一般的になりつつあるため、アイコンに複数のサイズを指定することをおすすめします。Chrome は最も近い値を選択し、16 ディップのスペースを埋めるように拡大縮小します。また、これにより、アイコンの表示サイズが変更された場合に、異なるアイコンを提供するために追加の作業を行う必要がなくなります。ただし、サイズの差が大きすぎると、このスケーリングによってアイコンの細部が失われたり、不鮮明になったりすることがあります。
デフォルト アイコンを登録するための古い構文も引き続きサポートされています。
{
"name": "My extension",
...
"page_action": {
...
"default_icon": "images/icon32.png" // optional
// equivalent to "default_icon": { "32": "images/icon32.png" }
},
...
}
UI の一部
ブラウザ アクションと同様に、ページ アクションにはアイコン、ツールチップ、ポップアップを表示できますが、バッジを含めることはできません。また、ページ アクションがグレー表示になることもあります。アイコン、ツールチップ、ポップアップの詳細については、ブラウザ アクション UI をご覧ください。
ページ アクションの表示とグレー表示にするには、それぞれ pageAction.show
メソッドと pageAction.hide
メソッドを使用します。デフォルトでは、ページ操作はグレー表示されます。表示するときは、アイコンを表示するタブを指定します。このアイコンは、タブを閉じるか、(ユーザーがリンクをクリックするなどして)別の URL の表示を開始するまで、表示されたままになります。
ヒント
視覚的な効果を最大限に高めるには、次のガイドラインに従ってください。
- 少数のページでしか意味をなさない機能については、ページ アクションを使用してください。
- ほとんどのページで意味のある機能にページ操作を使用しないでください。代わりにブラウザ アクションを使用してください。
- アイコンを常にアニメーション化しないでください。それはイライラするだけ。
型
ImageDataType
画像のピクセルデータ。ImageData オブジェクトである必要があります(canvas
要素など)。
タイプ
ImageData
TabDetails
プロパティ
-
tabId
number(省略可)
状態をクエリするタブの ID。タブが指定されていない場合は、タブに固有ではない状態が返されます。
メソッド
getPopup()
chrome.pageAction.getPopup(
details: TabDetails,
callback?: function,
)
このページ アクションのポップアップとして設定する HTML ドキュメントを取得します。
パラメータ
-
詳細
-
callback
関数(省略可)
callback
パラメータは次のようになります。(result: string) => void
-
件の結果
string
-
戻り値
-
Promise<文字列>
Chrome 101 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
getTitle()
chrome.pageAction.getTitle(
details: TabDetails,
callback?: function,
)
ページ アクションのタイトルを取得します。
パラメータ
-
詳細
-
callback
関数(省略可)
callback
パラメータは次のようになります。(result: string) => void
-
件の結果
string
-
戻り値
-
Promise<文字列>
Chrome 101 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
hide()
chrome.pageAction.hide(
tabId: number,
callback?: function,
)
ページ アクションを非表示にします。非表示にしたページの操作も Chrome ツールバーには表示されますが、グレー表示されます。
パラメータ
-
tabId
数値
ページ アクションを変更するタブの ID。
-
callback
関数(省略可)
Chrome 67 以降callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Chrome 101 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
setIcon()
chrome.pageAction.setIcon(
details: object,
callback?: function,
)
ページ アクションのアイコンを設定します。アイコンは、画像ファイルへのパス、キャンバス要素のピクセルデータ、またはこれらのいずれかの辞書として指定できます。path プロパティまたは imageData プロパティを指定する必要があります。
パラメータ
-
詳細
オブジェクト
-
iconIndex
number(省略可)
非推奨。この引数は無視されます。
-
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
数値
ページ アクションを変更するタブの ID。
-
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Chrome 101 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
setPopup()
chrome.pageAction.setPopup(
details: object,
callback?: function,
)
ユーザーがページ アクションのアイコンをクリックしたときにポップアップとして開く HTML ドキュメントを設定します。
パラメータ
-
詳細
オブジェクト
-
ポップアップ
string
ポップアップに表示する HTML ファイルの相対パス。空の文字列(
''
)に設定すると、ポップアップは表示されません。 -
tabId
数値
ページ アクションを変更するタブの ID。
-
-
callback
関数(省略可)
Chrome 67 以降callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Chrome 101 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
setTitle()
chrome.pageAction.setTitle(
details: object,
callback?: function,
)
ページ アクションのタイトルを設定します。これは、ページ操作の上にツールチップに表示されます。
パラメータ
-
詳細
オブジェクト
-
tabId
数値
ページ アクションを変更するタブの ID。
-
title
string
ツールチップの文字列。
-
-
callback
関数(省略可)
Chrome 67 以降callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Chrome 101 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
show()
chrome.pageAction.show(
tabId: number,
callback?: function,
)
ページの操作を表示します。ページ操作は、タブが選択されたときに表示されます。
パラメータ
-
tabId
数値
ページ アクションを変更するタブの ID。
-
callback
関数(省略可)
Chrome 67 以降callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Chrome 101 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。