설명
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
속성
- ids
string[] 선택사항
지정된 경우
getRegisteredContentScripts는 이 목록에 지정된 ID가 있는 스크립트만 반환합니다.
CSSInjection
속성
- css
문자열 선택사항
삽입할 CSS가 포함된 문자열입니다.
files및css중 하나를 정확히 지정해야 합니다. - 파일
string[] 선택사항
확장 프로그램의 루트 디렉터리를 기준으로 삽입할 CSS 파일의 경로입니다.
files및css중 하나를 정확히 지정해야 합니다. - origin
StyleOrigin 선택사항
삽입의 스타일 출처입니다. 기본값은
'AUTHOR'입니다. - target
CSS를 삽입할 타겟을 지정하는 세부정보입니다.
ExecutionWorld
스크립트가 실행될 JavaScript 세계입니다.
열거형
'ISOLATED'
이 확장 프로그램에 고유한 실행 환경인 격리된 세계를 지정합니다.
'MAIN'
호스트 페이지의 JavaScript와 공유되는 실행 환경인 DOM의 기본 세계를 지정합니다.
InjectionResult
속성
- documentId
문자열
Chrome 106 이상삽입과 연결된 문서입니다.
- frameId
숫자
Chrome 90 이상삽입과 연결된 프레임입니다.
- 결과
선택사항
스크립트 실행 결과입니다.
InjectionTarget
속성
RegisteredContentScript
속성
- 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 이상타겟에서 삽입을 최대한 빨리 트리거해야 하는지 여부입니다. 스크립트가 타겟에 도달할 때 페이지가 이미 로드되었을 수 있으므로 페이지 로드 전에 삽입이 발생한다는 보장은 없습니다.
- target
스크립트를 삽입할 타겟을 지정하는 세부정보입니다.
- 세계
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 속성이 설정된 경우 페이지 로드가 완료되지 않았더라도 스크립트가 기다리지 않고 삽입됩니다. 스크립트가 프로미스로 평가되면 브라우저는 프로미스가 처리될 때까지 기다린 후 결과 값을 반환합니다.
매개변수
-
삽입할 스크립트의 세부정보입니다.
반환 값
-
Promise<InjectionResult[]>
Chrome 90 이상
getRegisteredContentScripts()
chrome.scripting.getRegisteredContentScripts(
filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>
지정된 필터와 일치하는 이 확장 프로그램의 동적으로 등록된 모든 콘텐츠 스크립트를 반환합니다.
매개변수
- filter
ContentScriptFilter 선택사항
확장 프로그램의 동적으로 등록된 스크립트를 필터링하는 객체입니다.
반환 값
-
Promise<RegisteredContentScript[]>
insertCSS()
chrome.scripting.insertCSS(
injection: CSSInjection,
): Promise<void>
타겟 컨텍스트에 CSS 스타일시트를 삽입합니다. 프레임이 여러 개 지정된 경우 삽입에 실패한 프레임은 무시됩니다.
매개변수
- 삽입
삽입할 스타일의 세부정보입니다.
반환 값
-
Promise<void>
Chrome 90 이상
registerContentScripts()
chrome.scripting.registerContentScripts(
scripts: RegisteredContentScript[],
): Promise<void>
이 확장 프로그램의 콘텐츠 스크립트를 하나 이상 등록합니다.
매개변수
- 스크립트
등록할 스크립트 목록을 포함합니다. 스크립트 파싱/파일 유효성 검사 중에 오류가 있거나 지정된 ID가 이미 있는 경우 스크립트가 등록되지 않습니다.
반환 값
-
Promise<void>
removeCSS()
chrome.scripting.removeCSS(
injection: CSSInjection,
): Promise<void>
이 확장 프로그램이 이전에 삽입한 CSS 스타일시트를 타겟 컨텍스트에서 삭제합니다.
매개변수
- 삽입
삭제할 스타일의 세부정보입니다.
css,files,origin속성은insertCSS을 통해 삽입된 스타일시트와 정확하게 일치해야 합니다. 존재하지 않는 스타일시트를 삭제하려고 하면 아무 작업도 실행되지 않습니다.
반환 값
-
Promise<void>
unregisterContentScripts()
chrome.scripting.unregisterContentScripts(
filter?: ContentScriptFilter,
): Promise<void>
이 확장 프로그램의 콘텐츠 스크립트를 등록 해제합니다.
매개변수
- filter
ContentScriptFilter 선택사항
지정된 경우 필터와 일치하는 동적 콘텐츠 스크립트만 등록 해제합니다. 그렇지 않으면 확장 프로그램의 모든 동적 콘텐츠 스크립트가 등록 해제됩니다.
반환 값
-
Promise<void>
updateContentScripts()
chrome.scripting.updateContentScripts(
scripts: RegisteredContentScript[],
): Promise<void>
이 확장 프로그램의 하나 이상의 콘텐츠 스크립트를 업데이트합니다.
매개변수
- 스크립트
업데이트할 스크립트 목록이 포함되어 있습니다. 속성은 이 객체에 지정된 경우에만 기존 스크립트에 대해 업데이트됩니다. 스크립트 파싱/파일 유효성 검사 중에 오류가 발생하거나 지정된 ID가 완전히 등록된 스크립트에 해당하지 않으면 스크립트가 업데이트되지 않습니다.
반환 값
-
Promise<void>