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

アラームに応答する

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

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