Описание
Используйте API chrome.devtools.inspectedWindow для взаимодействия с проверяемым окном: получите идентификатор вкладки для проверяемой страницы, выполните код в контексте проверяемого окна, перезагрузите страницу или получите список ресурсов на странице.
Для получения общего представления об использовании API инструментов разработчика см. раздел «Краткое описание API инструментов разработчика».
Свойство tabId предоставляет идентификатор вкладки, который можно использовать при вызове API chrome.tabs.* . Однако обратите внимание, что API chrome.tabs.* не доступен на страницах расширений инструментов разработчика из соображений безопасности — вам потребуется передать идентификатор вкладки на фоновую страницу и вызывать функции API chrome.tabs.* оттуда.
Метод reload может использоваться для перезагрузки проверяемой страницы. Кроме того, вызывающая сторона может указать переопределение для строки пользовательского агента, скрипт, который будет внедрен на раннем этапе загрузки страницы, или параметр для принудительной перезагрузки кэшированных ресурсов.
Используйте вызов метода getResources и событие onResourceContent для получения списка ресурсов (документов, таблиц стилей, скриптов, изображений и т. д.) на проверяемой странице. Методы getContent и setContent класса Resource , а также событие onResourceContentCommitted могут использоваться для поддержки изменения содержимого ресурсов, например, внешним редактором.
Манифест
Выполните код в проверяемом окне.
Метод 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 из репозитория 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
- ошибка
объект необязательный
Если содержимое ресурса было успешно задано, значение устанавливается как undefined; в противном случае отображается сообщение об ошибке.
Характеристики
tabId
Идентификатор проверяемой вкладки. Этот идентификатор может использоваться с API chrome.tabs.*.
Тип
число
Методы
eval()
chrome.devtools.inspectedWindow.eval(
expression: string,
options?: object,
callback?: function,
): void
Функция eval вычисляет выражение JavaScript в контексте основного фрейма проверяемой страницы. Выражение должно возвращать объект, соответствующий стандарту JSON, в противном случае будет выброшено исключение. Функция eval может сообщать либо об ошибке на стороне DevTools, либо об исключении JavaScript, возникшем во время вычисления. В любом случае параметр result функции обратного вызова undefined . В случае ошибки на стороне DevTools параметр isException не равен null, и для него устанавливается значение isError равным true, а code — коду ошибки. В случае ошибки JavaScript isException устанавливается равным true, а value — строковому значению выброшенного объекта.
Параметры
- выражение
нить
Выражение для оценки.
- параметры
объект необязательный
Параметр options может содержать один или несколько параметров.
- frameURL
строка необязательный
Если указано, выражение вычисляется в iframe, URL которого совпадает с указанным. По умолчанию выражение вычисляется в верхнем фрейме проверяемой страницы.
- scriptExecutionContext
строка необязательный
Chrome 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
Получает список ресурсов с проверяемой страницы.
Параметры
reload()
chrome.devtools.inspectedWindow.reload(
reloadOptions?: object,
): void
Перезагружает проверяемую страницу.
Параметры
- reloadOptions
объект необязательный
- ignoreCache
логический необязательный
Если значение равно true, загрузчик будет обходить кэш для всех проверяемых ресурсов страницы, загруженных до срабатывания события
load. Эффект аналогичен нажатию Ctrl+Shift+R в проверяемом окне или в окне инструментов разработчика. - внедрённый скрипт
строка необязательный
Если указано иное, скрипт будет внедрен в каждый фрейм проверяемой страницы сразу после загрузки, до внедрения каких-либо скриптов этого фрейма. Скрипт не будет внедрен после последующих перезагрузок — например, если пользователь нажмет Ctrl+R.
- userAgent
строка необязательный
If specified, the string will override the value of the
User-AgentHTTP header that's sent while loading the resources of the inspected page. The string will also override the value of thenavigator.userAgentproperty that's returned to any scripts that are running within the inspected page.
События
onResourceAdded
chrome.devtools.inspectedWindow.onResourceAdded.addListener(
callback: function,
)
Событие срабатывает при добавлении нового ресурса на проверяемую страницу.
Параметры
- перезвонить
функция
Параметр
callbackвыглядит следующим образом:(resource: Resource) => void
- ресурс
onResourceContentCommitted
chrome.devtools.inspectedWindow.onResourceContentCommitted.addListener(
callback: function,
)
Срабатывает при сохранении новой версии ресурса (например, когда пользователь сохраняет отредактированную версию ресурса в инструментах разработчика).