설명
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 예를 설치하세요.
알람 설정해 줘
다음 예는 확장 프로그램이 설치될 때 서비스 워커에 알람을 설정합니다.
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
number 선택사항
null이 아닌 경우 알람은 반복 알람이며
periodInMinutes분 후에 다시 실행됩니다. -
scheduledTime
숫자
이 알람이 실행되도록 예약된 시간으로, 에포크 후 밀리초 단위로 표시됩니다 (예:
Date.now() + n). 성능상의 이유로 알람이 이 시간을 초과하는 임의의 시간만큼 지연되었을 수 있습니다.
AlarmCreateInfo
속성
-
delayInMinutes
number 선택사항
onAlarm이벤트가 실행되기까지 걸리는 시간(분)입니다. -
periodInMinutes
number 선택사항
설정되면
when또는delayInMinutes로 지정된 초기 이벤트 후periodInMinutes분마다 onAlarm 이벤트가 실행됩니다. 설정하지 않으면 알람은 한 번만 실행됩니다. -
when
number 선택사항
알람이 실행되어야 하는 시간으로, 에포크 이후 밀리초 단위로 표시됩니다 (예:
Date.now() + n).
방법
clear()
chrome.alarms.clear(
name?: string,
callback?: function,
)
지정된 이름의 알람을 지웁니다.
매개변수
-
이름
문자열 선택사항
지울 알람의 이름입니다. 기본값은 빈 문자열입니다.
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.(wasCleared: boolean)=>void
-
wasCleared
boolean
-
반환 값
-
Promise<boolean>
Chrome 91 이상프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
clearAll()
chrome.alarms.clearAll(
callback?: function,
)
모든 알람을 지웁니다.
매개변수
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.(wasCleared: boolean)=>void
-
wasCleared
boolean
-
반환 값
-
Promise<boolean>
Chrome 91 이상프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
create()
chrome.alarms.create(
name?: string,
alarmInfo: AlarmCreateInfo,
callback?: function,
)
알람을 생성합니다. alarmInfo로 지정된 시간이 다가오면 onAlarm 이벤트가 실행됩니다. 같은 이름의 다른 알람이 있는 경우 (또는 이름을 지정하지 않은 경우 이름이 지정되지 않은 경우) 취소되고 이 알람으로 대체됩니다.
사용자 컴퓨터의 부하를 줄이기 위해 Chrome은 알람이 30초마다 최대 한 번으로 제한되지만 임의의 시간만큼 알람이 지연될 수 있습니다. 즉, delayInMinutes 또는 periodInMinutes를 0.5보다 작게 설정하면 적용되지 않으며 경고가 발생합니다. when은(는) 경고 없이 '지금' 이후 30초 미만으로 설정될 수 있지만, 실제로 알람이 최소 30초 동안 실행되지는 않습니다.
앱 또는 확장 프로그램을 디버그하는 데 도움이 되도록 압축해제하여 로드한 후에는 알람이 실행되는 빈도에 제한이 없습니다.
매개변수
-
이름
문자열 선택사항
이 알람을 식별하기 위한 이름입니다(선택사항). 기본값은 빈 문자열입니다.
-
alarmInfo
알람이 실행되어야 하는 시기를 설명합니다. 초기 시간은
when또는delayInMinutes로 지정해야 합니다 (둘 다 지정할 수는 없음).periodInMinutes이(가) 설정되면 첫 이벤트 후periodInMinutes분마다 알람이 반복됩니다.when또는delayInMinutes중 어느 것도 반복 알람에 설정되어 있지 않으면periodInMinutes이delayInMinutes의 기본값으로 사용됩니다. -
콜백
함수 선택사항
Chrome 111 이상callback매개변수는 다음과 같습니다.()=>void
반환 값
-
Promise<void>
Chrome 111 이상프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
get()
chrome.alarms.get(
name?: string,
callback?: function,
)
지정된 알람에 대한 세부정보를 검색합니다.
매개변수
반환 값
-
프로미스<알람|undefined>
Chrome 91 이상프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
getAll()
chrome.alarms.getAll(
callback?: function,
)
모든 알람의 배열을 가져옵니다.
반환 값
-
프로미스<알람[]>
Chrome 91 이상프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.