chrome.scripting (original) (raw)

설명

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

권한

scripting

가용성

매니페스트

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

속성

CSSInjection

속성

ExecutionWorld

스크립트가 실행될 JavaScript 세계입니다.

열거형

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

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

InjectionResult

속성

InjectionTarget

속성

RegisteredContentScript

속성

ScriptInjection

속성

StyleOrigin

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

열거형

메서드

executeScript()

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

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

반환 값

getRegisteredContentScripts()

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

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

매개변수

반환 값

insertCSS()

chrome.scripting.insertCSS(
  injection: CSSInjection,
): Promise

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

반환 값

registerContentScripts()

chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise

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

매개변수

반환 값

removeCSS()

chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise

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

매개변수

반환 값

unregisterContentScripts()

chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise

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

매개변수

반환 값

updateContentScripts()

chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise

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

매개변수

반환 값