Descripción
Usa la API de chrome.devtools.inspectedWindow
para interactuar con la ventana inspeccionada: obtén el ID de pestaña de la página inspeccionada, evalúa el código en el contexto de la ventana inspeccionada, vuelve a cargar la página u obtén la lista de recursos dentro de ella.
Manifest
Usa chrome.devtools.inspectedWindow
para interactuar con la ventana inspeccionada: obtén el ID de pestaña de la página inspeccionada, evalúa el código en el contexto de una ventana inspeccionada, vuelve a cargar la página u obtén la lista de recursos dentro de ella.
Consulta el resumen de las APIs de Herramientas para desarrolladores para obtener una introducción general al uso de las APIs de Herramientas para desarrolladores.
Descripción general
La propiedad tabId
proporciona el identificador de pestaña que puedes usar con las llamadas a la API chrome.tabs.*
. Sin embargo, ten en cuenta que la API de chrome.tabs.*
no está expuesta a las páginas de extensiones de las Herramientas para desarrolladores debido a consideraciones de seguridad. Deberás pasar el ID de la pestaña a la página en segundo plano y, luego, invocar las funciones de la API de chrome.tabs.*
desde allí.
Puedes usar el método reload
para volver a cargar la página inspeccionada. Además, el llamador puede especificar
una anulación para la cadena de usuario-agente, una secuencia de comandos que se insertará con anticipación cuando se cargue la página o una
opción para forzar la recarga de los recursos almacenados en caché.
Usa la llamada getResources
y el evento onResourceContent
para obtener la lista de recursos (documentos, hojas de estilo, secuencias de comandos, imágenes, etc.) dentro de la página inspeccionada. Los métodos getContent
y setContent
de la clase Resource
, junto con el evento onResourceContentCommitted
, pueden usarse para admitir la modificación del contenido del recurso, por ejemplo, a través de un editor externo.
Cómo ejecutar código en la ventana inspeccionada
El método eval
permite que las extensiones ejecuten código JavaScript en el contexto de la página inspeccionada. Este método es potente cuando se usa en el contexto correcto y peligroso cuando se usa de manera inapropiada. Usa el método tabs.executeScript
, a menos que necesites la funcionalidad específica que proporciona el método eval
.
Estas son las principales diferencias entre los métodos eval
y tabs.executeScript
:
- El método
eval
no usa un mundo aislado para el código que se evalúa, por lo que el código puede acceder al estado de JavaScript de la ventana inspeccionada. Usa este método cuando sea necesario acceder al estado de JavaScript de la página inspeccionada. - El contexto de ejecución del código que se evalúa incluye la API de la consola de Herramientas para desarrolladores.
Por ejemplo, el código puede usar
inspect
y$0
. - El código evaluado puede mostrar un valor que se pasa a la devolución de llamada de la extensión. El valor que se muestra debe ser un objeto JSON válido (solo puede contener tipos primitivos de JavaScript y referencias acíclicas a otros objetos JSON). Ten mucho cuidado cuando proceses los datos recibidos de la página inspeccionada, ya que la página inspeccionada controla el contexto de ejecución; una página maliciosa puede afectar los datos que se muestran a la extensión.
Ten en cuenta que una página puede incluir varios contextos de ejecución de JavaScript diferentes. Cada marco tiene su propio contexto, además de un contexto adicional para cada extensión que tiene secuencias de comandos de contenido ejecutándose en ese marco.
De forma predeterminada, el método eval
se ejecuta en el contexto del marco principal de la página inspeccionada.
El método eval
incluye un segundo argumento opcional que puedes usar para especificar el contexto en el que se evalúa el código. Este objeto options puede contener una o más de las siguientes claves:
frameURL
- Se usa para especificar un marco que no sea el principal de la página inspeccionada.
contextSecurityOrigin
- Se usa para seleccionar un contexto dentro del marco especificado según su origen web.
useContentScriptContext
- Si es verdadero, ejecuta la secuencia de comandos en el mismo contexto que las secuencias de comandos del contenido de las extensiones. (equivalente a especificar el propio origen web de la extensión como origen de seguridad del contexto). Esto se puede usar para intercambiar datos con la secuencia de comandos de contenido.
Ejemplos
El siguiente código verifica la versión de jQuery que usó la página inspeccionada:
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);
}
}
);
Para probar esta API, instala los ejemplos de la API de Herramientas para desarrolladores del repositorio chrome-extension-samples.
Tipos
Resource
Un recurso dentro de la página inspeccionada, como un documento, una secuencia de comandos o una imagen.
Propiedades
-
url
cadena
La URL del recurso.
-
getContent
void
Obtiene el contenido del recurso.
La función
getContent
se ve de la siguiente manera:(callback: function) => {...}
-
callback
la función
El parámetro
callback
se ve de la siguiente manera:(content: string, encoding: string) => void
-
contenido
cadena
Contenido del recurso (posiblemente codificado).
-
encoding
cadena
Estará vacío si el contenido no está codificado. De lo contrario, se mostrará el nombre de la codificación. Actualmente, solo se admite Base64.
-
-
-
setContent
void
Establece el contenido del recurso.
La función
setContent
se ve de la siguiente manera:(content: string, commit: boolean, callback?: function) => {...}
-
contenido
cadena
Nuevo contenido del recurso. Por el momento, solo se admiten recursos con el tipo de texto.
-
commit
boolean
Es verdadero si el usuario terminó de editar el recurso y el contenido nuevo del recurso debe conservarse. Es falso si se trata de un cambio menor enviado en curso de la edición del recurso por parte del usuario.
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(error?: object) => void
-
error
objeto opcional
Se establece como no definido si el contenido del recurso se configuró correctamente; de lo contrario, describe el error.
-
-
Propiedades
tabId
El ID de la pestaña que se inspecciona. Este ID puede usarse con chrome.tabs.* API.
Tipo
número
Métodos
eval()
chrome.devtools.inspectedWindow.eval(
expression: string,
options?: object,
callback?: function,
)
Evalúa una expresión de JavaScript en el contexto del marco principal de la página inspeccionada. La expresión debe evaluarse como un objeto compatible con JSON; de lo contrario, se arrojará una excepción. La función eval puede informar un error del lado de Herramientas para desarrolladores o una excepción de JavaScript que se produce durante la evaluación. En cualquier caso, el parámetro result
de la devolución de llamada es undefined
. En el caso de un error del lado de las Herramientas para desarrolladores, el parámetro isException
no es nulo y tiene isError
establecido como verdadero y code
establecido en un código de error. En el caso de un error de JavaScript, se establece isException
como verdadero y value
en el valor de cadena del objeto arrojado.
Parámetros
-
expresión
cadena
Una expresión para evaluar.
-
Opciones
objeto opcional
El parámetro options puede contener una o más opciones.
-
frameURL
cadena opcional
Si se especifica, la expresión se evalúa en el iframe cuya URL coincide con la especificada. De forma predeterminada, la expresión se evalúa en el marco superior de la página inspeccionada.
-
scriptExecutionContext
cadena opcional
Chrome 107 y versiones posterioresEvalúa la expresión en el contexto de una secuencia de comandos de contenido de una extensión que coincide con el origen especificado. Si se proporciona, scriptExecutionContext anula la configuración “true” en useContentScriptContext.
-
useContentScriptContext
booleano opcional
Evalúa la expresión en el contexto de la secuencia de comandos de contenido de la extensión que realiza la llamada, siempre que la secuencia de comandos de contenido ya esté insertada en la página inspeccionada. De lo contrario, no se evalúa la expresión y se invoca la devolución de llamada con el parámetro de excepción establecido en un objeto que tiene establecido el campo
isError
como verdadero y el campocode
comoE_NOTFOUND
.
-
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(result: object, exceptionInfo: object) => void
-
resultado
objeto
El resultado de la evaluación.
-
exceptionInfo
objeto
Un objeto que proporciona detalles si se produjo una excepción mientras se evaluaba la expresión.
-
código
cadena
Establece si el error ocurrió en las Herramientas para desarrolladores antes de que se evalúe la expresión.
-
descripción
cadena
Establece si el error ocurrió en las Herramientas para desarrolladores antes de que se evalúe la expresión.
-
detalles
cualquiera
Establece si el error ocurrió en las Herramientas para desarrolladores antes de que se evalúe la expresión. Contiene el array de los valores que se pueden sustituir en la cadena de descripción para proporcionar más información sobre la causa del error.
-
isError
boolean
Establece si el error ocurrió en las Herramientas para desarrolladores antes de que se evalúe la expresión.
-
isException
boolean
Se establece si el código evaluado genera una excepción no controlada.
-
value
cadena
Se establece si el código evaluado genera una excepción no controlada.
-
-
getResources()
chrome.devtools.inspectedWindow.getResources(
callback: function,
)
Recupera la lista de recursos de la página inspeccionada.
Parámetros
reload()
chrome.devtools.inspectedWindow.reload(
reloadOptions?: object,
)
Vuelve a cargar la página inspeccionada.
Parámetros
-
reloadOptions
objeto opcional
-
ignoreCache
booleano opcional
Si es verdadero, el cargador omitirá la caché de todos los recursos de la página inspeccionada que se carguen antes de que se active el evento
load
. El efecto es similar a presionar Ctrl + Mayúsculas + R en la ventana inspeccionada o dentro de la ventana de Herramientas para desarrolladores. -
injectedScript
cadena opcional
Si se especifica, la secuencia de comandos se insertará en cada marco de la página inspeccionada inmediatamente después de que se cargue, antes que cualquiera de las secuencias de comandos del marco. La secuencia de comandos no se insertará después de las recargas posteriores (por ejemplo, si el usuario presiona Ctrl+R).
-
userAgent
cadena opcional
Si se especifica, la cadena anulará el valor del encabezado HTTP
User-Agent
que se envía mientras se cargan los recursos de la página inspeccionada. La cadena también anulará el valor de la propiedadnavigator.userAgent
que se muestra en cualquier secuencia de comandos que se ejecute en la página inspeccionada.
-
Eventos
onResourceAdded
chrome.devtools.inspectedWindow.onResourceAdded.addListener(
callback: function,
)
Se activa cuando se agrega un recurso nuevo a la página inspeccionada.
Parámetros
-
callback
la función
El parámetro
callback
se ve de la siguiente manera:(resource: Resource) => void
-
recurso
-
onResourceContentCommitted
chrome.devtools.inspectedWindow.onResourceContentCommitted.addListener(
callback: function,
)
Se activa cuando se confirma una nueva revisión del recurso (p.ej., cuando el usuario guarda una versión editada del recurso en las Herramientas para desarrolladores).