browser.devtools.inspectedWindow

Описание

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

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

Свойство tabId предоставляет идентификатор вкладки, который можно использовать с вызовами API browser.tabs.*. Однако API browser.tabs.* не предоставляется страницам расширений инструментов разработчика из соображений безопасности. Вам потребуется передать идентификатор вкладки фоновой странице и вызвать функции API browser.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 принимает необязательный второй аргумент, который можно использовать для указания контекста, в котором оценивается код. Объект options может содержать один или несколько следующих ключей:

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

Примеры

Следующий код проверяет версию jQuery, используемую на странице:

browser.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 инструментов разработчика из хранилища chrome-extension-samples.

Типы

Resource

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

Свойства

  • url

    string

    URL ресурса.

  • getContent

    void

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

    Функция getContent выглядит следующим образом: 

    () => {...}

    • Возвращает

      Promise<object>

      Chrome 151 и более поздних версий browser.* начиная с Chrome 152

      Функция, которая получает контент ресурса после выполнения запроса.

  • setContent

    void

    Задает содержимое ресурса.

    Функция setContent выглядит следующим образом: 

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

    • контент

      string

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

    • зафиксировать изменения

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

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

    • Возвращает

      Promise<object>

      Chrome 151 и более поздних версий browser.* начиная с Chrome 152

      Функция, вызываемая по завершении запроса.

Свойства

tabId

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

Тип

число

Методы

eval()

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

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

Параметры

  • выражение

    string

    Выражение, которое нужно вычислить.

  • Параметры

    Объект (необязательно)

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

    • frameURL

      Строка (необязательно)

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

    • scriptExecutionContext

      Строка (необязательно)

      Chrome 107+ browser.* начиная с Chrome 152

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

    • useContentScriptContext

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

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

Возвраты

  • Promise<object>

    Chrome 151 и более поздних версий browser.* начиная с Chrome 152

    Функция, вызываемая по завершении оценки.

getResources()

browser.devtools.inspectedWindow.getResources(): Promise<Resource[]>

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

Возвраты

  • Promise<Resource[]>

    Chrome 151 и более поздних версий browser.* начиная с Chrome 152

    Функция, которая получает список ресурсов после выполнения запроса.

reload()

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

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

Параметры

  • reloadOptions

    Объект (необязательно)

    • ignoreCache

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

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

    • injectedScript

      Строка (необязательно)

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

    • userAgent

      Строка (необязательно)

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

События

onResourceAdded

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

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

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

    (resource: Resource) => void

onResourceContentCommitted

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

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

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

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