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 매개변수를 사용하여 자바스크립트 또는 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"));

참고: "frameIds" 속성과 "allFrames" 속성을 모두 지정할 수는 없습니다.

삽입된 코드

확장 프로그램은 외부 파일이나 런타임 변수를 통해 삽입될 코드를 지정할 수 있습니다.

파일

파일은 확장 프로그램의 루트 디렉터리에 상대적인 경로인 문자열로 지정됩니다. 다음 코드는 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'입니다.

• 대상

  InjectionTarget

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

ExecutionWorld

Chrome 95 이상

스크립트가 실행될 자바스크립트 환경입니다.

열거형

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

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

InjectionResult

속성

• documentId

  string

  Chrome 106 이상

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

• frameId

  숫자

  Chrome 90 이상

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

• 결과

  모든 선택사항

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

InjectionTarget

속성

• allFrames

  부울 선택사항

  스크립트가 탭 내의 모든 프레임에 삽입되어야 하는지 여부입니다. 기본값은 거짓입니다. 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

  string

  API 호출에서 지정된 콘텐츠 스크립트의 ID입니다. '_'로 시작하면 안 됩니다. 생성된 스크립트 ID의 접두사로 예약되어 있습니다.

• js

  string[] 선택사항

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

• matchOriginAsFallback

  부울 선택사항

  Chrome 119 이상

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

• 일치

  string[] 선택사항

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

• persistAcrossSessions

  부울 선택사항

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

• runAt

  RunAt 선택사항

  자바스크립트 파일이 웹페이지에 삽입되는 시점을 지정합니다. 선호되는 기본값은 document_idle입니다.

• 월드

  ExecutionWorld 선택사항

  Chrome 102 이상

  스크립트를 실행할 자바스크립트 'world'입니다. 기본값은 ISOLATED입니다.

ScriptInjection

속성

• args

  any[] 선택사항

  Chrome 92 이상

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

• 파일

  string[] 선택사항

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

• injectImmediately

  부울 선택사항

  Chrome 102 이상

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

• 대상

  InjectionTarget

  스크립트를 삽입할 타겟을 지정하는 세부정보입니다.

• 월드

  ExecutionWorld 선택사항

  Chrome 95 이상

  스크립트를 실행할 자바스크립트 'world'입니다. 기본값은 ISOLATED입니다.

• func

  void 선택사항

  Chrome 92 이상

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

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

  ()=> {...}

StyleOrigin

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

열거형

방법

executeScript()

프로미스

chrome.scripting.executeScript(
  injection: ScriptInjection,
  callback?: function,
)

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

매개변수

• 삽입

  ScriptInjection

  삽입할 스크립트의 세부정보입니다.

• 콜백

  함수 선택사항

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

  (results: InjectionResult[])=>void

  • 경기 결과

    InjectionResult[]

반환 값

• Promise<InjectionResult[]>

  Chrome 90 이상

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

getRegisteredContentScripts()

Promise Chrome 96 이상

chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

매개변수

• filter

  ContentScriptFilter 선택사항

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

• 콜백

  함수 선택사항

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

  (scripts: RegisteredContentScript[])=>void

  • 스크립트

    RegisteredContentScript[]

반환 값

• Promise<RegisteredContentScript[]>

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

insertCSS()

프로미스

chrome.scripting.insertCSS(
  injection: CSSInjection,
  callback?: function,
)

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

매개변수

• 삽입

  CSSInjection

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

• 콜백

  함수 선택사항

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

  ()=>void

반환 값

• Promise<void>

  Chrome 90 이상

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

registerContentScripts()

Promise Chrome 96 이상

chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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

매개변수

• 스크립트

  RegisteredContentScript[]

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

• 콜백

  함수 선택사항

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

  ()=>void

반환 값

• Promise<void>

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

removeCSS()

Promise Chrome 90 이상

chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

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

매개변수

• 삽입

  CSSInjection

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

• 콜백

  함수 선택사항

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

  ()=>void

반환 값

• Promise<void>

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

unregisterContentScripts()

Promise Chrome 96 이상

chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

매개변수

• filter

  ContentScriptFilter 선택사항

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

• 콜백

  함수 선택사항

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

  ()=>void

반환 값

• Promise<void>

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

updateContentScripts()

Promise Chrome 96 이상

chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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

매개변수

• 스크립트

  RegisteredContentScript[]

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

• 콜백

  함수 선택사항

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

  ()=>void

반환 값

• Promise<void>

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