매니페스트 - 콘텐츠 스크립트

"content_scripts" 키는 특정 URL 패턴과 일치하는 페이지가 열릴 때마다 사용할 정적으로 로드된 JavaScript 또는 CSS 파일을 지정합니다. 확장 프로그램은 프로그래매틱 방식으로 콘텐츠 스크립트를 삽입할 수도 있습니다. 자세한 내용은 스크립트 삽입을 참고하세요.

매니페스트

"content_scripts"에 지원되는 키는 다음과 같습니다. "matches" 키와 "js" 또는 "css"만 필요합니다.

manifest.json

{
 "name": "My extension",
 ...
 "content_scripts": [
   {
     "matches": ["https://*.example.com/*"],
     "css": ["my-styles.css"],
     "js": ["content-script.js"],
     "exclude_matches": ["*://*/*foo*"],
     "include_globs": ["*example.com/???s/*"],
     "exclude_globs": ["*bar*"],     
     "all_frames": false,
     "match_origin_as_fallback": false,
     "match_about_blank": false,
     "run_at": "document_idle",
     "world": "ISOLATED",
   }
 ],
 ...
}

파일

각 파일에는 확장 프로그램의 루트 디렉터리에 있는 리소스의 상대 경로가 포함되어야 합니다. 선행 슬래시(/)는 자동으로 잘립니다. "run_at" 키는 각 파일이 삽입되는 시점을 지정합니다.

"css" - 배열
선택사항. CSS 파일 경로의 배열로, 이 배열의 순서대로 DOM 구성 또는 페이지 렌더링이 발생하기 전에 삽입됩니다.
"js" - 배열
선택사항. CSS 파일이 삽입된 후 이 배열에 표시되는 순서대로 삽입되는 JavaScript 파일 경로의 배열입니다. 배열의 각 문자열은 확장 프로그램의 루트 디렉터리에 있는 리소스의 상대 경로여야 합니다. 선행 슬래시('/')는 자동으로 잘립니다.

URL 일치

"matches" 속성만 필요합니다. 그런 다음 "exclude_matches", "include_globs", "exclude_globs"를 사용하여 코드를 삽입할 URL을 맞춤설정할 수 있습니다. "matches" 키는 경고를 트리거합니다.

"matches" - 배열
필수사항. 콘텐츠 스크립트를 삽입할 URL 패턴을 지정합니다. 구문은 일치 패턴을 참고하세요.
"exclude_matches" - 배열
선택사항. 콘텐츠 스크립트를 삽입할 URL 패턴을 제외합니다. 구문은 일치 패턴을 참고하세요.
"include_globs" - 배열
선택사항. 일치 후 적용되어 이 glob과도 일치하는 URL만 포함합니다. @include Greasemonkey 키워드를 에뮬레이션하기 위한 것입니다.
"exclude_globs" - 배열
선택사항. 일치 후 적용되어 이 glob과 일치하는 URL을 제외합니다. @exclude Greasemonkey 키워드를 에뮬레이션하기 위한 것입니다.

Glob URL은 '와일드 카드' * 및 물음표가 포함된 URL입니다. 와일드 카드 *는 빈 문자열을 포함하여 모든 길이의 문자열과 일치하며, 물음표 ?는 모든 단일 문자와 일치합니다.

콘텐츠 스크립트는 다음과 같은 경우 페이지에 삽입됩니다.

  • URL이 "matches" 및 "include_globs" 패턴과 일치합니다.
  • URL이 "exclude_matches" 또는 "exclude_globs" 패턴과 일치하지 않습니다.

Glob 및 URL 일치 예시

"include_globs"

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "include_globs": ["https://???.example.com/foo/*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
매치
https://www.example.com/foo/bar
https://the.example.com/foo/
일치하지 않음
https://my.example.com/foo/bar
https://example.com/foo/*
https://www.example.com/foo

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "include_globs": ["*example.com/???s/*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
매치
https://www.example.com/arts/index.html
https://www.example.com/jobs/index.html
일치하지 않음
https://www.example.com/sports/index.html
https://www.example.com/music/index.html

"exclude_globs"

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "exclude_globs": ["*science*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
매치
https://history.example.com
https://.example.com/music
일치하지 않음
https://science.example.com
https://www.example.com/science

고급 맞춤설정 예시

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "exclude_matches": ["*://*/*business*"],
      "include_globs": ["*example.com/???s/*"],
      "exclude_globs": ["*science*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
매치
https://www.example.com/arts/index.html
https://.example.com/jobs/index.html
일치하지 않음
https://science.example.com
https://www.example.com/jobs/business
https://www.example.com/science

프레임

"all_frames" 키는 지정된 URL의 요건과 일치하는 모든 프레임에 콘텐츠 스크립트를 삽입해야 하는지 지정합니다. false로 설정하면 최상위 프레임에만 삽입됩니다. "match_about_blank"와 함께 사용하여 about:blank 프레임에 삽입할 수 있습니다.

data:, blob:, filesystem:와 같은 다른 프레임에 삽입하려면 "match_origin_as_fallback"를 true로 설정합니다. 자세한 내용은 관련 프레임에 삽입을 참고하세요.

"all_frames" 불리언
선택사항. 기본값은 false이며, 이는 최상위 프레임만 일치함을 의미합니다. true로 설정하면 프레임이 탭의 최상위 프레임이 아니더라도 모든 프레임에 삽입됩니다. 각 프레임은 URL의 요건을 충족하는지 독립적으로 확인되며, URL의 요건을 충족하지 않으면 하위 프레임에 삽입되지 않습니다.
"match_about_blank" - 불리언
선택사항. 기본값은 false입니다. 상위 URL이 "matches"에 선언된 패턴 중 하나와 일치하는 about:blank 프레임에 스크립트를 삽입해야 하는지 여부입니다.
"match_origin_as_fallback" - 불리언
선택사항. 기본값은 false입니다. 일치하는 출처에서 생성되었지만 URL 또는 출처가 패턴과 직접 일치하지 않을 수 있는 프레임에 스크립트를 삽입해야 하는지 여부입니다. 여기에는 about:, data:, blob:, filesystem:와 같은 다양한 스키마가 있는 프레임이 포함됩니다.

런타임 및 실행 환경

기본적으로 콘텐츠 스크립트는 문서와 모든 리소스의 로드가 완료되면 삽입되며, 페이지나 다른 확장 프로그램에서 액세스할 수 없는 비공개 격리 실행 환경에 상주합니다. 다음 키에서 이러한 기본값을 변경할 수 있습니다.

"run_at" - document_start | document_end | document_idle
선택사항. 스크립트를 페이지에 삽입해야 하는 시점을 지정합니다. 이는 Document.readyState의 로드 상태에 해당합니다.
  • "document_start": DOM이 아직 로드 중입니다.
  • "document_end": 페이지의 리소스가 아직 로드 중입니다.
  • "document_idle": DOM 및 리소스 로드가 완료되었습니다. 이는 기본값입니다.
"world" - ISOLATED | MAIN
선택사항. 스크립트가 실행될 JavaScript 환경입니다. 기본값은 "ISOLATED"이며, 이는 콘텐츠 스크립트에 고유한 실행 환경입니다. "MAIN" 환경을 선택하면 스크립트가 호스트 페이지의 JavaScript와 실행 환경을 공유합니다. 자세한 내용은 격리된 환경에서 작업을 참고하세요.

예

모든 페이지에서 실행 튜토리얼을 참고하여 매니페스트에 콘텐츠 스크립트를 삽입하는 확장 프로그램을 빌드하세요.