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를 지정하여 탭의 특정 프레임에 삽입할 수도 있습니다. 프레임 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({ ids: 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 중 하나를 정확히 지정해야 합니다.

  • origin

    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 이상

    삽입할 특정 documentId의 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:, filesystem:)가 포함된 프레임에 삽입할 수 있는지 여부를 나타냅니다. 이 경우 스크립트를 삽입해야 하는지 확인하기 위해 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 optional

    Chrome 92 이상

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

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

    () => {...}

StyleOrigin

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

열거형

"AUTHOR"

"USER"

메서드

executeScript()

chrome.scripting.executeScript(
  injection: ScriptInjection,
): Promise<InjectionResult[]>

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

매개변수

반환 값

getRegisteredContentScripts()

Chrome 96 이상 
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

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

매개변수

  • filter

    ContentScriptFilter 선택사항

    확장 프로그램의 동적으로 등록된 스크립트를 필터링하는 객체입니다.

반환 값

insertCSS()

chrome.scripting.insertCSS(
  injection: CSSInjection,
): Promise<void>

타겟 컨텍스트에 CSS 스타일시트를 삽입합니다. 프레임이 여러 개 지정된 경우 삽입에 실패한 프레임은 무시됩니다.

매개변수

  • 삽입

    CSSInjection

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

반환 값

  • Promise<void>

    Chrome 90 이상

registerContentScripts()

Chrome 96 이상 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

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

매개변수

  • 스크립트

    RegisteredContentScript[]

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

반환 값

  • Promise<void>

removeCSS()

Chrome 90 이상 
chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

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

매개변수

  • 삽입

    CSSInjection

    삭제할 스타일의 세부정보입니다. css, files, origin 속성은 insertCSS을 통해 삽입된 스타일시트와 정확하게 일치해야 합니다. 존재하지 않는 스타일시트를 삭제하려고 하면 아무 작업도 실행되지 않습니다.

반환 값

  • Promise<void>

unregisterContentScripts()

Chrome 96 이상 
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

이 확장 프로그램의 콘텐츠 스크립트를 등록 해제합니다.

매개변수

  • filter

    ContentScriptFilter 선택사항

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

반환 값

  • Promise<void>

updateContentScripts()

Chrome 96 이상 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

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

매개변수

  • 스크립트

    RegisteredContentScript[]

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

반환 값

  • Promise<void>