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