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의 예: 알람, i18n, ID, 런타임 대부분의 Chrome API와는 다릅니다.

선언적 이벤트 핸들러

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

예를 들어 선언적 이벤트 핸들러는 선언적 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'}]});

이벤트는 해당 이벤트에 의미 있는 특정 필터를 지원합니다. 이벤트가 실행되었을 때 지원 목록은 해당 이벤트에 대한 문서의 'filters' 섹션으로 이동합니다.

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

유형

Event

Chrome 이벤트에 대한 리스너를 추가하고 제거할 수 있게 해주는 객체입니다.

속성

  • addListeners

    void

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

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

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

    • 콜백

      H

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

  • addRules

    void

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

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

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

    • 규칙

      규칙<모든 항목>[]

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

    • 콜백

      함수 선택사항

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

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

      • 규칙

        규칙<모든 항목>[]

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

  • getRules

    void

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

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

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

    • ruleIdentifiers

      string[] 선택사항

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

    • 콜백

      함수

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

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

      • 규칙

        규칙<모든 항목>[]

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

  • hasListener

    void

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

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

    • 콜백

      H

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

    • returns

      부울

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

  • hasListeners

    void

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

    () => {...}

    • returns

      부울

      이벤트에 등록된 이벤트 리스너가 하나라도 있는 경우 true입니다.

  • removeListener

    void

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

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

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

    • 콜백

      H

      등록 취소되어야 하는 리스너입니다.

  • removeRules

    void

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

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

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

    • ruleIdentifiers

      string[] 선택사항

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

    • 콜백

      함수 선택사항

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

      () => void

Rule

이벤트 처리를 위한 선언적 규칙에 대한 설명입니다.

속성

  • 작업

    모두[]

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

  • conditions

    모두[]

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

  • id

    문자열(선택사항)

    이 규칙의 참조를 허용하는 식별자입니다(선택사항).

  • 우선순위

    숫자 선택사항

    이 규칙의 우선순위(선택사항)입니다. 기본값은 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

    (숫자 | 숫자[])[] 선택사항

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

  • queryContains

    문자열(선택사항)

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

  • queryEquals

    문자열(선택사항)

    URL의 쿼리 세그먼트가 지정된 문자열과 일치하는 경우 일치합니다.

  • queryPrefix

    문자열(선택사항)

    URL의 쿼리 세그먼트가 지정된 문자열로 시작하면 일치합니다.

  • querySuffix

    문자열(선택사항)

    URL의 쿼리 세그먼트가 지정된 문자열로 끝나면 일치합니다.

  • 스키마

    string[] 선택사항

    URL의 스키마가 배열에 지정된 스키마와 같으면 일치합니다.

  • urlContains

    문자열(선택사항)

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

  • urlEquals

    문자열(선택사항)

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

  • urlMatches

    문자열(선택사항)

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

  • urlPrefix

    문자열(선택사항)

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

  • urlSuffix

    문자열(선택사항)

    부분 식별자가 없는 URL이 지정된 문자열로 끝나면 일치합니다. 포트 번호는 기본 포트 번호와 일치하면 URL에서 제거됩니다.