chrome.devtools.inspectedWindow

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, o bien obtén la lista de recursos dentro de la página.

Manifiesto

Para usar esta API, se deben declarar las siguientes claves en el manifiesto.

"devtools_page"

Usa chrome.devtools.inspectedWindow para interactuar con la ventana inspeccionada: obtén el ID de la pestaña de la página inspeccionada, evaluar el código en el contexto de una ventana inspeccionada, volver a cargar la página u obtener la lista de recursos dentro de la página.

Consulta el resumen de las APIs de Herramientas para desarrolladores para ver una introducción general al uso de las APIs de las Herramientas para desarrolladores.

Descripción general

La propiedad tabId proporciona el identificador de pestaña que puedes usar con chrome.tabs.*. Llamadas a la API. Sin embargo, ten en cuenta que la API de chrome.tabs.* no está expuesta a las Herramientas para desarrolladores. páginas de extensiones debido a consideraciones de seguridad, deberás pasar el ID de la pestaña a segundo plano e invoca las funciones de la API de chrome.tabs.* desde allí.

Se puede 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 del usuario-agente, una secuencia de comandos que se insertará al principio de la carga de la página 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 operadores getContent y Los métodos setContent de la clase Resource junto con el evento onResourceContentCommitted pueden usarse para facilitar 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 adecuado y peligroso cuando se usa. de forma 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 JavaScript de la ventana inspeccionada sea accesible para el código. Usa este método cuando accedas a Se requiere el 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 (puede contener solo tipos primitivos de JavaScript y referencias a otros objetos JSON). Presta especial atención al procesar los datos recibidos desde la página inspeccionada (básicamente, la página inspeccionada controla el contexto de ejecución) pañal una página maliciosa puede afectar los datos que se devuelven 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, más un contexto adicional para cada extensión que tenga secuencias de comandos de contenido que se ejecuten en ese marco.

De forma predeterminada, se ejecuta el método eval en el contexto del marco principal de la página inspeccionada.

El método eval toma 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 el valor es "true", ejecuta la secuencia de comandos en el mismo contexto que las secuencias de comandos del contenido de las extensiones. (Equivalente a y especifica el origen web de la extensión como el origen de la seguridad del contexto). Esto se puede usar para para intercambiar datos con la secuencia de comandos de contenido.

Ejemplos

Con el siguiente código, se verifica la versión de jQuery que usa 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 de chrome-extension-samples en un repositorio de confianza.

Tipos

Resource

Un recurso dentro de la página inspeccionada, como un documento, una secuencia de comandos o una imagen.

Propiedades

  • url

    string

    La URL del recurso.

  • getContent

    void

    Obtiene el contenido del recurso.

    La función getContent se ve de la siguiente manera: 

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

    • callback

      función

      El parámetro callback se ve de la siguiente manera: 

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

      • contenido

        string

        Contenido del recurso (potencialmente codificado).

      • encoding

        string

        Estará vacío si el contenido no está codificado. De lo contrario, se codificará el nombre. Actualmente, solo se admite Base64.

  • setContent

    void

    Configura el contenido del recurso.

    La función setContent se ve de la siguiente manera: 

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

    • contenido

      string

      Contenido nuevo 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 nuevo contenido del recurso debe conservarse. false si se trata de un cambio menor que se envía cuando el usuario edita el recurso

    • callback

      función opcional

      El parámetro callback se ve de la siguiente manera: 

      (error?: object) => void

      • error

        objeto opcional

        Se establece como indefinido si el contenido del recurso se estableció correctamente. describe el error de otro modo.

Propiedades

tabId

El ID de la pestaña que se inspecciona. Este ID se puede utilizar con chrome.tabs.* Recommender.

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 arroja una excepción. La función eval puede informar un error 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 en verdadero y code establecido en un código de error. En el caso de un error de JavaScript, isException se establece como verdadero y value se establece en el valor de cadena del objeto que se arroja.

Parámetros

  • expresión

    string

    Una expresión para evaluar.

  • opciones

    objeto opcional

    El parámetro options puede contener una o más opciones.

    • frameURL

      string 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

      string opcional

      Chrome 107 y versiones posteriores

      Evalú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 el valor "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 de 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 configurado en un objeto que tiene el campo isError configurado como verdadero y el campo code configurado como E_NOTFOUND.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

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

    • resultado

      objeto

      Es el resultado de la evaluación.

    • exceptionInfo

      objeto

      Un objeto que proporciona detalles si se produjo una excepción mientras se evalúa la expresión.

      • código

        string

        Establece si el error ocurrió en Herramientas para desarrolladores antes de evaluar la expresión.

      • descripción

        string

        Establece si el error ocurrió en Herramientas para desarrolladores antes de evaluar la expresión.

      • detalles

        cualquiera

        Establece si el error ocurrió en Herramientas para desarrolladores antes de evaluar 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 Herramientas para desarrolladores antes de evaluar la expresión.

      • isException

        boolean

        Se establece si el código evaluado produce una excepción no controlada.

      • valor

        string

        Se establece si el código evaluado produce una excepción no controlada.

getResources()

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

Recupera la lista de recursos de la página inspeccionada.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (resources: Resource[]) => void

    • recursos

      Recurso

      Los recursos dentro de la página.

reload()

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

Vuelve a cargar la página inspeccionada.

Parámetros

  • reloadOptions

    objeto opcional

    • ignoreCache

      booleano opcional

      Si el valor es verdadero, el cargador omitirá la caché de todos los recursos de la página inspeccionados que se hayan cargado antes de que se active el evento load. El efecto es similar al de presionar Ctrl + Mayúsculas + R en la ventana inspeccionada o dentro de la ventana de las Herramientas para desarrolladores.

    • injectedScript

      string 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 de 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

      string 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 propiedad navigator.userAgent que se muestra a cualquier secuencia de comandos que se ejecuta dentro de 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

    función

    El parámetro callback se ve de la siguiente manera: 

    (resource: Resource) => void

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).

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

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