chrome.alarms

Chrome 120: Chrome 120 以降、アラームの最小間隔が 1 分から 30 秒に短縮されました。30 秒後にアラームをトリガーするには、periodInMinutes: 0.5 を設定します。
Chrome 117: Chrome 117 以降、アクティブなアラームの数は 500 個に制限されます。この上限に達すると、chrome.alarms.create() は失敗します。コールバックを使用する場合は、chrome.runtime.lastError が設定されます。Promise を使用すると、Promise は拒否されます。

説明

chrome.alarms API を使用して、定期的に、または将来の特定の時刻にコードを実行するようにスケジュールします。

権限

alarms

chrome.alarms API を使用するには、manifestで "alarms" 権限を宣言します。

{
  "name": "My extension",
  ...
  "permissions": [
    "alarms"
  ],
  ...
}

コンセプトと使用方法

信頼性の高い動作を確保するには、API の動作を理解することが役立ちます。

デバイスのスリープ

デバイスがスリープ状態のときも、アラームは動作し続けます。ただし、アラームによってデバイスがスリープ状態から復帰することはありません。デバイスが復帰すると、鳴らなかったアラームが鳴ります。アラームの繰り返しは最大 1 回発生し、その後はデバイスの起動時から指定された期間を使用してスケジュールが再設定されます。アラームが最初に実行されるように設定されてから経過した時間は考慮されません。

永続性

通常、アラームは拡張機能が更新されるまで保持されます。ただし、これは保証されているわけではなく、ブラウザの再起動時にアラートが消去される可能性があります。そのため、アラームの作成時にストレージに値を設定し、Service Worker の起動時にその値が存在することを確認することをおすすめします。次に例を示します。

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()

Promise

chrome.alarms.clear(
  name?: string,
  callback?: function,
)

指定された名前のアラームを消去します。

パラメータ

• name

  文字列（省略可）

  消去するアラームの名前。デフォルトは空の文字列です。

• callback

  function 省略可

  callback パラメータは次のようになります。

  (wasCleared: boolean) => void

  • wasCleared

    ブール値

戻り値

• Promise<boolean>

  Chrome 91 以降

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

clearAll()

Promise

chrome.alarms.clearAll(
  callback?: function,
)

すべてのアラームを消去します。

パラメータ

• callback

  function 省略可

  callback パラメータは次のようになります。

  (wasCleared: boolean) => void

  • wasCleared

    ブール値

戻り値

• Promise<boolean>

  Chrome 91 以降

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

create()

Promise

chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

アラームを作成します。alarmInfo で指定された時刻の近くで、onAlarm イベントが発生します。同じ名前の別のアラーム（名前が指定されていない場合は名前なし）が存在する場合、そのアラームはキャンセルされ、このアラームに置き換えられます。

ユーザーのマシンの負荷を軽減するため、Chrome ではアラームの発生を 30 秒間に 1 回までに制限していますが、任意の量だけ遅らせることもあります。つまり、delayInMinutes または periodInMinutes を 0.5 未満に設定しても、設定は適用されず、警告が発生します。when は警告なしで「現在」から 30 秒未満に設定できますが、実際には 30 秒以上経過しないとアラームがトリガーされません。

アプリや拡張機能を解凍して読み込むと、アプリや拡張機能のデバッグに役立つように、アラームの発生頻度に上限はありません。

パラメータ

• name

  文字列（省略可）

  このアラームを識別するための名前（省略可）。デフォルトは空の文字列です。

• alarmInfo

  AlarmCreateInfo

  アラームをいつ配信するかを指定します。開始時間は when または delayInMinutes のいずれかで指定する必要があります（両方は指定できません）。periodInMinutes が設定されている場合、アラームは最初のイベントから periodInMinutes 分ごとに繰り返します。繰り返しアラームに when も delayInMinutes も設定されていない場合、delayInMinutes のデフォルトとして periodInMinutes が使用されます。

• callback

  function 省略可

  Chrome 111 以降

  callback パラメータは次のようになります。

  () => void

戻り値

• Promise<void>

  Chrome 111 以降

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

get()

Promise

chrome.alarms.get(
  name?: string,
  callback?: function,
)

指定したアラームの詳細を取得します。

パラメータ

• name

  文字列（省略可）

  取得するアラームの名前。デフォルトは空の文字列です。

• callback

  function 省略可

  callback パラメータは次のようになります。

  (alarm?: Alarm) => void

  • アラーム

    アラーム 省略可

戻り値

• Promise<Alarm | undefined>

  Chrome 91 以降

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

getAll()

Promise

chrome.alarms.getAll(
  callback?: function,
)

すべてのアラームの配列を取得します。

パラメータ

• callback

  function 省略可

  callback パラメータは次のようになります。

  (alarms: Alarm[]) => void

  • アラーム

    アラーム[]

戻り値

• Promise<Alarm[]>

  Chrome 91 以降

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

イベント

onAlarm

chrome.alarms.onAlarm.addListener(
  callback: function,
)

アラームが経過したときに呼び出されます。イベントページに役立ちます。

パラメータ

• callback

  関数

  callback パラメータは次のようになります。

  (alarm: Alarm) => void

  • アラーム

    アラーム