PopupNotifications.jsm

PopupNotifications.jsm JavaScript コードモジュールはポップアップ通知ボックスサービスを提供します。このサービスを使うことにより、例えば、位置情報に関連する通知の表示といった機能を実現できます。

このサービスを使用するためには、最初に、あなたの JavaScript スコープへとコードモジュールをインポートする必要があります：

Components.utils.import("resource://gre/modules/PopupNotifications.jsm");

モジュールを一度インポートすれば、エクスポートされた PopupNotifications オブジェクトを使用できるようになります。このオブジェクトは、ポップアップ通知パネルの作成と表示のためのメソッドを提供します。

メソッド概要

プロパティ

メソッド

locationChange()

使用者 (consumer)は、ポップアップ通知モジュールに現在のブラウザのロケーションが変更されたことを知らせるために、このメソッドを呼び出します。これにより通知サービスは、必要に応じて、アクティブな通知を更新することができます。

void locationChange();

引数

無し。

getNotification()

指定した browser 要素および ID に関連づけられている Notification オブジェクトを取得します。

Notification getNotification(
 string id
 XULElement browser
);

引数

id

検索に使用する Notification ID。

browser

Notification オブジェクトを検索する XUL browser 要素。 null である場合、現在選択されている browser に関連づけられている Notification オブジェクトが検索されます。

返り値

与えられた引数に対応する Notification オブジェクト。対応する Notification オブジェクトが無い場合は null を返します。

remove()

指定された通知を削除します。

void remove(
  Notification notification
);

引数

notification

削除する通知を表す Notification オブジェクト。

show()

新しいポップアップ通知を追加し、ユーザーへと表示します。

Notification show(
  browser,
  id,
  message,
  anchorID,
  mainAction,
  secondaryActions,
  options
); 

引数

browser

通知を結びつける XUL browser 要素。この値は null であってはいけません。現在のタブへと通知を結びつける場合であれば、単純に gBrowser.selectedBrowser を指定する事が可能です。

id

表示される通知の種類を示すユニーク ID 文字列。例えば、位置情報に関連する通知の場合のIDは "geolocation" となります。同じ ID を持つ通知は、同時にひとつしか表示されません。指定した ID の通知が既に通知されていた場合、新しい通知によって古い通知は置き換えられることになります。

message

通知パネルに表示される文字列。

anchorID

通知ポップアップのアンカーを表示することとなる要素の ID。（つまり、ポップアップの矢印が指し示すであろう要素のことです）　null に指定した場合、通知は PopupNotification オブジェクトのアイコンボックスを表示元とします。この anchorID は、PopupNotification オブジェクトのアイコンボックスの内側に含まれる要素を指定しなければなりません。（Firefox ウィンドウであれば、グローバル PopupNotifications オブジェクトは notification-popup-box 要素を使用します）

mainAction

通知パネル中に描画されるボタンを定義するフィールドを含む JavaScript オブジェクトリテラル。詳しくは下記の Notification actions を参照してください。

secondaryActions

Notification action オブジェクトの配列。これらは通知パネルのボタンのドロップダウンメニューへ項目を追加するのに使われます。

options

通知のオプションとなるプロパティを含む JavaScript オブジェクト。詳しくは下記の Notification options を参照してください。

返り値

追加された通知に対応する Notification オブジェクトを返します。

Notification actions

Notification action オブジェクトは、通知に結び付いたアクションのためのユーザーインターフェースを記述します。main action は通知パネル中に表示されるボタンの挙動を記述するために使われます。一方、secondary actions はボタンからドロップダウン表示されるメニューの挙動を記述するのにつかわれます。

Notification action は以下のプロパティを含まなければなりません：

label

アクションを説明するラベルのテキスト。

accessKey

アクションを発動するキーストロークを示す文字列。

callback

ユーザーがアクションを選択した際に実行される JavaScript 関数。

Notification options

Notification options オブジェクトは通知パネルの更なるカスタマイズを指定できます。以下のプロパティをどのように組み合わせた場合でもカスタマイズは提供されます：

persistence

通知を存在させ続ける、ページのロード回数を示す整数値。一度に大量のページのロードが発生した場合、通知は自動的に消えるかもしれません。

timeout

少なくとも通知が自動的には消えない時間を指定するタイムスタンプ（UNIX エポックからの経過ミリ秒）。タイムアウト値を指定した通知は、ユーザーの操作によって非表示にならない限り、指定された時間までは自動的に消えることはありません。大抵の使用時において、このパラメータ値は Date.now() に、通知を表示し続ける時間量を示すオフセット値を加えます。（例：30秒とする場合は Date.now() + 30000 。）

persistWhileVisible

ロケーションの変更をまたいでも通知を表示させたままにするかどうかを指定する真偽値。true の場合、別のロケーションへと移動しても、通知は表示されたままになります。

dismissed

非表示通知 (dismissed notification) として通知を追加するかどうかを指定する真偽値。非表示通知 はアンカーのクリックによってアクティベートされます。この指定により、あなたが作成した通知は、ユーザーがアンカーをクリックした後に表示されます。

eventCallback

通知の状態が変更されたときに呼び出される JavaScript 関数。コールバック関数の最初の引数は、発生した状態の変更を示す文字列となります。詳しくは下記の Notification events を参照してください。

neverShow

真偽値。true に指定した場合、ポップアップが表示されるのを永続的に妨げます。通知としてアンカーアイコンのみを表示する目的に使用できます。

removeOnDismissal

通知が非表示である場合（すなわち、ユーザーの操作でポップアップが閉じられている場合はいつでも）、この設定を true にされている通知は削除されます。

popupIconURL

ポップアップに表示される画像の URL を指定する文字列。 これは通常、 CSS で list-style-image と .popup-notification-icon[popupid=...] セレクタ―を用いて指定されています。

Notification events

show() を呼び出す際に options パラメータを使用してイベントコールバックを指定した場合、通知の状態の変更に応じてコールバック関数が呼び出されます。コールバック関数の最初の引数は、状態の変更を示す以下の文字列のうちのいずれかひとつとなります：

"dismissed"

（クリックやタブ切り替えといった）ユーザーの操作によって通知が消えた場合。"removed" とは異なり、通知は再び表示することが可能です。

"removed"

通知上でのユーザーの操作、または新たなロケーションへブラウザが移動することによって通知が削除場合。

"shown"

通知が表示された場合。通知の非表示と再表示の度に発火します。

The Notification object

いずれの通知も Notification オブジェクトによって提供されます。このオブジェクトは通知の表示と管理に必要なすべてのデータを含み、1つのメソッドを持っています。anchorElement プロパティは通知のアンカー要素を返します。 remove()メソッドは通知を除去します。

関連項目

• Using popup notifications