browser.events

설명

개념 및 사용

Event는 흥미로운 일이 발생할 때 알림을 받을 수 있는 객체입니다. 다음은 알람이 경과할 때마다 알림을 받기 위해 browser.alarms.onAlarm 이벤트를 사용하는 예입니다.

browser.alarms.onAlarm.addListener((alarm) => {
  appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});

예시와 같이 addListener()를 사용하여 알림을 등록합니다. addListener()의 인수는 항상 이벤트를 처리하기 위해 정의하는 함수이지만 함수의 매개변수는 처리하는 이벤트에 따라 다릅니다. alarms.onAlarm 문서를 확인하면 이 함수에 단일 매개변수가 있습니다. 경과된 알람에 관한 세부정보가 있는 alarms.Alarm 객체입니다.

이벤트를 사용하는 API의 예: alarms, i18n, identity, runtime 대부분의 Chrome API는 그렇습니다.

선언적 이벤트 핸들러

선언적 이벤트 핸들러는 선언적 조건과 작업으로 구성된 규칙을 정의하는 수단을 제공합니다. 조건은 JavaScript 엔진이 아닌 브라우저에서 평가되므로 왕복 지연 시간이 줄어들고 매우 높은 효율성을 달성할 수 있습니다.

선언적 이벤트 핸들러는 선언적 Content API에서 사용됩니다. 이 페이지에서는 모든 선언적 이벤트 핸들러의 기본 개념을 설명합니다.

규칙

가장 간단한 규칙은 하나 이상의 조건과 하나 이상의 작업으로 구성됩니다.

const rule = {
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

조건 중 하나라도 충족되면 모든 작업이 실행됩니다.

조건 및 작업 외에도 각 규칙에 식별자를 부여하여 이전에 등록된 규칙의 등록을 간소화하고 규칙 간의 우선순위를 정의할 수 있습니다. 우선순위는 규칙이 서로 충돌하거나 특정 순서로 실행해야 하는 경우에만 고려됩니다. 작업은 규칙의 우선순위 내림차순으로 실행됩니다.

const rule = {
  id: "my rule",  // optional, will be generated if not set.
  priority: 100,  // optional, defaults to 100.
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

이벤트 객체

이벤트 객체는 규칙을 지원할 수 있습니다. 이러한 이벤트 객체는 이벤트가 발생할 때 콜백 함수를 호출하지 않지만 등록된 규칙에 충족된 조건이 하나 이상 있는지 테스트하고 이 규칙과 연결된 작업을 실행합니다. 선언적 API를 지원하는 이벤트 객체에는 events.Event.addRules(), events.Event.removeRules(), events.Event.getRules()의 세 가지 관련 메서드가 있습니다.

규칙 추가

규칙을 추가하려면 이벤트 객체의 addRules() 함수를 호출합니다. 규칙 인스턴스 배열을 첫 번째 매개변수로 사용하고 완료 시 호출되는 콜백 함수를 사용합니다.

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});

규칙이 성공적으로 삽입된 경우 details 매개변수에는 전달된 rule_list과 동일한 순서로 표시되는 삽입된 규칙의 배열이 포함되며, 여기서 선택적 매개변수 id 및 priority는 생성된 값으로 채워집니다. 무효한 조건이나 작업을 포함하는 등 규칙이 무효한 경우 규칙이 추가되지 않으며 콜백 함수가 호출될 때 runtime.lastError 변수가 설정됩니다. rule_list의 각 규칙에는 다른 규칙에서 이미 사용 중이거나 비어 있지 않은 고유 식별자가 포함되어야 합니다.

규칙 삭제

규칙을 삭제하려면 removeRules() 함수를 호출합니다. 규칙 식별자의 선택적 배열을 첫 번째 매개변수로, 콜백 함수를 두 번째 매개변수로 허용합니다.

const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});

rule_ids가 식별자 배열인 경우 배열에 나열된 식별자가 있는 모든 규칙이 삭제됩니다. rule_ids에 알 수 없는 식별자가 나열되면 이 식별자는 자동으로 무시됩니다. rule_ids가 undefined이면 이 확장 프로그램의 등록된 모든 규칙이 삭제됩니다. 규칙이 삭제되면 callback() 함수가 호출됩니다.

규칙 가져오기

등록된 규칙 목록을 가져오려면 getRules() 함수를 호출합니다. removeRules()와 동일한 시맨틱스의 규칙 식별자 배열(선택 사항)과 콜백 함수를 허용합니다.

const rule_ids = ["id1", "id2", ...];
getRules(rule_ids, (details) => {...});

callback() 함수에 전달된 details 매개변수는 채워진 선택적 매개변수를 포함한 규칙 배열을 나타냅니다.

성능

최대 성능을 달성하려면 다음 가이드라인을 참고하세요.

규칙을 일괄 등록 및 등록 취소합니다. 등록 또는 등록 해제 후 Chrome은 내부 데이터 구조를 업데이트해야 합니다. 이 업데이트는 비용이 많이 드는 작업입니다.

const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1]);
browser.declarativeWebRequest.onRequest.addRules([rule2]);

const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

events.UrlFilter에서 정규 표현식보다 하위 문자열 일치를 선호합니다. 부분 문자열 기반 일치는 매우 빠릅니다.

const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});

const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {hostSuffix: "example.com", pathContains: "foo"}
});

동일한 작업을 공유하는 규칙이 많은 경우 규칙을 하나로 병합합니다. 규칙은 단일 조건이 충족되는 즉시 작업을 트리거합니다. 이렇게 하면 중복 작업 세트의 일치 속도가 빨라지고 메모리 소비가 줄어듭니다.

const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule1 = { conditions: [condition1],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
const rule2 = { conditions: [condition2],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule = { conditions: [condition1, condition2],
              actions: [new browser.declarativeWebRequest.CancelRequest()]
             };
browser.declarativeWebRequest.onRequest.addRules([rule]);

필터링된 이벤트

필터링된 이벤트는 리스너가 관심 있는 이벤트의 하위 집합을 지정할 수 있는 메커니즘입니다. 필터를 사용하는 리스너는 필터를 통과하지 않는 이벤트에 대해 호출되지 않으므로 리스닝 코드가 더 선언적이고 효율적입니다. 서비스 워커는 관심이 없는 이벤트를 처리하기 위해 깨어날 필요가 없습니다.

필터링된 이벤트는 수동 필터링 코드에서 전환할 수 있도록 하기 위한 것입니다.

browser.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});

browser.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

이벤트는 해당 이벤트에 의미가 있는 특정 필터를 지원합니다. 이벤트에서 지원하는 필터 목록은 '필터' 섹션의 해당 이벤트에 관한 문서에 나열됩니다.

위의 예와 같이 URL을 일치시킬 때 이벤트 필터는 스키마 및 포트 일치를 제외하고 events.UrlFilter로 표현할 수 있는 것과 동일한 URL 일치 기능을 지원합니다.