説明
chrome.alarms API を使用して、コードを定期的に実行するか、将来の指定した時間に実行するようにスケジュールします。
権限
alarmsbrowser.alarms API を使用するには、マニフェストで "alarms" 権限を宣言します。
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
コンセプトと使用方法
信頼性の高い動作を確保するには、API の動作を理解することが役立ちます。
デバイスのスリープ
デバイスがスリープ状態の間も、アラームは引き続き実行されます。ただし、アラームによってデバイスがスリープ解除されることはありません。デバイスが復帰すると、見逃したアラームが鳴ります。繰り返しアラームは、最大 1 回起動した後、デバイスが復帰した時点から指定された期間を使用して再スケジュールされます。アラームが最初に実行されるように設定されてから経過した時間は考慮されません。
永続性
アラームの永続性は、作成時に persistAcrossSessions フラグを使用して制御できます。この値は、true（拡張機能が更新されるまで保持）または false（拡張機能が再読み込みされた場合、ブラウザが再起動された場合、拡張機能が更新された場合にクリア）に設定できます。
その他のブラウザと Chrome の以前のバージョン
このプロパティは、他のブラウザ（問題）や Chrome 150 より前のバージョンの Chrome ではサポートされていません。これらのブラウザでは、動作が予測できない場合があります。そのため、サービス ワーカーが起動するたびに、重要なアラームが存在することを確認することをおすすめします。次に例を示します。
async function checkAlarmState() {
const alarm = await browser.alarms.get("my-alarm");
if (!alarm) {
await browser.alarms.create("my-alarm", { periodInMinutes: 1 });
}
}
checkAlarmState();
ユーザーのアクションに基づいてアラームが動的に作成される場合は、アラームが別の場所で作成されたことを保存して、必要に応じて再作成できるようにすることをおすすめします。
例
次の例は、アラームの使用方法と対応方法を示しています。この API を試すには、chrome-extension-samples リポジトリから Alarm API の例をインストールします。
アラームを設定する
次の例では、拡張機能の新しいバージョンがインストールされたときに、Service Worker でアラームを設定します。
service-worker.js:
browser.runtime.onInstalled.addListener(async ({ reason }) => {
// Create an alarm so we have something to look at in the demo
await browser.alarms.create('demo-default-alarm', {
delayInMinutes: 1,
periodInMinutes: 1,
persistAcrossSessions: true
});
});
アラームに対応する
次の例では、鳴ったアラームの名前に基づいてアクション ツールバー アイコンを設定しています。
service-worker.js:
browser.alarms.onAlarm.addListener((alarm) => {
browser.action.setIcon({
path: getIconPath(alarm.name),
});
});
型
Alarm
プロパティ
-
name
文字列
このアラームの名前。
-
periodInMinutes
number 省略可
null でない場合、アラームは繰り返しアラームであり、
periodInMinutes分後に再び作動します。 -
persistAcrossSessions
ブール値
Chrome 150 以降アラームをセッション（ブラウザの再起動）をまたいで維持するかどうか。
-
scheduledTime
数値
このアラームが起動するようにスケジュールされた時刻（エポックからのミリ秒単位、例:
Date.now() + n）。パフォーマンス上の理由により、アラームがこの時刻より遅れて起動する場合があります。
AlarmCreateInfo
プロパティ
-
delayInMinutes
number 省略可
onAlarmイベントを発生させるまでの時間（分単位）。 -
name
文字列 省略可
Chrome 152 以降このアラームの名前。
-
periodInMinutes
number 省略可
設定されている場合、onAlarm イベントは、
whenまたはdelayInMinutesで指定された最初のイベントの後、periodInMinutes分ごとに発生します。設定されていない場合、アラームは 1 回だけ鳴ります。 -
persistAcrossSessions
boolean 省略可
Chrome 150 以降アラームをセッション（ブラウザの再起動）をまたいで維持するかどうか。Chrome では、以前の動作に合わせてデフォルトで true に設定されていますが、ブラウザ間の互換性を最大化するには、これを明示的に設定する必要があります。
-
いつ
number 省略可
アラームを鳴らす時刻。エポックからの経過時間（ミリ秒単位）で指定します（例:
Date.now() + n）。
メソッド
clear()
chrome.alarms.clear(
name?: string,
): Promise<boolean>
指定された名前のアラームを消去します。
パラメータ
-
name
文字列 省略可
クリアするアラームの名前。デフォルトは空の文字列です。
戻り値
-
Promise<boolean>
Chrome 91 以降
clearAll()
chrome.alarms.clearAll(): Promise<boolean | undefined>
すべてのアラームを消去します。
戻り値
-
Promise<boolean | undefined>
Chrome 91 以降
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
): Promise<void>
アラームを作成します。alarmInfo で指定された時刻の近くで、onAlarm イベントが発生します。同じ名前のアラーム（名前が指定されていない場合は名前なし）が他にある場合、そのアラームはキャンセルされ、このアラームに置き換えられます。
ユーザーのマシンへの負荷を軽減するため、Chrome ではアラームを最大で 1 秒に 1 回に制限していますが、任意の時間だけ遅延させることもできます。つまり、delayInMinutes または periodInMinutes を 1 秒未満に設定すると、無視され、警告が表示されます。when は、警告なしで「現在」から 1 秒未満に設定できますが、実際には少なくとも 1 秒間はアラームが鳴りません。
パラメータ
-
name
文字列 省略可
このアラームを識別するための名前（省略可）。デフォルトは空の文字列です。
-
alarmInfo
アラームを鳴らすタイミングを記述します。初期時間は、
whenまたはdelayInMinutesのいずれかで指定する必要があります（両方は指定できません）。periodInMinutesが設定されている場合、アラームは最初のイベントの後、periodInMinutes分ごとに繰り返されます。繰り返しアラームにwhenとdelayInMinutesのどちらも設定されていない場合、periodInMinutesがdelayInMinutesのデフォルトとして使用されます。
戻り値
-
Promise<void>
Chrome 111 以降アラームが作成されると解決される Promise。
パラメータ
-
name
文字列 省略可
取得するアラームの名前。デフォルトは空の文字列です。
戻り値
-
Promise<Alarm | undefined>
Chrome 91 以降
戻り値
-
Promise<Alarm[]>
Chrome 91 以降