説明
chrome.alarms API を使用すると、コードを定期的に実行したり、将来の指定した時間に実行したりするようにスケジュールできます。
権限
alarmschrome.alarms API を使用するには、"alarms" 権限を マニフェスト で宣言します。
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
コンセプトと使用方法
信頼性の高い動作を確保するには、API の動作を理解することが重要です。
デバイスのスリープ
デバイスがスリープ状態でもアラームは引き続き実行されます。ただし、アラームによってデバイスが起動することはありません。デバイスが起動すると、見逃したアラームがトリガーされます。 繰り返しアラームは最大で 1 回トリガーされ、デバイスが起動した時点から指定された間隔で再スケジュールされます。アラームが最初に実行されるように設定されてから経過した時間は考慮されません。
永続性
通常、アラームは拡張機能が更新されるまで保持されます。ただし、これは保証されておらず、ブラウザが再起動されるとアラームがクリアされることがあります。そのため、Service Worker が起動するたびにアラームが存在することを確認してください。次に例を示します。
async function checkAlarmState() {
const alarm = await chrome.alarms.get("my-alarm");
if (!alarm) {
await chrome.alarms.create("my-alarm", { periodInMinutes: 1 });
}
}
checkAlarmState();
例
次の例は、アラームの使用方法とアラームへの対応方法を示しています。この API を試すには、 Alarm API のサンプルを chrome-extension-samples リポジトリからインストールします。
アラームを設定する
次の例では、拡張機能がインストールされたときに 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
数値（省略可）
null でない場合、アラームは繰り返しアラームとなり、
periodInMinutes分後に再びトリガーされます。 -
persistAcrossSessions
ブール値
保留中アラームをセッション（ブラウザの再起動）をまたいで保持するかどうか。
-
scheduledTime
数値
このアラームがトリガーされるようにスケジュールされた時刻（エポックからの経過時間（ミリ秒単位））（例:
Date.now() + n）。パフォーマンス上の理由から、アラームがこの時刻より遅れることがあります。
AlarmCreateInfo
プロパティ
-
delayInMinutes
数値（省略可）
onAlarmイベントがトリガーされるまでの時間（分単位）。 -
periodInMinutes
数値（省略可）
設定すると、
whenまたはdelayInMinutesで指定された最初のイベントからperiodInMinutes分ごとに onAlarm イベントがトリガーされます。設定しない場合、アラームは 1 回だけトリガーされます。 -
persistAcrossSessions
ブール値（省略可）
保留中アラームをセッション（ブラウザの再起動）をまたいで保持するかどうか。Chrome では、過去の動作に合わせてデフォルトで true に設定されていますが、ブラウザ間の互換性を最大限に高めるために、明示的に設定することをおすすめします。
-
いつ
数値（省略可）
アラームがトリガーされる時刻（エポックからの経過時間（ミリ秒単位））（例:
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 以降アラームが作成されたときに解決される Promise。
パラメータ
-
name
文字列（省略可）
取得するアラームの名前。デフォルトは空の文字列です。
戻り値
-
Promise<Alarm | undefined>
Chrome 91 以降
戻り値
-
Promise<Alarm[]>
Chrome 91 以降