chrome.declarativeContent

설명

chrome.declarativeContent API를 사용하여 페이지 콘텐츠를 읽을 권한이 없어도 페이지 콘텐츠에 따라 작업을 실행할 수 있습니다.

권한

declarativeContent

개념 및 사용

선언적 콘텐츠 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 일치

URL 기준이 충족되면 PageStateMatcher.pageurl가 일치합니다. 가장 일반적인 기준은 호스트, 경로 또는 URL을 연결한 후 Contains(포함), Equals(같음), Prefix(접두사) 또는 Suffix(접미사)를 사용하는 것입니다. 다음 표에는 몇 가지 예가 나와 있습니다.

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

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

CSS 일치

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

복합 선택기 (OK) 복잡한 선택기 (잘못됨)
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의 북마크 상태를 일치시킬 수 있습니다. 이 조건을 사용하려면 확장 프로그램 manifest에서 '북마크' 권한을 선언해야 합니다.

유형

유형

ImageData

PageStateMatcher

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

속성

  • 생성자

    void

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

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

  • css

    string[] 선택사항

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

  • isBookmarked

    불리언 선택사항

    Chrome 45 이상

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

  • pageUrl

    UrlFilter 선택사항

    페이지의 최상위 URL에 UrlFilter의 조건이 충족되면 일치합니다.

RequestContentScript

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

경고: 이 작업은 아직 실험용이며 안정적인 Chrome 빌드에서는 지원되지 않습니다.

속성

  • 생성자

    void

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

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

  • allFrames

    불리언 선택사항

    콘텐츠 스크립트가 일치하는 페이지의 모든 프레임에서 실행되는지 또는 상단 프레임에서만 실행되는지 여부입니다. 기본값은 false입니다.

  • css

    string[] 선택사항

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

  • js

    string[] 선택사항

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

  • matchAboutBlank

    불리언 선택사항

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

SetIcon

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

imageData 또는 path 중에서 정확히 하나만 지정해야 합니다. 둘 다 픽셀 수를 이미지 표현에 매핑하는 사전입니다. imageData의 이미지 표현은 ImageData 객체입니다(예: canvas 요소). 반면 path의 이미지 표현은 확장 프로그램의 매니페스트를 기준으로 한 이미지 파일의 경로입니다. scale 화면 픽셀이 기기 독립적 픽셀에 맞는 경우 scale * n 아이콘이 사용됩니다. 이 배율이 없으면 다른 이미지의 크기가 필요한 크기로 조정됩니다.

속성

  • 생성자

    void

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

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

  • imageData

    ImageData | 객체 선택사항

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

ShowAction

Chrome 97 이상

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

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

속성

ShowPageAction

Chrome 97부터 지원 중단됨

declarativeContent.ShowAction를 사용하세요.

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

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

속성

이벤트

onPageChanged

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

조건

PageStateMatcher

작업

RequestContentScript

SetIcon

ShowPageAction

ShowAction