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

    数値（省略可）

    null でない場合、アラームは繰り返しアラームであり、periodInMinutes 分後に再び発生します。

  • scheduledTime

    数値

    このアラームの起動がスケジュール設定された時刻で、エポックからのミリ秒単位で表します（例: Date.now() + n）。パフォーマンス上の理由から、アラームはこれ以上の任意の時間遅延した可能性があります。

AlarmCreateInfo

プロパティ

  • delayInMinutes

    数値（省略可）

    onAlarm イベントを発生させる時間の長さ（分単位）。

  • periodInMinutes

    数値（省略可）

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

  • when

    数値（省略可）

    エポックからのミリ秒単位でアラームを起動する時刻（例: Date.now() + n）。

メソッド

clear()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.alarms.clear(
  name?: string,
  callback?: function,
)

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

パラメータ

  • name

    文字列（省略可）

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

  • callback

    関数（省略可）

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

    (wasCleared: boolean) => void

    • wasCleared

      ブール値

戻り値

  • Promise&lt;boolean&gt;

    Chrome 91 以降

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

clearAll()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.alarms.clearAll(
  callback?: function,
)

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

パラメータ

  • callback

    関数（省略可）

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

    (wasCleared: boolean) => void

    • wasCleared

      ブール値

戻り値

  • Promise&lt;boolean&gt;

    Chrome 91 以降

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

create()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

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

Chrome では、ユーザーのパソコンの負荷を軽減するため、アラームを最大で 30 秒に 1 回に制限しますが、それ以上遅らせる場合があります。つまり、delayInMinutes または periodInMinutes を 0.5 未満に設定しても無視され、警告が発生します。when は「now」から 30 秒未満に設定できます実際にはアラームが 30 秒以上鳴りません。

アプリや拡張機能のデバッグに役立つよう、パッケージ化されていない状態で読み込んだ場合、アラームを起動する頻度に制限はありません。

パラメータ

  • name

    文字列（省略可）

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

  • alarmInfo

    AlarmCreateInfo

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

  • callback

    関数（省略可）

    Chrome 111 以降

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

    () => void

戻り値

  • 約束 <void>

    Chrome 111 以降

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

get()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.alarms.get(
  name?: string,
  callback?: function,
)

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

パラメータ

  • name

    文字列（省略可）

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

  • callback

    関数（省略可）

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

    (alarm?: Alarm) => void

戻り値

  • Promise&lt;Alarm |未定義>

    Chrome 91 以降

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

getAll()

<ph type="x-smartling-placeholder"></ph> 約束 
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