chrome.alarms

説明

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
  });
});

注: Chrome 117 以降、有効なアラームの数が 500 に制限されます。この上限に達すると、chrome.alarms.create() は失敗します。コールバックを使用する場合、chrome.runtime.lastError が設定されます。Promise を使用する場合、Promise は拒否されます。

アラームに応答する

次の例では、鳴ったアラームの名前に基づいてアクション ツールバー アイコンを設定しています。

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 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

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 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

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 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

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 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

getAll()

<ph type="x-smartling-placeholder"></ph> 約束

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

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

パラメータ

• callback

  関数（省略可）

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

  (alarms: Alarm[]) => void

  • アラーム

    アラーム[]

戻り値

• Promise<アラーム[]>

  Chrome 91 以降

  Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

イベント

onAlarm

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

アラームの時間が経過したときに発生します。イベントページで役立ちます。

パラメータ

• callback

  関数

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

  (alarm: Alarm) => void

  • アラーム

    アラーム