설명
chrome.scripting API를 사용하여 다양한 컨텍스트에서 스크립트를 실행합니다.
권한
scripting가용성
매니페스트
browser.scripting API를 사용하려면 매니페스트에서 "scripting" 권한과 스크립트를 삽입할 페이지의 호스트 권한을 선언합니다. "host_permissions" 키 또는 "activeTab" 권한을 사용합니다. 이 권한은 임시 호스트 권한을 부여합니다. 다음 예에서는 activeTab 권한을 사용합니다.
{
"name": "Scripting Extension",
"manifest_version": 3,
"permissions": ["scripting", "activeTab"],
...
}
개념 및 사용법
browser.scripting API를 사용하여 웹사이트에 JavaScript 및 CSS를 삽입할 수 있습니다. 이는 콘텐츠 스크립트로 할 수 있는 작업과 유사합니다. 하지만 browser.scripting 네임스페이스를 사용하면 확장 프로그램이 런타임에 결정을 내릴 수 있습니다.
삽입 대상
target 매개변수를 사용하여 자바스크립트 또는 CSS를 삽입할 타겟을 지정할 수 있습니다.
필수 필드는 tabId뿐입니다. 기본적으로 삽입은 지정된 탭의 기본 프레임에서 실행됩니다.
function getTabId() { ... }
browser.scripting
.executeScript({
target : {tabId : getTabId()},
files : [ "script.js" ],
})
.then(() => console.log("script injected"));
지정된 탭의 모든 프레임에서 실행하려면 allFrames 불리언을 true로 설정하면 됩니다.
function getTabId() { ... }
browser.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
files : [ "script.js" ],
})
.then(() => console.log("script injected in all frames"));
개별 프레임 ID를 지정하여 탭의 특정 프레임에 삽입할 수도 있습니다. 프레임 ID에 관한 자세한 내용은 browser.webNavigation API를 참고하세요.
function getTabId() { ... }
browser.scripting
.executeScript({
target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
files : [ "script.js" ],
})
.then(() => console.log("script injected on target frames"));
삽입된 코드
확장 프로그램은 외부 파일 또는 런타임 변수를 통해 삽입할 코드를 지정할 수 있습니다.
파일
파일은 확장 프로그램의 루트 디렉터리를 기준으로 하는 경로인 문자열로 지정됩니다. 다음 코드는 script.js 파일을 탭의 기본 프레임에 삽입합니다.
function getTabId() { ... }
browser.scripting
.executeScript({
target : {tabId : getTabId()},
files : [ "script.js" ],
})
.then(() => console.log("injected script file"));
런타임 함수
scripting.executeScript()를 사용하여 JavaScript를 삽입할 때 파일 대신 실행할 함수를 지정할 수 있습니다. 이 함수는 현재 확장 프로그램 컨텍스트에서 사용할 수 있는 함수 변수여야 합니다.
function getTabId() { ... }
function getTitle() { return document.title; }
browser.scripting
.executeScript({
target : {tabId : getTabId()},
func : getTitle,
})
.then(() => console.log("injected a function"));
function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor() {
document.body.style.backgroundColor = getUserColor();
}
browser.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;
}
browser.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; }";
browser.scripting
.insertCSS({
target : {tabId : getTabId()},
css : css,
})
.then(() => console.log("CSS injected"));
결과 처리
JavaScript 실행 결과가 확장 프로그램에 전달됩니다. 프레임당 하나의 결과가 포함됩니다. 기본 프레임은 결과 배열의 첫 번째 색인으로 보장됩니다. 다른 모든 프레임은 비결정적 순서입니다.
function getTabId() { ... }
function getTitle() { return document.title; }
browser.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;
}
browser.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 browser.scripting.getRegisteredContentScripts();
const scriptIds = scripts.map(script => script.id);
return browser.scripting.unregisterContentScripts({ ids: scriptIds });
} catch (error) {
const message = [
"An unexpected error occurred while",
"unregistering dynamic content scripts.",
].join(" ");
throw new Error(message, {cause : error});
}
}
browser.scripting API를 사용해 보려면 Chrome 확장 프로그램 샘플 저장소에서 스크립팅 샘플을 설치하세요.
유형
ContentScriptFilter
속성
-
ids
string[] 선택사항
지정된 경우
getRegisteredContentScripts는 이 목록에 지정된 ID가 있는 스크립트만 반환합니다.
CSSInjection
속성
-
css
문자열 선택사항
삽입할 CSS가 포함된 문자열입니다.
files및css중 하나만 지정해야 합니다. -
파일
string[] 선택사항
삽입할 CSS 파일의 경로로, 확장 프로그램의 루트 디렉터리를 기준으로 합니다.
files및css중 하나만 지정해야 합니다. -
origin
StyleOrigin 선택사항
삽입의 스타일 출처입니다. 기본값은
'AUTHOR'입니다. -
CSS를 삽입할 타겟을 지정하는 세부정보입니다.
ExecutionWorld
스크립트가 실행될 JavaScript 환경입니다.
열거형
"ISOLATED"
이 확장 프로그램에 고유한 실행 환경인 격리된 환경을 지정합니다.
'MAIN'
DOM의 기본 환경을 지정합니다. 이 환경은 호스트 페이지의 JavaScript와 공유되는 실행 환경입니다.
InjectionResult
속성
-
documentId
문자열
Chrome 106 이상 Chrome 148 이후의 browser.*삽입과 연결된 문서입니다.
-
frameId
숫자
Chrome 90 이상 브라우저.*(Chrome 148부터)삽입과 연결된 프레임입니다.
-
결과
any 선택사항
스크립트 실행 결과입니다.
InjectionTarget
속성
RegisteredContentScript
속성
-
allFrames
불리언 선택사항
true로 지정하면 프레임이 탭의 최상위 프레임이 아니더라도 모든 프레임에 삽입됩니다. 각 프레임은 URL의 요건을 독립적으로 확인합니다. URL의 요건이 충족되지 않으면 하위 프레임에 삽입되지 않습니다. 기본값은 false이며, 이는 최상위 프레임만 일치함을 의미합니다.
-
css
string[] 선택사항
일치하는 페이지에 삽입할 CSS 파일 목록입니다. 이러한 스크립트는 페이지에 DOM이 구성되거나 표시되기 전에 이 배열에 표시되는 순서대로 삽입됩니다.
-
excludeMatches
string[] 선택사항
이 콘텐츠 스크립트가 삽입될 페이지를 제외합니다. 이러한 문자열의 문법에 관한 자세한 내용은 일치 패턴을 참고하세요.
-
id
문자열
API 호출에 지정된 콘텐츠 스크립트의 ID입니다. 생성된 스크립트 ID의 프리픽스로 예약되어 있으므로 '_'로 시작해서는 안 됩니다.
-
js
string[] 선택사항
일치하는 페이지에 삽입할 JavaScript 파일 목록입니다. 이 배열에 표시되는 순서대로 삽입됩니다.
-
matchOriginAsFallback
불리언 선택사항
Chrome 119 이상 브라우저.*(Chrome 148부터)URL에 지원되지 않는 스키마(특히 about:, data:, blob:, filesystem:)가 포함된 프레임에 스크립트를 삽입할 수 있는지 여부를 나타냅니다. 이 경우 URL의 출처를 확인하여 스크립트를 삽입해야 하는지 결정합니다. 출처가
null인 경우(data: URL의 경우) 사용되는 출처는 현재 프레임을 만든 프레임 또는 이 프레임으로의 탐색을 시작한 프레임입니다. 상위 프레임이 아닐 수도 있습니다. -
일치
string[] 선택사항
이 콘텐츠 스크립트가 삽입될 페이지를 지정합니다. 이러한 문자열의 문법에 관한 자세한 내용은 일치 패턴을 참고하세요.
registerContentScripts에 지정해야 합니다. -
persistAcrossSessions
불리언 선택사항
이 콘텐츠 스크립트가 향후 세션에서 유지될지 지정합니다. 기본값은 true입니다.
-
runAt
RunAt 선택사항
JavaScript 파일이 웹페이지에 삽입되는 시점을 지정합니다. 기본값은
document_idle입니다. -
세계
ExecutionWorld 선택사항
Chrome 102 이상 브라우저.* Chrome 148부터스크립트를 실행할 JavaScript 'world'입니다. 기본값은
ISOLATED입니다.
ScriptInjection
속성
-
args
any[] 선택사항
Chrome 92 이상 browser.*(Chrome 148 이후)제공된 함수에 전달할 인수입니다. 이는
func매개변수가 지정된 경우에만 유효합니다. 이러한 인수는 JSON 직렬화 가능해야 합니다. -
파일
string[] 선택사항
삽입할 JS 또는 CSS 파일의 경로로, 확장 프로그램의 루트 디렉터리를 기준으로 합니다.
files또는func중 하나만 지정해야 합니다. -
injectImmediately
불리언 선택사항
Chrome 102 이상 브라우저.* Chrome 148부터대상에서 삽입을 최대한 빨리 트리거해야 하는지 여부입니다. 스크립트가 타겟에 도달할 때까지 페이지가 이미 로드되었을 수 있으므로 페이지 로드 전에 삽입이 발생한다고 보장할 수는 없습니다.
-
스크립트를 삽입할 타겟을 지정하는 세부정보입니다.
-
세계
ExecutionWorld 선택사항
Chrome 95 이상 브라우저.*(Chrome 148부터)스크립트를 실행할 JavaScript 'world'입니다. 기본값은
ISOLATED입니다. -
func
void 선택사항
Chrome 92 이상 browser.*(Chrome 148 이후)삽입할 JavaScript 함수입니다. 이 함수는 직렬화된 후 삽입을 위해 역직렬화됩니다. 즉, 바인딩된 매개변수와 실행 컨텍스트가 손실됩니다.
files또는func중 하나만 지정해야 합니다.func함수는 다음과 같습니다.() => {...}
StyleOrigin
스타일 변경의 출처입니다. 자세한 내용은 스타일 출처를 참고하세요.
열거형
"AUTHOR"
"USER"
메서드
executeScript()
browser.scripting.executeScript(
injection: ScriptInjection,
): Promise<InjectionResult[]>
스크립트를 타겟 컨텍스트에 삽입합니다. 기본적으로 스크립트는 document_idle에 실행되거나 페이지가 이미 로드된 경우 즉시 실행됩니다. injectImmediately 속성이 설정된 경우 페이지 로드가 완료되지 않았더라도 스크립트가 대기 없이 삽입됩니다. 스크립트가 프로미스로 평가되면 브라우저는 프로미스가 해결될 때까지 기다린 후 결과 값을 반환합니다.
매개변수
-
삽입할 스크립트의 세부정보입니다.
반환 값
-
Promise<InjectionResult[]>
Chrome 90 이상 브라우저.*(Chrome 148부터)삽입이 완료되면 결정되는 프로미스를 반환합니다. 결과 배열에는 삽입이 성공한 각 프레임의 실행 결과가 포함됩니다.
getRegisteredContentScripts()
browser.scripting.getRegisteredContentScripts(
filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>
지정된 필터와 일치하는 이 확장 프로그램의 동적으로 등록된 모든 콘텐츠 스크립트를 반환합니다.
매개변수
-
filter
ContentScriptFilter 선택사항
확장 프로그램의 동적으로 등록된 스크립트를 필터링하는 객체입니다.
반환 값
-
Promise<RegisteredContentScript[]>
insertCSS()
browser.scripting.insertCSS(
injection: CSSInjection,
): Promise<void>
대상 컨텍스트에 CSS 스타일시트를 삽입합니다. 여러 프레임이 지정된 경우 실패한 삽입은 무시됩니다.
매개변수
-
삽입
삽입할 스타일의 세부정보입니다.
반환 값
-
약속<void>
Chrome 90 이상 브라우저.*(Chrome 148부터)삽입이 완료되면 결정되는 프로미스를 반환합니다.
registerContentScripts()
browser.scripting.registerContentScripts(
scripts: RegisteredContentScript[],
): Promise<void>
이 확장 프로그램의 콘텐츠 스크립트를 하나 이상 등록합니다.
매개변수
-
스크립트
등록할 스크립트 목록을 포함합니다. 스크립트 파싱/파일 검증 중에 오류가 발생하거나 지정된 ID가 이미 존재하는 경우 스크립트가 등록되지 않습니다.
반환 값
-
약속<void>
스크립트가 완전히 등록되면 결정되고 오류가 발생하면 거부되는 프로미스를 반환합니다.
removeCSS()
browser.scripting.removeCSS(
injection: CSSInjection,
): Promise<void>
이 확장 프로그램에서 이전에 삽입한 CSS 스타일시트를 타겟 컨텍스트에서 삭제합니다.
매개변수
-
삽입
삭제할 스타일의 세부정보입니다.
css,files,origin속성은insertCSS를 통해 삽입된 스타일시트와 정확히 일치해야 합니다. 존재하지 않는 스타일시트를 삭제하려고 하면 작업이 수행되지 않습니다.
반환 값
-
약속<void>
삭제가 완료되면 결정되는 프로미스를 반환합니다.
unregisterContentScripts()
browser.scripting.unregisterContentScripts(
filter?: ContentScriptFilter,
): Promise<void>
이 확장 프로그램의 콘텐츠 스크립트를 등록 취소합니다.
매개변수
-
filter
ContentScriptFilter 선택사항
지정된 경우 필터와 일치하는 동적 콘텐츠 스크립트만 등록 취소합니다. 그렇지 않으면 확장 프로그램의 모든 동적 콘텐츠 스크립트가 등록 취소됩니다.
반환 값
-
약속<void>
스크립트가 등록 취소되면 해결되고 오류가 발생하면 거부되는 프로미스를 반환합니다.
updateContentScripts()
browser.scripting.updateContentScripts(
scripts: RegisteredContentScript[],
): Promise<void>
이 확장 프로그램의 콘텐츠 스크립트를 하나 이상 업데이트합니다.
매개변수
-
스크립트
업데이트할 스크립트 목록이 포함되어 있습니다. 속성은 이 객체에 지정된 경우에만 기존 스크립트에 대해 업데이트됩니다. 스크립트 파싱/파일 검증 중에 오류가 발생하거나 지정된 ID가 완전히 등록된 스크립트에 해당하지 않으면 스크립트가 업데이트되지 않습니다.
반환 값
-
약속<void>
스크립트가 업데이트되면 해결되거나 오류가 발생하면 거부되는 프로미스를 반환합니다.