chrome.devtools.inspectedWindow

refresh date: 2026-09-25 robots: noindex

설명

chrome.devtools.inspectedWindow API를 사용하여 검사된 창과 상호작용합니다. 검사된 페이지의 탭 ID를 가져오고, 검사된 창의 컨텍스트에서 코드를 평가하고, 페이지를 새로고침하거나, 페이지 내 리소스 목록을 가져옵니다.

매니페스트

이 API를 사용하려면 매니페스트에 다음 키를 선언해야 합니다.

"devtools_page"

chrome.devtools.inspectedWindow를 사용하여 검사된 창과 상호작용합니다. 검사된 페이지의 탭 ID를 가져오거나, 검사된 창의 컨텍스트에서 코드를 평가하거나, 페이지를 새로고침하거나, 페이지 내 리소스 목록을 가져옵니다.

개발자 도구 API 사용에 관한 일반적인 소개는 DevTools API 요약을 참고하세요.

개요

tabId 속성은 chrome.tabs.* API 호출에 사용할 수 있는 탭 식별자를 제공합니다. 하지만 보안상의 이유로 chrome.tabs.* API는 개발자 도구 확장 프로그램 페이지에 노출되지 않습니다. 탭 ID를 백그라운드 페이지에 전달하고 여기에서 chrome.tabs.* API 함수를 호출해야 합니다.

reload 메서드를 사용하여 검사된 페이지를 새로고침할 수 있습니다. 또한 호출자는 사용자 에이전트 문자열의 재정의, 페이지 로드 시 초기에 삽입될 스크립트 또는 캐시된 리소스의 강제 새로고침 옵션을 지정할 수 있습니다.

getResources 호출 및 onResourceContent 이벤트를 사용하여 검사된 페이지 내의 리소스 목록(문서, 스타일시트, 스크립트, 이미지 등)을 가져옵니다. Resource 클래스의 getContent 및 setContent 메서드를 onResourceContentCommitted 이벤트와 함께 사용하여 외부 편집기 등으로 리소스 콘텐츠 수정을 지원할 수 있습니다.

검사된 창에서 코드 실행

eval 메서드를 사용하면 확장 프로그램이 검사된 페이지의 컨텍스트에서 JavaScript 코드를 실행할 수 있습니다. 이 메서드는 올바른 컨텍스트에서 사용하면 강력하지만 부적절하게 사용하면 위험합니다. eval 메서드가 제공하는 특정 기능이 필요하지 않은 경우 tabs.executeScript 메서드를 사용합니다.

eval 메서드와 tabs.executeScript 메서드의 주요 차이점은 다음과 같습니다.

  • eval 메서드는 평가 중인 코드에 격리된 환경을 사용하지 않으므로 검사된 창의 JavaScript 상태에 코드가 액세스할 수 있습니다. 검사된 페이지의 JavaScript 상태에 액세스해야 하는 경우 이 메서드를 사용합니다.
  • 평가 중인 코드의 실행 컨텍스트에는 개발자 도구 콘솔 API가 포함됩니다. 예를 들어 코드에서 inspect 및 $0를 사용할 수 있습니다.
  • 평가된 코드는 확장 프로그램 콜백에 전달되는 값을 반환할 수 있습니다. 반환된 값은 유효한 JSON 객체여야 합니다 (기본 JavaScript 유형과 다른 JSON 객체에 대한 비순환 참조만 포함할 수 있음). 검사된 페이지에서 수신된 데이터를 처리할 때는 각별히 주의하세요. 실행 컨텍스트는 기본적으로 검사된 페이지에 의해 제어됩니다. 악성 페이지는 확장 프로그램에 반환되는 데이터에 영향을 미칠 수 있습니다.

페이지에는 여러 자바스크립트 실행 컨텍스트가 포함될 수 있습니다. 각 프레임에는 자체 컨텍스트가 있으며, 해당 프레임에서 콘텐츠 스크립트가 실행되는 각 확장 프로그램에 대한 추가 컨텍스트가 있습니다.

기본적으로 eval 메서드는 검사된 페이지의 기본 프레임 컨텍스트에서 실행됩니다.

eval 메서드는 코드가 평가되는 컨텍스트를 지정하는 데 사용할 수 있는 선택적 두 번째 인수를 사용합니다. 이 options 객체에는 다음 키 중 하나 이상이 포함될 수 있습니다.

frameURL
검사된 페이지의 기본 프레임이 아닌 다른 프레임을 지정하는 데 사용합니다.
contextSecurityOrigin
웹 출처에 따라 지정된 프레임 내에서 컨텍스트를 선택하는 데 사용합니다.
useContentScriptContext
true인 경우 확장 프로그램의 콘텐츠 스크립트와 동일한 컨텍스트에서 스크립트를 실행합니다. 이는 확장 프로그램 자체의 웹 출처를 컨텍스트 보안 출처로 지정하는 것과 같습니다. 이는 콘텐츠 스크립트와 데이터를 교환하는 데 사용할 수 있습니다.

예

다음 코드는 검사된 페이지에서 사용하는 jQuery 버전을 확인합니다.

chrome.devtools.inspectedWindow.eval(
  "jQuery.fn.jquery",
  function(result, isException) {
    if (isException) {
      console.log("the page is not using jQuery");
    } else {
      console.log("The page is using jQuery v" + result);
    }
  }
);

이 API를 사용해 보려면 chrome-extension-samples 저장소에서 devtools API 예를 설치하세요.

유형

Resource

검사된 페이지 내의 리소스(예: 문서, 스크립트, 이미지)입니다.

속성

  • URL

    문자열

    리소스의 URL입니다.

  • getContent

    void

    Promise

    리소스의 콘텐츠를 가져옵니다.

    getContent 함수는 다음과 같습니다. 

    (callback?: function) => {...}

    • callback

      함수 선택사항

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

      (response: object) => void

      • 응답

        객체

        Chrome 151 이상

        리소스 콘텐츠와 인코딩이 포함된 객체입니다.

        • 콘텐츠

          문자열

          리소스의 콘텐츠입니다 (인코딩될 수 있음).

        • encoding

          문자열

          콘텐츠가 인코딩되지 않은 경우 비어 있고, 그렇지 않으면 인코딩 이름입니다. 현재는 base64만 지원됩니다.

    • returns

      <span class="notranslate">Promise<object></span>

      Chrome 151 이상

      요청이 완료되면 리소스 콘텐츠를 수신하는 함수입니다.

      프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

  • setContent

    void

    Promise

    리소스의 콘텐츠를 설정합니다.

    setContent 함수는 다음과 같습니다. 

    (content: string, commit: boolean, callback?: function) => {...}

    • 콘텐츠

      문자열

      리소스의 새 콘텐츠입니다. 현재 텍스트 유형의 리소스만 지원됩니다.

    • commit

      부울

      사용자가 리소스 수정을 완료했고 리소스의 새 콘텐츠를 유지해야 하는 경우 true이고, 사용자가 리소스를 수정하는 중에 전송된 사소한 변경사항인 경우 false입니다.

    • callback

      함수 선택사항

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

      (error?: object) => void

      • 오류

        객체 선택사항

        리소스 콘텐츠가 설정된 경우 정의되지 않음으로 설정되고, 그렇지 않으면 오류를 설명합니다.

    • returns

      <span class="notranslate">Promise<object></span>

      Chrome 151 이상

      요청 완료 시 호출되는 함수입니다.

      프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

속성

tabId

검사 중인 탭의 ID입니다. 이 ID는 chrome.tabs.*와 함께 사용할 수 있습니다. 사용해야 할 수도 있습니다

유형

숫자

메서드

eval()

Promise 
chrome.devtools.inspectedWindow.eval(
  expression: string,
  options?: object,
  callback?: function,
): Promise<object>

검사된 페이지의 기본 프레임 컨텍스트에서 JavaScript 표현식을 평가합니다. 표현식은 JSON 호환 객체로 평가되어야 합니다. 그렇지 않으면 예외가 발생합니다. eval 함수는 DevTools 측 오류 또는 평가 중에 발생하는 JavaScript 예외를 보고할 수 있습니다. 두 경우 모두 콜백의 result 매개변수는 undefined입니다. DevTools 측 오류의 경우 isException 매개변수가 null이 아니며 isError가 true로 설정되고 code가 오류 코드로 설정됩니다. 자바스크립트 오류가 발생하면 isException가 true로 설정되고 value가 발생한 객체의 문자열 값으로 설정됩니다.

매개변수

  • 표현식

    문자열

    평가할 표현식입니다.

  • 옵션

    객체 선택사항

    options 매개변수에는 하나 이상의 옵션이 포함될 수 있습니다.

    • frameURL

      문자열 선택사항

      지정된 경우 URL이 지정된 URL과 일치하는 iframe에서 표현식이 평가됩니다. 기본적으로 표현식은 검사된 페이지의 상단 프레임에서 평가됩니다.

    • scriptExecutionContext

      문자열 선택사항

      Chrome 107 이상

      지정된 출처와 일치하는 확장 프로그램의 콘텐츠 스크립트 컨텍스트에서 표현식을 평가합니다. 제공된 경우 scriptExecutionContext는 useContentScriptContext의 'true' 설정을 재정의합니다.

    • useContentScriptContext

      불리언 선택사항

      콘텐츠 스크립트가 이미 검사된 페이지에 삽입된 경우 호출 확장 프로그램의 콘텐츠 스크립트 컨텍스트에서 표현식을 평가합니다. 그렇지 않으면 표현식이 평가되지 않고 콜백이 호출되며, 이때 예외 매개변수는 isError 필드가 true로 설정되고 code 필드가 E_NOTFOUND로 설정된 객체로 설정됩니다.

  • callback

    함수 선택사항

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

    (response: object) => void

    • 응답

      객체

      Chrome 151 이상

      평가 및 예외 정보의 결과입니다.

      • exceptionInfo

        객체

        표현식을 평가하는 동안 예외가 발생한 경우 세부정보를 제공하는 객체입니다.

        • 코드

          문자열

          표현식이 평가되기 전에 DevTools 측에서 오류가 발생한 경우 설정됩니다.

        • 설명

          문자열

          표현식이 평가되기 전에 DevTools 측에서 오류가 발생한 경우 설정됩니다.

        • 세부정보

          any[]

          표현식이 평가되기 전에 DevTools 측에서 오류가 발생한 경우 설정되며, 오류 원인에 관한 자세한 정보를 제공하기 위해 설명 문자열로 대체될 수 있는 값의 배열을 포함합니다.

        • isError

          부울

          표현식이 평가되기 전에 DevTools 측에서 오류가 발생한 경우 설정됩니다.

        • isException

          부울

          평가된 코드에서 처리되지 않은 예외가 생성되는 경우 설정됩니다.

        • 값

          문자열

          평가된 코드에서 처리되지 않은 예외가 생성되는 경우 설정됩니다.

      • 결과

        객체

        평가 결과입니다.

반환 값

  • <span class="notranslate">Promise<object></span>

    Chrome 151 이상

    평가가 완료되면 호출되는 함수입니다.

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

getResources()

Promise 
chrome.devtools.inspectedWindow.getResources(
  callback?: function,
): Promise<Resource[]>

검사된 페이지에서 리소스 목록을 가져옵니다.

매개변수

  • callback

    함수 선택사항

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

    (resources: Resource[]) => void

    • 리소스

      리소스[]

      페이지 내 리소스입니다.

반환 값

  • 약속<리소스[]>

    Chrome 151 이상

    요청이 완료되면 리소스 목록을 수신하는 함수입니다.

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

reload()

chrome.devtools.inspectedWindow.reload(
  reloadOptions?: object,
): void

검사된 페이지를 새로고침합니다.

매개변수

  • reloadOptions

    객체 선택사항

    • ignoreCache

      불리언 선택사항

      true인 경우 로더는 load 이벤트가 실행되기 전에 로드된 모든 검사된 페이지 리소스의 캐시를 우회합니다. 이 효과는 검사된 창 또는 개발자 도구 창에서 Ctrl+Shift+R을 누르는 것과 유사합니다.

    • injectedScript

      문자열 선택사항

      지정된 경우 스크립트는 로드 시 프레임의 스크립트보다 먼저 검사된 페이지의 모든 프레임에 즉시 삽입됩니다. 사용자가 Ctrl+R을 누르는 등 이후에 새로고침하면 스크립트가 삽입되지 않습니다.

    • userAgent

      문자열 선택사항

      지정된 경우 문자열은 검사된 페이지의 리소스를 로드하는 동안 전송되는 User-Agent HTTP 헤더의 값을 재정의합니다. 또한 이 문자열은 검사된 페이지 내에서 실행되는 모든 스크립트에 반환되는 navigator.userAgent 속성 값을 재정의합니다.

이벤트

onResourceAdded

chrome.devtools.inspectedWindow.onResourceAdded.addListener(
  callback: function,
)

검사된 페이지에 새 리소스가 추가되면 실행됩니다.

매개변수

  • callback

    함수

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

    (resource: Resource) => void

onResourceContentCommitted

chrome.devtools.inspectedWindow.onResourceContentCommitted.addListener(
  callback: function,
)

리소스의 새 버전이 커밋될 때 실행됩니다 (예: 사용자가 개발자 도구에서 리소스의 수정된 버전을 저장하는 경우).

매개변수

  • callback

    함수

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

    (resource: Resource, content: string) => void