chrome.alarms

説明

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

権限

alarms

chrome.alarms API を使用するには、マニフェストで "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（省略可）

    設定すると、when または delayInMinutes で指定された最初のイベントから periodInMinutes 分ごとに onAlarm イベントが発生します。設定しない場合、アラームは 1 回のみ発生します。

  • when

    number（省略可）

    アラームを発する時刻。エポックからのミリ秒数で指定します（例: Date.now() + n）。

Methods

clear()

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

指定した名前のアラームをクリアします。

パラメータ

  • name

    string（省略可）

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

  • callback

    関数（省略可）

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

    (wasCleared: boolean)=>void

    • wasCleared

      boolean

戻り値

  • Promise<boolean>

    Chrome 91 以降

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

clearAll()

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

すべてのアラームをクリアします。

パラメータ

  • callback

    関数（省略可）

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

    (wasCleared: boolean)=>void

    • wasCleared

      boolean

戻り値

  • 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

    string（省略可）

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

  • alarmInfo

    AlarmCreateInfo

    アラームをいつ起動するかを記述します。初期時刻は when または delayInMinutes のいずれかで指定する必要があります（両方は指定できません）。periodInMinutes が設定されている場合、最初のアクティビティから periodInMinutes 分ごとにアラームが鳴ります。繰り返しアラームに when も delayInMinutes も設定されていない場合は、periodInMinutes が delayInMinutes のデフォルトとして使用されます。

  • callback

    関数（省略可）

    Chrome 111 以降

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

    ()=>void

戻り値

  • Promise<void>

    Chrome 111 以降

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

get()

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

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

パラメータ

  • name

    string（省略可）

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

  • callback

    関数（省略可）

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

    (alarm?: Alarm)=>void

戻り値

  • Promise<アラーム|未定義>

    Chrome 91 以降

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

getAll()

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

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

パラメータ

  • callback

    関数（省略可）

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

    (alarms: Alarm[])=>void

戻り値

  • Promise<アラーム[]>

    Chrome 91 以降

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

イベント

onAlarm

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

アラームが終了すると呼び出されます。イベントページで役立ちます。

パラメータ

  • callback

    機能

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

    (alarm: Alarm)=>void