chrome.userScripts

설명

userScripts API를 사용하여 사용자 스크립트 컨텍스트에서 사용자 스크립트를 실행합니다.

권한

userScripts

User Scripts API(chrome.userScripts)를 사용하려면 스크립트를 실행하려는 사이트의 manifest.json에 "userScripts" 권한을 추가하고 "host_permissions"를 추가합니다.

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

가용성

Chrome 120 이상 MV3 이상

개념 및 사용

사용자 스크립트는 웹페이지의 모양이나 동작을 수정하기 위해 웹페이지에 삽입되는 코드 스니펫입니다. 콘텐츠 스크립트 및 chrome.scripting API와 같은 다른 확장 프로그램 기능과 달리 User Scripts API를 사용하면 임의의 코드를 실행할 수 있습니다. 이 API는 확장 프로그램 패키지의 일부로 제공할 수 없는 사용자가 제공한 스크립트를 실행하는 확장 프로그램에 필요합니다.

확장 프로그램 사용자를 위한 개발자 모드

확장 프로그램 개발자는 Chrome 설치 시 이미 개발자 모드를 사용 설정합니다. 사용자 스크립트 확장 프로그램의 경우 사용자도 개발자 모드를 사용 설정해야 합니다. 다음은 자체 문서에 복사하여 붙여넣을 수 있는 안내입니다.

1. 새 탭에서 chrome://extensions를 입력하여 확장 프로그램 페이지로 이동합니다. (chrome:// URL은 설계상 연결할 수 없습니다.)

2. 개발자 모드 옆에 있는 전환 스위치를 클릭하여 개발자 모드를 사용 설정합니다.

   

   확장 프로그램 페이지 (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;
  }
}

격리된 세계에서 작업

사용자 스크립트와 콘텐츠 스크립트 모두 격리된 월드 또는 기본 월드에서 실행할 수 있습니다. 격리된 세계는 호스트 페이지나 다른 확장 프로그램에서 액세스할 수 없는 실행 환경입니다. 이렇게 하면 사용자 스크립트가 호스트 페이지나 다른 확장 프로그램의 사용자 및 콘텐츠 스크립트에 영향을 미치지 않고 JavaScript 환경을 변경할 수 있습니다. 반대로 사용자 스크립트 (및 콘텐츠 스크립트)는 호스트 페이지 또는 다른 확장 프로그램의 사용자 및 콘텐츠 스크립트에 표시되지 않습니다. 기본 세계에서 실행되는 스크립트는 호스트 페이지 및 기타 확장 프로그램에 액세스할 수 있으며 호스트 페이지 및 기타 확장 프로그램에 표시됩니다. 지구를 선택하려면 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 세계입니다.

열거형

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

'USER_SCRIPT'
사용자 스크립트에만 해당하며 페이지의 CSP에서 제외되는 실행 환경을 지정합니다.

RegisteredUserScript

속성

• allFrames

  불리언 선택사항

  이 값이 true이면 프레임이 탭에서 최상위 프레임이 아니더라도 모든 프레임에 삽입됩니다. 각 프레임은 URL 요구사항에 대해 개별적으로 확인됩니다. URL 요구사항이 충족되지 않으면 하위 프레임에 삽입되지 않습니다. 기본값은 false이며, 즉 최상위 프레임만 일치합니다.

• excludeGlobs

  string[] 선택사항

  이 사용자 스크립트가 삽입되지 않는 페이지의 와일드 카드 패턴을 지정합니다.

• excludeMatches

  string[] 선택사항

  이 사용자 스크립트가 삽입될 페이지를 제외합니다. 이러한 문자열의 문법에 관한 자세한 내용은 일치 패턴을 참고하세요.

• id

  문자열

  API 호출에 지정된 사용자 스크립트의 ID입니다. 이 속성은 생성된 스크립트 ID의 접두사로 예약되어 있으므로 '_'로 시작해서는 안 됩니다.

• includeGlobs

  string[] 선택사항

  이 사용자 스크립트가 삽입될 페이지의 와일드 카드 패턴을 지정합니다.

• js

  ScriptSource[] 선택사항

  일치하는 페이지에 삽입할 스크립트의 소스를 정의하는 ScriptSource 객체 목록입니다. 이 속성은 ${ref:register}에 지정해야 하며 지정된 경우 비어 있지 않은 배열이어야 합니다.

• 일치

  string[] 선택사항

  이 사용자 스크립트가 삽입될 페이지를 지정합니다. 이러한 문자열의 문법에 관한 자세한 내용은 일치 패턴을 참고하세요. 이 속성은 ${ref:register}에 지정해야 합니다.

• runAt

  RunAt 선택사항

  JavaScript 파일이 웹페이지에 삽입되는 시점을 지정합니다. 기본값은 document_idle입니다.

• 세계

  ExecutionWorld 선택사항

  스크립트를 실행할 JavaScript 실행 환경입니다. 기본값은 `USER_SCRIPT`입니다.

• worldId

  문자열 선택사항

  Chrome 133 이상

  실행할 사용자 스크립트 월드 ID를 지정합니다. 생략하면 스크립트가 기본 사용자 스크립트 세계에서 실행됩니다. world가 생략되었거나 USER_SCRIPT인 경우에만 유효합니다. 선행 밑줄 (_)이 있는 값은 예약되어 있습니다.

ScriptSource

속성

• 코드

  문자열 선택사항

  삽입할 JavaScript 코드가 포함된 문자열입니다. file 또는 code 중에서 정확히 하나만 지정해야 합니다.

• 파일

  문자열 선택사항

  확장 프로그램의 루트 디렉터리를 기준으로 삽입할 JavaScript 파일의 경로입니다. file 또는 code 중에서 정확히 하나만 지정해야 합니다.

UserScriptFilter

속성

• ids

  string[] 선택사항

  getScripts는 이 목록에 지정된 ID가 있는 스크립트만 반환합니다.

WorldProperties

속성

• CSP

  문자열 선택사항

  세계 csp를 지정합니다. 기본값은 `ISOLATED` 전 세계 csp입니다.

• 메시지

  불리언 선택사항

  메시지 API가 노출되는지 여부를 지정합니다. 기본값은 false입니다.

• worldId

  문자열 선택사항

  Chrome 133 이상

  업데이트할 특정 사용자 스크립트 월드의 ID를 지정합니다. 제공하지 않으면 기본 사용자 스크립트 월드의 속성을 업데이트합니다. 선행 밑줄 (_)이 있는 값은 예약되어 있습니다.

메서드

configureWorld()

Promise

chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

`USER_SCRIPT` 실행 환경을 구성합니다.

매개변수

• 속성

  WorldProperties

  사용자 스크립트 월드 구성을 포함합니다.

• callback

  함수 선택사항

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

  () => void

반환 값

• Promise<void>

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

getScripts()

Promise

chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

이 확장 프로그램에 대해 동적으로 등록된 모든 사용자 스크립트를 반환합니다.

매개변수

• filter

  UserScriptFilter 선택사항

  지정된 경우 이 메서드는 일치하는 사용자 스크립트만 반환합니다.

• callback

  함수 선택사항

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

  (scripts: RegisteredUserScript[]) => void

  • 스크립트

    RegisteredUserScript[]

반환 값

• Promise<RegisteredUserScript[]>

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

getWorldConfigurations()

Promise Chrome 133 이상

chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

등록된 모든 세계 구성을 검색합니다.

매개변수

• callback

  함수 선택사항

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

  (worlds: WorldProperties[]) => void

  • 세계

    WorldProperties[]

반환 값

• Promise<WorldProperties[]>

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

register()

Promise

chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

이 확장 프로그램에 하나 이상의 사용자 스크립트를 등록합니다.

매개변수

• 스크립트

  RegisteredUserScript[]

  등록할 사용자 스크립트 목록을 포함합니다.

• callback

  함수 선택사항

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

  () => void

반환 값

• Promise<void>

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

resetWorldConfiguration()

Promise Chrome 133 이상

chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

사용자 스크립트 월의 구성을 재설정합니다. 지정된 ID로 월드에 삽입하는 모든 스크립트는 기본 월드 구성을 사용합니다.

매개변수

• worldId

  문자열 선택사항

  재설정할 사용자 스크립트 월드의 ID입니다. 생략하면 기본 월드의 구성을 재설정합니다.

• callback

  함수 선택사항

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

  () => void

반환 값

• Promise<void>

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

unregister()

Promise

chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

이 확장 프로그램에 대해 동적으로 등록된 모든 사용자 스크립트를 등록 취소합니다.

매개변수

• filter

  UserScriptFilter 선택사항

  지정된 경우 이 메서드는 일치하는 사용자 스크립트만 등록 취소합니다.

• callback

  함수 선택사항

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

  () => void

반환 값

• Promise<void>

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

update()

Promise

chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

이 확장 프로그램의 사용자 스크립트를 하나 이상 업데이트합니다.

매개변수

• 스크립트

  RegisteredUserScript[]

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

• callback

  함수 선택사항

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

  () => void

반환 값

• Promise<void>

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