설명
chrome.alarms API를 사용하여 주기적으로 또는 지정된 미래 시간에 실행되도록 코드를 예약합니다.
권한
alarmschrome.alarms API를 사용하려면 매니페스트에서 "alarms" 권한을 선언하세요.
{
"name": "My extension",
...
"permissions": [
"alarms"
],
...
}
개념 및 사용
안정적인 동작을 보장하려면 API의 동작을 이해하는 것이 좋습니다.
기기 절전 모드
기기가 절전 모드일 때도 알람은 계속 실행됩니다. 하지만 알람은 기기의 절전 모드를 해제하지 않습니다. 기기가 절전 모드에서 해제되면 놓친 알람이 실행됩니다. 반복 알람은 최대 한 번 실행된 후 알람이 원래 실행되도록 설정된 이후 이미 경과한 시간을 고려하지 않고 기기가 절전 모드에서 해제된 시점부터 시작되는 지정된 기간을 사용하여 다시 예약됩니다.
지속성
알람은 일반적으로 확장 프로그램이 업데이트될 때까지 지속됩니다. 하지만 이는 보장되지 않으며 브라우저가 다시 시작되면 알람이 삭제될 수 있습니다. 따라서 알람이 생성될 때 저장소에 값을 설정한 다음 서비스 워커가 시작될 때마다 값이 있는지 확인하는 것이 좋습니다. 예를 들면 다음과 같습니다.
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 example을 설치하세요.
알람 설정해 줘
다음 예에서는 확장 프로그램이 설치될 때 서비스 워커에서 알람을 설정합니다.
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
속성
-
이름
문자열
이 알람의 이름입니다.
-
periodInMinutes
번호 선택사항
null이 아니면 알람이 반복 알람이며
periodInMinutes분 후에 다시 울립니다. -
scheduledTime
숫자
이 알람이 트리거되도록 예약된 시간입니다 (단위: 밀리초, 에포크 이후 경과 시간, 예:
Date.now() + n). 성능상의 이유로 알람이 이 시간을 지나 임의의 시간만큼 지연되었을 수 있습니다.
AlarmCreateInfo
속성
-
delayInMinutes
번호 선택사항
onAlarm이벤트가 발생해야 하는 시간(분)입니다. -
periodInMinutes
번호 선택사항
설정된 경우 onAlarm 이벤트는
when또는delayInMinutes로 지정된 초기 이벤트 후periodInMinutes분마다 발생해야 합니다. 설정하지 않으면 알람이 한 번만 울립니다. -
언제
번호 선택사항
알람이 울려야 하는 시간입니다 (에포크 이후 경과된 밀리초, 예:
Date.now() + n).
메서드
clear()
chrome.alarms.clear(
name?: string,
): Promise<boolean>
지정된 이름의 알람을 삭제합니다.
매개변수
-
이름
문자열 선택사항
삭제할 알람의 이름입니다. 기본값은 빈 문자열입니다.
반환 값
-
Promise<boolean>
Chrome 91 이상
clearAll()
chrome.alarms.clearAll(): Promise<boolean>
모든 알람을 삭제합니다.
반환 값
-
Promise<boolean>
Chrome 91 이상
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
): Promise<void>
알람을 만듭니다. alarmInfo로 지정된 시간에 가까워지면 onAlarm 이벤트가 실행됩니다. 이름이 같은 다른 알람이 있거나 이름이 지정되지 않은 경우 취소되고 이 알람으로 대체됩니다.
사용자 컴퓨터의 부하를 줄이기 위해 Chrome은 알람을 최대 30초에 한 번으로 제한하지만 임의의 시간만큼 더 지연시킬 수 있습니다. 즉, delayInMinutes 또는 periodInMinutes을 0.5보다 작은 값으로 설정하면 적용되지 않으며 경고가 표시됩니다. when는 경고 없이 '지금'으로부터 30초 미만으로 설정할 수 있지만 실제로 알람이 최소 30초 동안 울리지는 않습니다.
앱이나 확장 프로그램을 압축 해제된 상태로 로드한 경우 앱이나 확장 프로그램을 디버그할 수 있도록 알람이 실행되는 횟수에는 제한이 없습니다.
매개변수
-
이름
문자열 선택사항
이 알람을 식별하는 선택적 이름입니다. 기본값은 빈 문자열입니다.
-
alarmInfo
알람이 울려야 하는 시간을 설명합니다. 초기 시간은
when또는delayInMinutes중 하나로 지정해야 합니다 (둘 다는 안 됨).periodInMinutes이 설정되면 알람이 초기 이벤트 후periodInMinutes분마다 반복됩니다. 반복 알람에when또는delayInMinutes이 설정되지 않은 경우periodInMinutes이delayInMinutes의 기본값으로 사용됩니다.
반환 값
-
Promise<void>
Chrome 111 이상
매개변수
-
이름
문자열 선택사항
가져올 알람의 이름입니다. 기본값은 빈 문자열입니다.
반환 값
-
Promise<Alarm | undefined>
Chrome 91 이상
반환 값
-
Promise<Alarm[]>
Chrome 91 이상