설명
userScripts
API를 사용하여 사용자 스크립트 컨텍스트에서 사용자 스크립트를 실행합니다.
권한
userScripts
chrome.userScripts
API를 사용하려면 스크립트를 실행하려는 사이트의 manifest.json 및 "host_permissions"
에 "userScripts"
권한을 추가하세요.
{
"name": "User script test extension",
"manifest_version": 3,
"minimum_chrome_version": "120",
"permissions": [
"userScripts"
],
"host_permissions": [
"*://example.com/*"
]
}
지원 대상
개념 및 사용법
사용자 스크립트는 웹페이지에 삽입되어 모양이나 동작을 수정하는 코드입니다. 스크립트는 사용자가 만들���나 스크립트 저장소 또는 사용자 스크립트 확장 프로그램에서 다운로드됩니다.
확장 프로그램 사용자를 위한 개발자 모드
확장 프로그램 개발자로서 Chrome을 설치할 때 이미 개발자 모드를 사용하도록 설정했습니다. 사용자 스크립트 확장 프로그램의 경우 사용자가 개발자 모드도 사용 설정해야 합니다. 다음은 복사하여 내 문서에 붙여넣을 수 있는 안내입니다.
- 새 탭에
chrome://extensions
를 입력하여 확장 프로그램 페이지로 이동합니다. (chrome://
URL은 연결할 수 없도록 설계됨) 개발자 모드 옆에 있는 전환 스위치를 클릭하여 개발자 모드를 사용 설정합니다.
확장 프로그램 페이지 (chrome://extensions)
chrome.userScripts
에서 오류가 발생하는지 확인하여 개발자 모드가 사용 설정되었는지 확인할 수 있습니다. 예를 들면 다음과 같습니다.
function isUserScriptsAvailable() {
try {
// Property access which throws if developer mode is not enabled.
chrome.userScripts;
return true;
} catch {
// Not available.
return false;
}
}
고립된 환경에서의 업무 수행
사용자 스크립트와 콘텐츠 스크립트는 모두 분리된 환경이나 기본 환경에서 실행될 수 있습니다. 격리된 환경은 호스트 페이지 또는 다른 확장 프로그램에서 액세스할 수 없는 실행 환경입니다. 이렇게 하면 사용자 스크립트가 호스트 페이지나 다른 확장 프로그램의 사용자 및 콘텐츠 스크립트에 영향을 주지 않고 자바스크립트 환경을 변경할 수 있습니다. 반대로 사용자 스크립트 (및 콘텐츠 스크립트)는 다른 확장 프로그램의 호스트 페이지나 사용자 및 콘텐츠 스크립트에 표시되지 않습니다. 기본 환경에서 실행되는 스크립트는 호스트 페이지 및 기타 확장 프로그램에서 액세스할 수 있으며 호스트 페이지 및 기타 확장 프로그램에 표시됩니다. 세계를 선택하려면 userScripts.register()
를 호출할 때 "USER_SCRIPT"
또는 "MAIN"
를 전달합니다.
USER_SCRIPT
환경의 콘텐츠 보안 정책을 구성하려면 userScripts.configureWorld()
를 호출합니다.
chrome.userScripts.configureWorld({
csp: "script-src 'self'"
});
메시지
콘텐츠 스크립트 및 화면 밖 문서와 마찬가지로 사용자 스크립트는 메시지를 사용하여 확장 프로그램의 다른 부분과 통신합니다. 즉, 확장 프로그램의 다른 부분과 마찬가지로 runtime.sendMessage()
및 runtime.connect()
를 호출할 수 있습니다. 그러나 전용 이벤트 핸들러를 사용하여 수신됩니다 (즉, onMessage
또는 onConnect
를 사용하지 않음). 이러한 핸들러를 runtime.onUserScriptMessage
및 runtime.onUserScriptConnect
라고 합니다. 전용 핸들러를 사용하면 신뢰할 수 없는 컨텍스트인 사용자 스크립트에서 메시지를 더 쉽게 식별할 수 있습니다.
메시지를 보내기 전에 messaging
인수를 true
로 설정하여 configureWorld()
를 호출해야 합니다. csp
및 messaging
인수는 동시에 전달할 수 있습니다.
chrome.userScripts.configureWorld({
messaging: true
});
확장 프로그램 업데이트
확장 프로그램이 업데이트되면 사용자 스크립트가 삭제됩니다. 확장 프로그램 서비스 워커의 runtime.onInstalled
이벤트 핸들러에서 코드를 실행하여 다시 추가할 수 있습니다. 이벤트 콜백에 전달된 "update"
이유에만 응답합니다.
예
이 예는 샘플 저장소의 userScript 샘플에서 가져온 것입니다.
스크립트 등록
다음 예는 register()
의 기본 호출을 보여줍니다. 첫 번째 인수는 등록할 스크립트를 정의하는 객체의 배열입니다. 여기에 표시된 것보다 더 많은 옵션이 있습니다.
chrome.userScripts.register([{
id: 'test',
matches: ['*://*/*'],
js: [{code: 'alert("Hi!")'}]
}]);
유형
ExecutionWorld
사용자 스크립트가 실행될 JavaScript 환경입니다.
enum
"MAIN"
호스트 페이지의 자바스크립트와 공유되는 실행 환경인 DOM의 실행 환경을 지정합니다.
"USER_script"
사용자 스크립트와 관련된 실행 환경을 지정하며 페이지의 CSP에서 제외됩니다.
RegisteredUserScript
속성
-
allFrames
부울 선택사항
true인 경우 프레임이 탭의 최상위 프레임이 아니더라도 모든 프레임에 삽입됩니다. 각 프레임은 URL 요구사항을 독립적으로 확인하며, URL 요구사항이 충족되지 않으면 하위 프레임에 삽입되지 않습니다. 기본값은 false입니다. 즉, 상단 프레임만 일치합니다.
-
excludeGlobs
string[] 선택사항
이 사용자 스크립트를 삽입하지 않을 페이지의 와일드 카드 패턴을 지정합니다.
-
excludeMatches
string[] 선택사항
이 사용자 스크립트가 삽입될 페이지는 제외됩니다. 이러한 문자열의 구문에 대한 자세한 내용은 일치 패턴을 참조하세요.
-
id
문자열
API 호출에 지정된 사용자 스크립트의 ID입니다. 이 속성은 생성된 스크립트 ID의 접두사로 예약되어 있으므로 '_'로 시작하면 안 됩니다.
-
includeGlobs
string[] 선택사항
이 사용자 스크립트가 삽입될 페이지의 와일드 카드 패턴을 지정합니다.
-
js
일치하는 페이지에 삽입할 스크립트 소스를 정의하는 ScriptSource 객체의 목록입니다.
-
일치
string[] 선택사항
이 사용자 스크립트가 삽입될 페이지를 지정합니다. 이러한 문자열의 구문에 대한 자세한 내용은 일치 패턴을 참조하세요. ${ref:register}에 이 속성을 지정해야 합니다.
-
runAt
RunAt 선택사항
자바스크립트 파일이 웹페이지에 삽입되는 시점을 지정합니다. 선호되는 기본값은
document_idle
입니다. -
월드
ExecutionWorld 선택사항
스크립트를 실행할 자바스크립트 실행 환경입니다. 기본값은
`USER_SCRIPT`
입니다.
ScriptSource
속성
-
코드
문자열 선택사항
삽입할 자바스크립트 코드가 포함된 문자열입니다.
file
또는code
중 하나만 지정해야 합니다. -
파일
문자열 선택사항
확장 프로그램의 루트 디렉터리를 기준으로 삽입할 자바스크립트 파일의 경로입니다.
file
또는code
중 하나만 지정해야 합니다.
UserScriptFilter
속성
-
ids
string[] 선택사항
getScripts
는 이 목록에 지정된 ID가 있는 스크립트만 반환합니다.
WorldProperties
속성
-
CSP
문자열 선택사항
세계 csp를 지정합니다. 기본값은
`ISOLATED`
World csp입니다. -
메시지
부울 선택사항
메시징 API를 노출할지 여부를 지정합니다. 기본값은
false
입니다.
방법
configureWorld()
chrome.userScripts.configureWorld(
properties: WorldProperties,
callback?: function,
)
`USER_SCRIPT`
실행 환경을 구성합니다.
매개변수
-
사용자 스크립트 환경 구성을 포함합니다.
-
콜백
함수 선택사항
callback
매개변수는 다음과 같습니다.() => void
반환 값
-
Promise<void>
프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
getScripts()
chrome.userScripts.getScripts(
filter?: UserScriptFilter,
callback?: function,
)
이 확장 프로그램에 대해 동적으로 등록된 모든 사용자 스크립트를 반환합니다.
매개변수
-
filter
UserScriptFilter 선택사항
지정하면 이 메서드가 일치하는 사용자 스크립트만 반환합니다.
-
콜백
함수 선택사항
callback
매개변수는 다음과 같습니다.(scripts: RegisteredUserScript[]) => void
-
스크립트
-
반환 값
-
Promise<RegisteredUserScript[]>
프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
register()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
callback?: function,
)
이 확장 프로그램에 하나 이상의 사용자 스크립트를 등록합니다.
매개변수
-
스크립트
등록할 사용자 스크립트의 목록을 포함합니다.
-
콜백
함수 선택사항
callback
매개변수는 다음과 같습니다.() => void
반환 값
-
Promise<void>
프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
unregister()
chrome.userScripts.unregister(
filter?: UserScriptFilter,
callback?: function,
)
이 확장 프로그램에 대해 동적으로 등록된 모든 사용자 스크립트를 등록 취소합니다.
매개변수
-
filter
UserScriptFilter 선택사항
지정된 경우 이 메서드는 일치하는 사용자 스크립트만 등록 취소합니다.
-
콜백
함수 선택사항
callback
매개변수는 다음과 같습니다.() => void
반환 값
-
Promise<void>
프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
update()
chrome.userScripts.update(
scripts: RegisteredUserScript[],
callback?: function,
)
이 확장 프로그램의 사용자 스크립트를 하나 이상 업데이트합니다.
매개변수
-
스크립트
업데이트할 사용자 스크립트의 목록을 포함합니다. 기존 스크립트에 대한 속성은 이 객체에 지정된 경우에만 업데이트됩니다. 스크립트 파싱/파일 유효성 검사 중에 오류가 발생하거나 지정된 ID가 완전히 등록된 스크립트와 일치하지 않는 경우 ���크립트가 업데이트되지 않습니다.
-
콜백
함수 선택사항
callback
매개변수는 다음과 같습니다.() => void
반환 값
-
Promise<void>
프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.