chrome.events

설명

chrome.events 네임스페이스에는 API에서 이벤트를 전달하여 흥미로운 상황이 발생할 때 사용자에게 알리는 데 사용되는 공통 유형이 포함되어 있습니다.

개념 및 사용법

Event는 흥미로운 상황이 발생할 때 알림을 받을 수 있는 객체입니다. 다음은 알람이 경과할 때마다 알림을 받도록 chrome.alarms.onAlarm 이벤트를 사용하는 예입니다.

chrome.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는 지원합니다.

선언적 이벤트 핸들러

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

선언적 이벤트 핸들러는 예를 들어 Declarative 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 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1]);
chrome.declarativeWebRequest.onRequest.addRules([rule2]);
설정
const rule1 = {...};
const rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

events.UrlFilter에서 정규 표현식보다 하위 문자열 일치를 사용하는 것이 좋습니다. 하위 문자열 기반 일치는 매우 빠릅니다.

대신
const match = new chrome.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});
설정
const match = new chrome.declarativeWebRequest.RequestMatcher({
  url: {hostSuffix: "example.com", pathContains: "foo"}
});

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

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

필터링된 이벤트

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

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

대신
chrome.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});
설정
chrome.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

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

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

유형

Event

Chrome 이벤트에 대한 리스너를 추가 및 삭제할 수 있는 객체입니다.

속성

  • addListener

    void

    이벤트 리스너 콜백을 이벤트에 등록합니다.

    addListener 함수는 다음과 같습니다. 

    (callback: H)=> {...}

    • 콜백

      H

      이벤트가 발생할 때 호출됩니다. 이 함수의 매개변수는 이벤트 유형에 따라 다릅니다.

  • addRules

    void

    이벤트를 처리할 규칙을 등록합니다.

    addRules 함수는 다음과 같습니다. 

    (rules: Rule<anyany>[],callback?: function)=> {...}

    • 규칙

      규칙<any>[]

      등록할 규칙입니다. 이전에 등록된 규칙을 대체하지 않습니다.

    • 콜백

      함수 선택사항

      callback 매개변수는 다음과 같습니다. 

      (rules: Rule<anyany>[])=>void

      • 규칙

        규칙<any>[]

        등록된 규칙이며 선택적 매개변수가 값으로 채워집니다.

  • getRules

    void

    현재 등록된 규칙을 반환합니다.

    getRules 함수는 다음과 같습니다. 

    (ruleIdentifiers?: string[],callback: function)=> {...}

    • ruleIdentifiers

      string[] 선택사항

      배열이 전달되면 이 배열에 포함된 식별자가 있는 규칙만 반환됩니다.

    • 콜백

      기능

      callback 매개변수는 다음과 같습니다. 

      (rules: Rule<anyany>[])=>void

      • 규칙

        규칙<any>[]

        등록된 규칙이며 선택적 매개변수가 값으로 채워집니다.

  • hasListener

    void

    hasListener 함수는 다음과 같습니다. 

    (callback: H)=> {...}

    • 콜백

      H

      등록 상태를 테스트할 리스너입니다.

    • returns

      boolean

      콜백이 이벤트에 등록된 경우 true입니다.

  • hasListeners

    void

    hasListeners 함수는 다음과 같습니다. 

    ()=> {...}

    • returns

      boolean

      이벤트 리스너가 이벤트에 등록된 경우 true입니다.

  • removeListener

    void

    이벤트에서 이벤트 리스너 콜백을 등록 취소합니다.

    removeListener 함수는 다음과 같습니다. 

    (callback: H)=> {...}

    • 콜백

      H

      등록 취소될 리스너입니다.

  • removeRules

    void

    현재 등록된 규칙을 등록 취소합니다.

    removeRules 함수는 다음과 같습니다. 

    (ruleIdentifiers?: string[],callback?: function)=> {...}

    • ruleIdentifiers

      string[] 선택사항

      배열이 전달되면 이 배열에 포함된 식별자가 있는 규칙만 등록 취소됩니다.

    • 콜백

      함수 선택사항

      callback 매개변수는 다음과 같습니다. 

      ()=>void

Rule

이벤트 처리를 위한 선언적 규칙의 설명

속성

  • 작업

    모든[]

    조건 중 하나가 충족되면 트리거되는 작업 목록입니다.

  • conditions

    모든[]

    작업을 트리거할 수 있는 조건 목록입니다.

  • id

    문자열 선택사항

    이 규칙 참조를 허용하는 선택적 식별자입니다.

  • 우선순위

    number 선택사항

    이 규칙의 우선순위입니다(선택사항). 기본값은 100입니다.

  • tags

    string[] 선택사항

    태그를 사용하면 규칙에 주석을 달고 규칙 집합에 대한 작업을 수행할 수 있습니다.

UrlFilter

다양한 기준에 따라 URL을 필터링합니다. 이벤트 필터링을 참고하세요. 모든 기준은 대소문자를 구분합니다.

속성

  • cidrBlocks

    string[] 선택사항

    Chrome 123 이상

    URL의 호스트 부분이 IP 주소이고 배열에 지정된 CIDR 블록에 포함된 경우 일치합니다.

  • hostContains

    문자열 선택사항

    URL의 호스트 이름에 지정된 문자열이 포함되어 있으면 일치합니다. 호스트 이름 구성요소에 'foo' 프리픽스가 있는지 테스트하려면 hostContains: '.foo'를 사용합니다. 이는 'www.foobar.com' 및 'foo.com'과 일치합니다. 호스트 이름의 시작 부분에 암시적 점이 추가되기 때문입니다. 마찬가지로 hostContains를 사용하여 구성요소 접미사 ('foo.')와 일치시키고 구성요소 ('.foo.')와 정확하게 일치시킬 수 있습니다. 마지막 구성요소의 접미사 및 완전 일치는 hostSuffix를 사용하여 별도로 실행되어야 합니다. 호스트 이름의 끝에 암시적 점이 추가되지 않기 때문입니다.

  • hostEquals

    문자열 선택사항

    URL의 호스트 이름이 지정된 문자열과 같은 경우 일치합니다.

  • hostPrefix

    문자열 선택사항

    URL의 호스트 이름이 지정된 문자열로 시작하는 경우 일치합니다.

  • hostSuffix

    문자열 선택사항

    URL의 호스트 이름이 지정된 문자열로 끝나는 경우 일치합니다.

  • originAndPathMatches

    문자열 선택사항

    검색어 세그먼트와 부분 식별자가 없는 URL이 지정된 정규 표현식과 일치하면 일치합니다. 포트 번호는 기본 포트 번호와 일치하는 경우 URL에서 제거됩니다. 정규 표현식은 RE2 구문을 사용합니다.

  • pathContains

    문자열 선택사항

    URL의 경로 세그먼트에 지정된 문자열이 포함되어 있으면 일치합니다.

  • pathEquals

    문자열 선택사항

    URL의 경로 세그먼트가 지정된 문자열과 동일한 경우 일치합니다.

  • pathPrefix

    문자열 선택사항

    URL의 경로 세그먼트가 지정된 문자열로 시작하는 경우 일치합니다.

  • pathSuffix

    문자열 선택사항

    URL의 경로 세그먼트가 지정된 문자열로 끝나는 경우 일치합니다.

  • ports

    (number|number[])[] 선택사항

    URL의 포트가 지정된 포트 목록에 포함되어 있으면 일치합니다. 예를 들어 [80, 443, [1000, 1200]]는 포트 80, 443 및 1000~1200 범위에 있는 모든 요청과 일치합니다.

  • queryContains

    문자열 선택사항

    URL의 검색어 세그먼트에 지정된 문자열이 포함되어 있으면 일치합니다.

  • queryEquals

    문자열 선택사항

    URL의 검색어 세그먼트가 지정된 문자열과 동일한 경우 일치합니다.

  • queryPrefix

    문자열 선택사항

    URL의 검색어 세그먼트가 지정된 문자열로 시작하는 경우 일치합니다.

  • querySuffix

    문자열 선택사항

    URL의 검색어 세그먼트가 지정된 문자열로 끝나는 경우 일치합니다.

  • schemes

    string[] 선택사항

    URL의 스키마가 배열에 지정된 스키마와 동일한 경우 일치합니다.

  • urlContains

    문자열 선택사항

    부분 식별자가 없는 URL에 지정된 문자열이 포함되어 있으면 일치합니다. 포트 번호는 기본 포트 번호와 일치하는 경우 URL에서 제거됩니다.

  • urlEquals

    문자열 선택사항

    부분 식별자가 없는 URL이 지정된 문자열과 동일한 경우 일치합니다. 포트 번호는 기본 포트 번호와 일치하는 경우 URL에서 제거됩니다.

  • urlMatches

    문자열 선택사항

    프래그먼트 식별자가 없는 URL이 지정된 정규 표현식과 일치하면 매칭합니다. 포트 번호는 기본 포트 번호와 일치하는 경우 URL에서 제거됩니다. 정규 표현식은 RE2 구문을 사용합니다.

  • urlPrefix

    문자열 선택사항

    프래그먼트 식별자가 없는 URL이 지정된 문자열로 시작하는 경우 일치합니다. 포트 번호는 기본 포트 번호와 일치하는 경우 URL에서 제거됩니다.

  • urlSuffix

    문자열 선택사항

    프래그먼트 식별자 없이 URL이 지정된 문자열로 끝나는 경우 일치합니다. 포트 번호는 기본 포트 번호와 일치하는 경우 URL에서 제거됩니다.