chrome.scripting

설명

chrome.scripting API를 사용하여 다른 컨텍스트에서 스크립트를 실행합니다.

권한

scripting

가용성

Chrome 88 이상 MV3 이상

매니페스트

chrome.scripting API를 사용하려면 매니페스트에서 "scripting" 권한과 스크립트를 삽입할 페이지의 호스트 권한을 선언합니다. "host_permissions" 키 또는 "activeTab" 권한을 사용하여 임시 호스트 권한을 부여합니다. 다음 예에서는 activeTab 권한을 사용합니다.

{
  "name": "Scripting Extension",
  "manifest_version": 3,
  "permissions": ["scripting", "activeTab"],
  ...
}

개념 및 사용법

chrome.scripting API를 사용하여 JavaScript와 CSS를 있습니다. 이는 콘텐츠 네트워크에서 콘텐츠 사용과 스크립트와 동일합니다. 하지만 chrome.scripting 네임스페이스를 사용하면 확장자가 결정을 내릴 수 있습니다

삽입 대상

target 매개변수를 사용하여 JavaScript를 삽입할 타겟을 지정하거나 CSS에 삽입해야 합니다.

유일한 필수 필드는 tabId입니다. 기본적으로 삽입은 메인 프레임입니다.

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected"));

지정된 탭의 모든 프레임에서 실행하려면 allFrames 부울을 설정하면 됩니다. true에게 전송합니다.

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected in all frames"));

개별 프레임을 지정하여 탭의 특정 프레임에 삽입할 수도 있습니다. 있습니다. 프레임 ID에 관한 자세한 내용은 chrome.webNavigation API를 참조하세요.

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected on target frames"));

삽입된 코드

확장 프로그램은 외부 파일 또는 런타임 변수가 포함됩니다.

파일

파일은 확장 프로그램의 루트에 상대적인 경로인 문자열로 지정됩니다. 를 참조하세요. 다음 코드는 script.js 파일을 기본 표시됩니다.

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("injected script file"));

런타임 함수

scripting.executeScript()로 JavaScript를 삽입할 때 함수를 호출합니다. 이 함수는 함수여야 합니다. 변수입니다.

function getTabId() { ... }
function getTitle() { return document.title; }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : getTitle,
    })
    .then(() => console.log("injected a function"));

function getTabId() { ... }
function getUserColor() { ... }

function changeBackgroundColor() {
  document.body.style.backgroundColor = getUserColor();
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
    })
    .then(() => console.log("injected a function"));

args 속성을 사용하여 이 문제를 해결할 수 있습니다.

function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
  document.body.style.backgroundColor = backgroundColor;
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
      args : [ getUserColor() ],
    })
    .then(() => console.log("injected a function"));

런타임 문자열

페이지 내에 CSS를 삽입하는 경우 css 속성입니다. 이 옵션은 scripting.insertCSS()에만 사용할 수 있습니다. 나 scripting.executeScript()를 사용하여 문자열을 실행할 수 없습니다.

function getTabId() { ... }
const css = "body { background-color: red; }";

chrome.scripting
    .insertCSS({
      target : {tabId : getTabId()},
      css : css,
    })
    .then(() => console.log("CSS injected"));

결과 처리

JavaScript 실행 결과는 확장 프로그램에 전달됩니다. 단일 결과 포함됩니다 메인 프레임은 결과 배열 다른 모든 프레임은 비결정적 순서입니다.

function getTabId() { ... }
function getTitle() { return document.title; }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : getTitle,
    })
    .then(injectionResults => {
      for (const {frameId, result} of injectionResults) {
        console.log(`Frame ${frameId} result:`, result);
      }
    });

scripting.insertCSS()는 결과를 반환하지 않습니다.

프로미스

스크립트 실행의 결과 값이 프로미스인 경우 Chrome은 대기합니다. 프라미스가 결정되고 결과 값을 반환합니다.

function getTabId() { ... }
async function addIframe() {
  const iframe = document.createElement("iframe");
  const loadComplete =
      new Promise(resolve => iframe.addEventListener("load", resolve));
  iframe.src = "https://example.com";
  document.body.appendChild(iframe);
  await loadComplete;
  return iframe.contentWindow.document.title;
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : addIframe,
    })
    .then(injectionResults => {
      for (const frameResult of injectionResults) {
        const {frameId, result} = frameResult;
        console.log(`Frame ${frameId} result:`, result);
      }
    });

예

모든 동적 콘텐츠 스크립트 등록 취소

다음 스니펫에는 모든 동적 콘텐츠를 등록 취소하는 함수가 포함되어 있습니다. 이전에 등록한 스크립트가 있는지 확인합니다.

async function unregisterAllDynamicContentScripts() {
  try {
    const scripts = await chrome.scripting.getRegisteredContentScripts();
    const scriptIds = scripts.map(script => script.id);
    return chrome.scripting.unregisterContentScripts(scriptIds);
  } catch (error) {
    const message = [
      "An unexpected error occurred while",
      "unregistering dynamic content scripts.",
    ].join(" ");
    throw new Error(message, {cause : error});
  }
}

chrome.scripting API를 사용해 보려면 다음 안내를 따르세요. Chrome 확장 프로그램 샘플의 스크립팅 샘플을 설치합니다. 저장소

유형

ContentScriptFilter

Chrome 96 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

속성

  • ids

    string[] 선택사항

    지정하면 getRegisteredContentScripts에서 ID가 이 목록에 지정된 스크립트만 반환합니다.

CSSInjection

속성

  • css

    문자열(선택사항)

    삽입할 CSS가 포함된 문자열입니다. files와 css 중 정확히 하나를 지정해야 합니다.

  • 파일

    string[] 선택사항

    삽입할 CSS 파일의 상대 경로로, 확장 프로그램의 루트 디렉터리를 기준으로 합니다. files와 css 중 정확히 하나를 지정해야 합니다.

  • 출처

    StyleOrigin 선택사항

    삽입의 스타일 출처입니다. 기본값은 'AUTHOR'입니다.

  • CSS를 삽입할 타겟을 지정하는 세부정보입니다.

ExecutionWorld

Chrome 95 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

스크립트를 실행할 JavaScript 환경입니다.

열거형

"ISOLATED"
이 확장 프로그램에 고유한 실행 환경인 격리된 환경을 지정합니다.

"MAIN"
호스트 페이지의 JavaScript와 공유되는 실행 환경인 DOM의 기본 환경을 지정합니다.

InjectionResult

속성

  • documentId

    문자열

    Chrome 106 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    삽입과 관련된 문서입니다.

  • frameId

    숫자

    Chrome 90 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    삽입과 관련된 프레임입니다.

  • 결과

    선택사항

    스크립트 실행 결과입니다.

InjectionTarget

속성

  • allFrames

    불리언 선택사항

    스크립트가 탭 내의 모든 프레임에 삽입되어야 하는지 여부입니다. 기본값은 false입니다. frameIds가 지정된 경우 true가 아니어야 합니다.

  • documentIds

    string[] 선택사항

    Chrome 106 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    삽입할 특정 문서 ID의 ID. frameIds가 설정된 경우에는 설정하면 안 됩니다.

  • frameIds

    number[] 선택사항

    삽입할 특정 프레임의 ID입니다.

  • tabId

    숫자

    삽입할 탭의 ID입니다.

RegisteredContentScript

Chrome 96 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

속성

  • allFrames

    불리언 선택사항

    true로 지정하면 프레임이 탭의 최상위 프레임이 아니더라도 모든 프레임에 삽입됩니다. 각 프레임에서 URL 요구사항을 개별적으로 확인합니다. URL 요구사항이 충족되지 않으면 하위 프레임에 삽입되지 않습니다. 기본값은 false이며, 이는 상단 프레임만 일치함을 의미합니다.

  • css

    string[] 선택사항

    일치하는 페이지에 삽입할 CSS 파일의 목록입니다. 이러한 요소는 페이지에 대한 DOM이 구성되거나 표시되기 전에 이 배열에 나타난 순서대로 삽입됩니다.

  • excludeMatches

    string[] 선택사항

    이 콘텐츠 스크립트가 삽입될 수 있는 페이지는 제외됩니다. 이러한 문자열의 구문에 관한 자세한 내용은 패턴 일치를 참고하세요.

  • id

    문자열

    API 호출에 지정된 콘텐츠 스크립트의 ID입니다. '_'로 시작할 수 없습니다. 생성된 스크립트 ID의 접두사로 예약되어 있기 때문입니다.

  • js

    string[] 선택사항

    일치하는 페이지에 삽입할 JavaScript 파일의 목록입니다. 이 배열에 표시된 순서대로 삽입됩니다.

  • matchOriginAsFallback

    불리언 선택사항

    Chrome 119 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    URL에 지원되지 않는 스키마가 포함된 경우 스크립트를 프레임에 삽입할 수 있는지 여부를 나타냅니다. 구체적으로는 about:, data:, blob:, 파일 시스템: 중 하나입니다. 이러한 경우 스크립트를 삽입해야 하는지 결정하기 위해 URL의 출처를 확인합니다. 출처가 null인 경우 (data: URL의 경우와 동일) 사용되는 출처는 현재 프레임을 만든 프레임 또는 이 프레임으로의 탐색을 시작한 프레임입니다. 이 프레임은 상위 프레임이 아닐 수 있습니다.

  • 일치

    string[] 선택사항

    이 콘텐츠 스크립트를 삽입할 페이지를 지정합니다. 이러한 문자열의 구문에 관한 자세한 내용은 패턴 일치를 참고하세요. registerContentScripts에 대해 지정해야 합니다.

  • persistAcrossSessions

    불리언 선택사항

    이 콘텐츠 스크립트를 이후 세션에서도 유지할지 지정합니다. 기본값은 true입니다.

  • runAt

    RunAt 선택사항

    JavaScript 파일이 웹페이지에 삽입되는 시기를 지정합니다. 선호 및 기본값은 document_idle입니다.

  • 세계

    ExecutionWorld 선택사항

    Chrome 102 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    JavaScript '세계' 스크립트를 실행할 수 있습니다 기본값은 ISOLATED입니다.

ScriptInjection

속성

  • args

    any[] 선택사항

    Chrome 92 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    제공된 함수에 전달할 인수입니다. func 매개변수가 지정된 경우에만 유효합니다. 이러한 인수는 JSON 직렬화가 가능해야 합니다.

  • 파일

    string[] 선택사항

    삽입할 JS 또는 CSS 파일의 경로로, 확장 프로그램의 루트 디렉터리를 기준으로 합니다. files 또는 func 중 정확히 하나를 지정해야 합니다.

  • injectImmediately

    불리언 선택사항

    Chrome 102 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    타겟에서 삽입을 최대한 빨리 트리거해야 하는지 여부입니다. 스크립트가 타겟에 도달할 때 이미 페이지가 로드되었을 수 있으므로 페이지 로드 전에 삽입이 발생한다고 보장할 수는 없습니다.

  • 스크립트를 삽입할 대상을 지정하는 세부정보입니다.

  • 세계

    ExecutionWorld 선택사항

    Chrome 95 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    JavaScript '세계' 스크립트를 실행할 수 있습니다 기본값은 ISOLATED입니다.

  • func

    void 선택사항

    Chrome 92 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    삽입할 JavaScript 함수. 이 함수는 직렬화된 후 삽입을 위해 역직렬화됩니다. 즉, 바인딩된 매개변수와 실행 컨텍스트가 손실됩니다. files 또는 func 중 정확히 하나를 지정해야 합니다.

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

    () => {...}

StyleOrigin

스타일 변경의 출처입니다. 자세한 내용은 스타일 출처를 참고하세요.

열거형

'AUTHOR'

'사용자'

메서드

executeScript()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.scripting.executeScript(
  injection: ScriptInjection,
  callback?: function,
)

스크립트를 대상 컨텍스트에 삽입합니다. 기본적으로 스크립트는 document_idle에서 실행되거나 페이지가 이미 로드된 경우 즉시 실행됩니다. injectImmediately 속성이 설정되면 페이지 로드가 완료되지 않았더라도 스크립트가 대기 없이 삽입됩니다. 스크립트가 프라미스로 평가되면 브라우저는 프라미스가 해결될 때까지 기다렸다가 결과 값을 반환합니다.

매개변수

반환 값

  • Promise&lt;InjectionResult[]&gt;

    Chrome 90 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

getRegisteredContentScripts()

<ph type="x-smartling-placeholder"></ph> 프로미스 Chrome 96 이상 
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

지정된 필터와 일치하는 이 확장 프로그램의 동적으로 등록된 모든 콘텐츠 스크립트를 반환합니다.

매개변수

반환 값

  • Promise&lt;RegisteredContentScript[]&gt;

    프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

insertCSS()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.scripting.insertCSS(
  injection: CSSInjection,
  callback?: function,
)

CSS 스타일시트를 대상 컨텍스트에 삽입합니다. 여러 프레임이 지정되면 실패한 삽입은 무시됩니다.

매개변수

  • 삽입

    CSSInjection

    삽입할 스타일의 세부정보입니다.

  • 콜백

    함수 선택사항

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

    () => void

반환 값

  • 프로미스<void>

    Chrome 90 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

registerContentScripts()

<ph type="x-smartling-placeholder"></ph> 프로미스 Chrome 96 이상 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

이 확장 프로그램에 하나 이상의 콘텐츠 스크립트를 등록합니다.

매개변수

  • 스크립트

    RegisteredContentScript[]

    등록할 스크립트 목록이 포함되어 있습니다. 스크립트 파싱/파일 유효성 검사 중에 오류가 발생하거나 지정된 ID가 이미 존재하는 경우 스크립트가 등록되지 않습니다.

  • 콜백

    함수 선택사항

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

    () => void

반환 값

  • 프로미스<void>

    프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

removeCSS()

<ph type="x-smartling-placeholder"></ph> 프로미스 Chrome 90 이상 
chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

이전에 이 확장 프로그램에 의해 삽입된 CSS 스타일시트를 타겟 컨텍스트에서 삭제합니다.

매개변수

  • 삽입

    CSSInjection

    삭제할 스타일의 세부정보입니다. css, files 및 origin 속성은 insertCSS를 통해 삽입된 스타일시트와 정확히 일치해야 합니다. 존재하지 않는 스타일시트를 제거하려고 해도 작동하지 않습니다.

  • 콜백

    함수 선택사항

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

    () => void

반환 값

  • 프로미스<void>

    프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

unregisterContentScripts()

<ph type="x-smartling-placeholder"></ph> 프로미스 Chrome 96 이상 
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

이 확장 프로그램의 콘텐츠 스크립트 등록을 취소합니다.

매개변수

  • filter

    ContentScriptFilter 선택사항

    지정하면 필터와 일치하는 동적 콘텐츠 스크립트만 등록 취소합니다. 그렇지 않으면 확장 프로그램의 모든 동적 콘텐츠 스크립트가 등록 취소됩니다.

  • 콜백

    함수 선택사항

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

    () => void

반환 값

  • 프로미스<void>

    프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

updateContentScripts()

<ph type="x-smartling-placeholder"></ph> 프로미스 Chrome 96 이상 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

이 확장 프로그램에 대한 하나 이상의 콘텐츠 스크립트를 업데이트합니다.

매개변수

  • 스크립트

    RegisteredContentScript[]

    업데이트할 스크립트 목록이 포함됩니다. 속성은 이 객체에 지정된 경우에만 기존 스크립트에 대해 업데이트됩니다. 스크립트 파싱/파일 유효성 검사 중에 오류가 발생하거나 지정된 ID가 완전히 등록된 스크립트에 해당하지 않는 경우 스크립트가 업데이트되지 않습니다.

  • 콜백

    함수 선택사항

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

    () => void

반환 값

  • 프로미스<void>

    프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.