chrome.declarativeContent

설명

chrome.declarativeContent API를 사용하면 페이지 콘텐츠를 읽을 수 있는 권한을 요청하지 않고 페이지의 콘텐츠에 따라 작업을 실행할 수 있습니다.

권한

declarativeContent

개념 및 사용법

핵심 용어: 확장 프로그램의 작업은 확장 프로그램의 툴바 아이콘을 제어합니다.

Declarative Content API를 사용하면 호스트 권한을 추가하거나 콘텐츠 스크립트를 삽입할 필요 없이 웹페이지의 URL 또는 CSS 선택자가 페이지의 요소와 일치하는지에 따라 확장 프로그램의 작업을 사용 설정할 수 있습니다.

사용자가 확장 프로그램의 작업을 클릭한 후 페이지와 상호작용하려면 activeTab 권한을 사용합니다.

규칙

규칙은 조건과 작업으로 구성됩니다. 조건 중 하나라도 충족되면 모든 작업이 실행됩니다. 작업은 setIcon() 및 showAction()입니다.

PageStateMatcher는 나열된 모든 기준이 충족되는 경우에만 웹페이지와 일치합니다. 페이지 URL, CSS 복합 선택기 또는 페이지의 북마크 상태와 일치할 수 있습니다. 다음 규칙은 비밀번호 필드가 있을 때 Google 페이지에서 확장 프로그램의 작업을 사용 설정합니다.

let rule1 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

성공: 모든 조건과 작업이 이전 예와 같이 생성자를 사용하여 생성됩니다.

동영상이 포함된 Google 사이트의 확장 프로그램 작업을 사용 설정하려면 각 조건이 지정된 모든 작업을 트리거하기에 충분하므로 두 번째 조건을 추가할 수 있습니다.

let rule2 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    }),
    new chrome.declarativeContent.PageStateMatcher({
      css: ["video"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

onPageChanged 이벤트는 처리된 조건이 하나 이상 있는 규칙이 있는지 테스트하고 작업을 실행합니다. 규칙은 탐색 세션 간에 유지됩니다. 따라서 확장 프로그램 설치 시간 동안 먼저 removeRules를 사용하여 이전에 설치된 규칙을 지운 다음 addRules를 사용하여 새 규칙을 등록해야 합니다.

chrome.runtime.onInstalled.addListener(function(details) {
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    chrome.declarativeContent.onPageChanged.addRules([rule2]);
  });
});

참고: 각 작업에서 내부 데이터 구조를 다시 생성하므로 항상 규칙을 일괄적으로 등록 또는 등록 취소해야 합니다. 이 재생성은 계산 비용이 많이 들지만 더 빠른 매칭 알고리즘이 용이합니다.

activeTab 권한이 있는 확장 프로그램은 권한 경고를 표시하지 않으며 사용자가 확장 프로그램 작업을 클릭할 때 관련 페이지에서만 실행됩니다.

페이지 URL 일치

PageStateMatcher.pageurl는 URL 기준이 충족되면 일치합니다. 가장 일반적인 기준은 호스트, 경로 또는 URL을 연결한 다음 포함, 같음, 접두사 또는 접미사입니다. 다음 표에는 몇 가지 예가 포함되어 있습니다.

기준	일치 동영상
{ hostSuffix: 'google.com' }	모든 Google URL
{ pathPrefix: '/docs/extensions' }	확장 프로그램 문서 URL
{ urlContains: 'developer.chrome.com' }	모든 Chrome 개발자 문서 URL

모든 기준은 대소문자를 구분합니다. 전체 기준 목록은 UrlFilter를 참조하세요.

CSS 일치

PageStateMatcher.css 조건은 복합 선택기여야 합니다. 즉, 선택기에 공백이나 '>'과 같은 조합자를 포함할 수 없습니다. 이렇게 하면 Chrome이 선택기를 더 효율적으로 일치시키는 데 도움이 됩니다.

복합 선택기 (양호)	복잡한 선택자 (허용되지 않음)
a	div p
iframe.special[src^='http']	p>span.highlight
ns|*	p + ol
#abcd:checked	p::first-line

CSS 조건은 표시된 요소에만 일치: 선택기와 일치하는 요소가 display:none이거나 상위 요소 중 하나가 display:none인 경우 조건이 일치하지 않습니다. visibility:hidden으로 스타일이 지정되거나, 화면 밖에 배치되거나, 다른 요소에 의해 숨겨진 요소는 여전히 조건과 일치하게 만들 수 있습니다.

북마크된 상태 일치

PageStateMatcher.isBookmarked 조건을 사용하면 사용자 프로필에서 현재 URL의 북마크된 상태를 일치시킬 수 있습니다. 이 조건을 사용하려면 확장 프로그램 매니페스트에서 '북마크' 권한을 선언해야 합니다.

유형

ImageDataType

https://developer.mozilla.org/en-US/docs/Web/API/ImageData를 참조하세요.

유형

ImageData

PageStateMatcher

다양한 기준에 따라 웹페이지의 상태를 일치시킵니다.

속성

• 생성자

  void

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

  (arg: PageStateMatcher)=> {...}

  • 인수

    PageStateMatcher

  • returns

    PageStateMatcher

• css

  string[] 선택사항

  배열의 모든 CSS 선택자가 페이지의 기본 프레임과 원점이 동일한 프레임에 표시된 요소와 일치하면 일치합니다. 매칭 속도를 높이려면 이 배열의 모든 선택기가 복합 선택기여야 합니다. 참고: 페이지당 수백 번 일치하는 CSS 선택자를 수백 개 나열하거나 CSS 선택자를 나열하면 웹사이트 속도가 느려질 수 있습니다.

• isBookmarked

  부울 선택사항

  Chrome 45 이상

  페이지의 북마크된 상태가 지정된 값과 동일한 경우 일치합니다. 북마크 권한이 필요합니다.

• pageUrl

  UrlFilter 선택사항

  페이지의 최상위 URL에 대해 UrlFilter의 조건이 충족되는 경우 일치합니다.

RequestContentScript

콘텐츠 스크립트를 삽입하는 선언적 이벤트 작업입니다.

경고: 이 작업은 아직 실험 단계에 있으며 Chrome의 안정화 버전 빌드에서는 지원되지 않습니다.

속성

• 생성자

  void

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

  (arg: RequestContentScript)=> {...}

  • 인수

    RequestContentScript

  • returns

    RequestContentScript

• allFrames

  부울 선택사항

  콘텐츠 스크립트가 일치하는 페이지의 모든 프레임에서 실행되는지, 아니면 상단 프레임에서만 실행되는지를 나타냅니다. 기본값은 false입니다.

• css

  string[] 선택사항

  콘텐츠 스크립트의 일부로 삽입할 CSS 파일의 이름입니다.

• js

  string[] 선택사항

  콘텐츠 스크립트의 일부로 삽입될 자바스크립트 파일의 이름입니다.

• matchAboutBlank

  부울 선택사항

  about:blank 및 about:srcdoc에 콘텐츠 스크립트를 삽입할지 여부입니다. 기본값은 false입니다.

SetIcon

해당 조건이 충족되는 동안 확장 프로그램의 페이지 작업 또는 브라우저 작업에 n-dip 정사각형 아이콘을 설정하는 선언적 이벤트 작업입니다. 이 작업은 호스트 권한 없이 사용할 수 있지만 확장 프로그램에 페이지 또는 브라우저 작업이 있어야 합니다.

imageData 또는 path 중 하나만 지정해야 합니다. 두 가지 모두 이미지 표현에 여러 픽셀을 매핑하는 사전입니다. imageData의 이미지 표현은 ImageData 객체입니다. 예를 들어 canvas 요소에서 가져오는 반면 path의 이미지 표현은 확장 프로그램의 매니페스트에 상대적인 이미지 파일의 경로입니다. scale개의 화면 픽셀이 기기 독립형 픽셀에 맞으면 scale * n 아이콘이 사용됩니다. 이 배율이 누락되면 다른 이미지의 크기가 필요한 크기로 조정됩니다.

속성

• 생성자

  void

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

  (arg: SetIcon)=> {...}

  • 인수

    SetIcon

  • returns

    SetIcon

• imageData

  ImageData|object 선택사항

  ImageData 객체 또는 설정할 아이콘을 나타내는 사전 {size -> ImageData}입니다. 아이콘이 사전으로 지정된 경우 사용되는 이미지는 화면의 픽셀 밀도에 따라 선택됩니다. 하나의 화면 공간 단위에 들어가는 이미지 픽셀의 수가 scale와 같으면 크기가 scale * n인 이미지가 선택됩니다. 여기서 n은 UI에 있는 아이콘의 크기입니다. 이미지를 하나 이상 지정해야 합니다. details.imageData = foo는 details.imageData = {'16': foo}와 동일합니다.

ShowAction

Chrome 97 이상

해당 조건이 충족되는 동안 확장 프로그램의 툴바 작업을 사용 설정된 상태로 설정하는 선언적 이벤트 작업입니다. 이 작업은 호스트 권한 없이 사용할 수 있습니다. 확장 프로그램에 activeTab 권한이 있는 경우 페이지 작업을 클릭하면 활성 탭에 액세스할 수 있는 권한이 부여됩니다.

조건이 충족되지 않는 페이지에서는 확장 프로그램의 툴바 작업이 회색조로 표시되며, 이를 클릭하면 작업이 트리거되는 대신 컨텍스트 메뉴가 열립니다.

속성

• 생성자

  void

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

  (arg: ShowAction)=> {...}

  • 인수

    ShowAction

  • returns

    ShowAction

ShowPageAction

Chrome 97부터 지원 중단됨

declarativeContent.ShowAction을(를) 사용하세요.

해당 조건이 충족되는 동안 확장 프로그램의 페이지 작업을 사용 설정된 상태로 설정하는 선언적 이벤트 작업입니다. 이 작업은 호스트 권한 없이 사용할 수 있지만 확장 프로그램에 페이지 작업이 있어야 합니다. 확장 프로그램에 activeTab 권한이 있는 경우 페이지 작업을 클릭하면 활성 탭에 액세스할 수 있는 권한이 부여됩니다.

조건이 충족되지 않는 페이지에서는 확장 프로그램의 툴바 작업이 회색조로 표시되며, 이를 클릭하면 작업이 트리거되는 대신 컨텍스트 메뉴가 열립니다.

속성

• 생성자

  void

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

  (arg: ShowPageAction)=> {...}

  • 인수

    ShowPageAction

  • returns

    ShowPageAction

이벤트

onPageChanged

addRules, removeRules, getRules로 구성된 선언적 이벤트 API를 제공합니다.

조건

PageStateMatcher

작업

RequestContentScript

SetIcon

ShowPageAction

ShowAction