chrome.devtools.inspectedWindow

Описание

Используйте API chrome.devtools.inspectedWindow для взаимодействия с проверяемым окном: получите идентификатор вкладки для проверяемой страницы, оцените код в контексте проверяемого окна, перезагрузите страницу или получите список ресурсов на странице.

Общие сведения об использовании API инструментов инструментов разработчика см. в обзоре API-интерфейсов DevTools .

Свойство tabId предоставляет идентификатор вкладки, который можно использовать с вызовами API chrome.tabs.* . Однако обратите внимание, что API chrome.tabs.* не доступен на страницах расширения инструментов разработчика из соображений безопасности — вам нужно будет передать идентификатор вкладки на фоновую страницу и вызвать функции API chrome.tabs.* оттуда.

Метод reload можно использовать для перезагрузки проверяемой страницы. Кроме того, вызывающая сторона может указать переопределение строки пользовательского агента, сценарий, который будет внедрен сразу после загрузки страницы, или опцию принудительной перезагрузки кэшированных ресурсов.

Используйте вызов getResources и событие onResourceContent , чтобы получить список ресурсов (документов, таблиц стилей, сценариев, изображений и т. д.) на проверяемой странице. Методы getContent и setContent класса Resource вместе с событием onResourceContentCommitted могут использоваться для поддержки изменения содержимого ресурса, например, внешним редактором.

Манифест

Для использования этого API в манифесте необходимо объявить следующие ключи.

"devtools_page"

Выполнить код в проверяемом окне

Метод eval предоставляет расширениям возможность выполнять код JavaScript в контексте проверяемой страницы. Этот метод эффективен при использовании в правильном контексте и опасен при неправильном использовании. Используйте метод tabs.executeScript если вам не нужны конкретные функции, предоставляемые методом eval .

Вот основные различия между методами eval и tabs.executeScript :

  • Метод eval не использует изолированный мир для оцениваемого кода, поэтому состояние JavaScript проверяемого окна доступно коду. Используйте этот метод, когда требуется доступ к состоянию JavaScript проверяемой страницы.
  • Контекст выполнения оцениваемого кода включает API консоли инструментов разработчика . Например, код может использовать inspect и $0 .
  • Оцененный код может возвращать значение, которое передается в обратный вызов расширения. Возвращаемое значение должно быть допустимым объектом JSON (оно может содержать только примитивные типы JavaScript и ациклические ссылки на другие объекты JSON). Соблюдайте особую осторожность при обработке данных, полученных с проверяемой страницы: контекст выполнения по сути контролируется проверяемой страницей; вредоносная страница может повлиять на данные, возвращаемые в расширение.

Обратите внимание, что страница может включать в себя несколько различных контекстов выполнения JavaScript. Каждый кадр имеет свой собственный контекст, а также дополнительный контекст для каждого расширения, в котором в этом кадре выполняются сценарии содержимого.

По умолчанию метод eval выполняется в контексте основного фрейма проверяемой страницы.

Метод eval принимает необязательный второй аргумент, который можно использовать для указания контекста, в котором оценивается код. Этот объект параметров может содержать один или несколько следующих ключей:

frameURL
Используйте, чтобы указать фрейм, отличный от основного фрейма проверяемой страницы.
contextSecurityOrigin
Используйте для выбора контекста внутри указанного фрейма в соответствии с его веб-происхождением .
useContentScriptContext
Если это правда, выполните сценарий в том же контексте, что и сценарии содержимого расширений. (Эквивалентно указанию собственного веб-источника расширения в качестве источника контекстной безопасности.) Это можно использовать для обмена данными со сценарием содержимого.

Примеры

Следующий код проверяет версию 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, установите примеры API devtools из репозитория chrome-extension-samples .

Типы

Resource

Ресурс на проверяемой странице, например документ, скрипт или изображение.

Характеристики

  • URL

    нить

    URL-адрес ресурса.

  • получить контент

    пустота

    Получает содержимое ресурса.

    Функция getContent выглядит так: 

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

    • перезвонить

      функция

      Параметр callback выглядит так: 

      (content: string, encoding: string) => void

      • содержание

        нить

        Содержимое ресурса (возможно, закодированное).

      • кодирование

        нить

        Пусто, если содержимое не закодировано, в противном случае — имя кодировки. В настоящее время поддерживается только base64.

  • setContent

    пустота

    Устанавливает содержимое ресурса.

    Функция setContent выглядит так: 

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

    • содержание

      нить

      Новое содержание ресурса. В настоящее время поддерживаются только ресурсы текстового типа.

    • совершить

      логическое значение

      Значение true, если пользователь завершил редактирование ресурса и новое содержимое ресурса должно сохраниться; false, если это незначительное изменение, отправленное в процессе редактирования пользователем ресурса.

    • перезвонить

      функция необязательна

      Параметр callback выглядит так: 

      (error?: object) => void

      • ошибка

        объект необязательный

        Устанавливается в неопределенное значение, если содержимое ресурса было установлено успешно; иначе описывает ошибку.

Характеристики

tabId

Идентификатор проверяемой вкладки. Этот идентификатор можно использовать с API chrome.tabs.*.

Тип

число

Методы

eval()

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

Оценивает выражение JavaScript в контексте основного фрейма проверяемой страницы. Выражение должно возвращать JSON-совместимый объект, в противном случае будет выдано исключение. Функция eval может сообщать либо об ошибке на стороне DevTools, либо об исключении JavaScript, возникающем во время оценки. В любом случае параметр result обратного вызова undefined . В случае ошибки на стороне DevTools параметр isException имеет ненулевое значение, для isError установлено значение true, а для code установлен код ошибки. В случае ошибки JavaScript isException устанавливается значение true, а value устанавливается строковое значение выброшенного объекта.

Параметры

  • выражение

    нить

    Выражение для оценки.

  • параметры

    объект необязательный

    Параметр options может содержать один или несколько параметров.

    • фреймURL

      строка необязательна

      Если указано, выражение оценивается в iframe, URL-адрес которого соответствует указанному. По умолчанию выражение оценивается в верхнем фрейме проверяемой страницы.

    • scriptExecutionContext

      строка необязательна

      Хром 107+

      Оцените выражение в контексте сценария содержимого расширения, соответствующего указанному источнику. Если задано, scriptExecutionContext переопределяет значение true для useContentScriptContext.

    • useContentScriptContext

      логическое значение необязательно

      Оцените выражение в контексте сценария содержимого вызывающего расширения при условии, что сценарий содержимого уже внедрен на проверяемую страницу. В противном случае выражение не оценивается, и обратный вызов вызывается с параметром исключения, установленным для объекта, у которого для поля isError установлено значение true, а для поля code установлено значение E_NOTFOUND .

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    (result: object, exceptionInfo: object) => void

    • результат

      объект

      Результат оценки.

    • исключениеИнформация

      объект

      Объект, предоставляющий подробную информацию, если при вычислении выражения возникло исключение.

      • код

        нить

        Установите, если ошибка произошла на стороне DevTools до вычисления выражения.

      • описание

        нить

        Установите, если ошибка произошла на стороне DevTools до вычисления выражения.

      • подробности

        любой[]

        Устанавливается, если ошибка произошла на стороне DevTools до оценки выражения. Содержит массив значений, которые можно подставить в строку описания, чтобы предоставить дополнительную информацию о причине ошибки.

      • isError

        логическое значение

        Установите, если ошибка произошла на стороне DevTools до вычисления выражения.

      • isException

        логическое значение

        Установите, если оцененный код создает необработанное исключение.

      • ценить

        нить

        Установите, если оцененный код создает необработанное исключение.

getResources()

chrome.devtools.inspectedWindow.getResources(
  callback: function,
): void

Получает список ресурсов с проверяемой страницы.

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

    (resources: Resource[]) => void

    • ресурсы

      Ресурс []

      Ресурсы на странице.

reload()

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

Перезагружает проверенную страницу.

Параметры

  • перезагрузитьОпции

    объект необязательный

    • игнорировать кэш

      логическое значение необязательно

      Если установлено значение true, загрузчик будет обходить кеш для всех проверяемых ресурсов страницы, загруженных до запуска события load . Эффект аналогичен нажатию Ctrl+Shift+R в проверяемом окне или в окне инструментов разработчика.

    • введенный скрипт

      строка необязательна

      Если указано, сценарий будет внедрен в каждый кадр проверяемой страницы сразу после загрузки, перед любым из сценариев фрейма. Сценарий не будет внедрен после последующих перезагрузок, например, если пользователь нажмет Ctrl+R.

    • пользовательский агент

      строка необязательна

      Если указано, строка будет переопределять значение HTTP-заголовка User-Agent , отправленного при загрузке ресурсов проверяемой страницы. Эта строка также переопределит значение свойства navigator.userAgent , которое возвращается всем сценариям, выполняющимся на проверяемой странице.

События

onResourceAdded

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

Запускается, когда на проверяемую страницу добавляется новый ресурс.

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

    (resource: Resource) => void

onResourceContentCommitted

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

Запускается, когда фиксируется новая версия ресурса (например, пользователь сохраняет отредактированную версию ресурса в Инструментах разработчика).

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

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