説明
chrome.alarms
API を使用して、定期的に、または将来の指定された時刻にコードを実行するようにスケジュールします。
権限
alarms
マニフェスト
chrome.alarms
API を使用するには、マニフェストで "alarms"
権限を宣言します。
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
例
次の例は、アラームの使用方法と応答方法を示しています。この 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
string
このアラームの名前。
-
periodInMinutes
number(省略可)
null でない場合、アラームは繰り返しアラームとなり、
periodInMinutes
分後に再び作動します。 -
scheduledTime
数値
このアラームが発動するようスケジュール設定された時刻。エポックからのミリ秒数で指定します(例:
Date.now() + n
)。パフォーマンス上の理由から、アラームはこれより任意の時間だけ遅延している可能性があります。
AlarmCreateInfo
プロパティ
-
delayInMinutes
number(省略可)
onAlarm
イベントを発生させるまでの時間(分単位)。 -
periodInMinutes
number(省略可)
設定すると、
when
またはdelayInMinutes
で指定された最初のイベントからperiodInMinutes
分ごとに onAlarm イベントが発生します。設定しない場合、アラームは 1 回のみ発生します。 -
when
number(省略可)
アラームを発する時刻。エポックからのミリ秒数で指定します(例:
Date.now() + n
)。
メソッド
clear()
chrome.alarms.clear(
name?: string,
callback?: function,
)
指定した名前のアラームをクリアします。
パラメータ
-
name
string(省略可)
消去するアラームの名前。デフォルトは空の文字列です。
-
callback
関数(省略可)
callback
パラメータは次のようになります。(wasCleared: boolean) => void
-
wasCleared
boolean
-
戻り値
-
Promise<boolean>
Chrome 91 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
すべてのアラームをクリアします。
パラメータ
-
callback
関数(省略可)
callback
パラメータは次のようになります。(wasCleared: boolean) => void
-
wasCleared
boolean
-
戻り値
-
Promise<boolean>
Chrome 91 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
)
アラームを作成します。alarmInfo
で指定された時間付近で、onAlarm
イベントが発生します。同じ名前のアラーム(指定されていない場合は名前なし)が別のアラームにある場合、そのアラームはキャンセルされ、このアラームに置き換えられます。
ユーザーのパソコンの負荷を軽減するため、Chrome ではアラームを最大で 30 秒に 1 回に制限しますが、遅延は任意です。つまり、delayInMinutes
または periodInMinutes
を 0.5
未満に設定しても適用されず、警告が表示されます。when
では、「現在」から 30 秒未満(事前警告なし)に設定できますが、実際にはアラームを少なくとも 30 秒間は鳴らさないように設定できます。
アプリや拡張機能を解凍すると、デバッグに役立つように、アラームを発生する頻度に制限はありません。
パラメータ
-
name
string(省略可)
このアラームを識別する名前(省略可)。デフォルトは空の文字列です。
-
alarmInfo
アラームをいつ起動するかを記述します。初期時刻は
when
またはdelayInMinutes
のいずれかで指定する必要があります(両方は指定できません)。periodInMinutes
が設定されている場合、最初のアクティビティからperiodInMinutes
分ごとにアラームが鳴ります。繰り返しアラームにwhen
もdelayInMinutes
も設定されていない場合は、periodInMinutes
がdelayInMinutes
のデフォルトとして使用されます。 -
callback
関数(省略可)
Chrome 111 以降callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Chrome 111 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
指定したアラームの詳細を取得します。
パラメータ
戻り値
-
Promise<Alarm | undefined>
Chrome 91 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
getAll()
chrome.alarms.getAll(
callback?: function,
)
すべてのアラームの配列を取得します。
戻り値
-
Promise<アラーム[]>
Chrome 91 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。