chrome.devtools.inspectedWindow

Descripción

Usa la API de chrome.devtools.inspectedWindow para interactuar con la ventana inspeccionada: obtén el ID de la 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 obtén la lista de recursos dentro de la página.

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

La propiedad tabId proporciona el identificador de la pestaña que puedes usar con las llamadas a la API de chrome.tabs.*. Sin embargo, ten en cuenta que la API de chrome.tabs.* no se expone a las páginas de extensión de 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í.

Se puede usar el método reload para volver a cargar la página inspeccionada. Además, la persona que llama puede especificar una anulación para la cadena del agente de usuario, una secuencia de comandos que se insertará al principio 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, se pueden usar para admitir la modificación del contenido del recurso, por ejemplo, mediante un editor externo.

Manifiesto

Se deben declarar las siguientes claves en el manifiesto para usar esta API.

"devtools_page"

Ejecuta 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 forma inadecuada. 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 se requiera acceso 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. El contexto de ejecución está controlado por la página inspeccionada. 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 que se ejecutan 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 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 marco 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 de contenido de la extensión. (Equivalente a especificar el origen web propio de la extensión como el 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 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 devtools desde el 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

    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 (posiblemente codificado).

      • encoding

        string

        Está vacío si el contenido no está codificado. De lo contrario, se muestra 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

      string

      Contenido nuevo del recurso. Actualmente, solo se admiten recursos con el tipo de texto.

    • commit

      booleano

      Es verdadero si el usuario terminó de editar el recurso y se debe conservar el contenido nuevo del recurso. Es falso si se trata de un cambio menor que se envía mientras 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 configuró correctamente. De lo contrario, se describe el error.

Propiedades

tabId

El ID de la pestaña que se está inspeccionando. Este ID se puede usar con chrome.tabs.* de Compute Engine o Google Cloud CLI.

Tipo

número

Métodos

eval()

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

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 del lado de DevTools 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 DevTools, el isException parámetro 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 en verdadero y value se establece en el valor de cadena del objeto arrojado.

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+

      Evalúa la expresión en el contexto de una secuencia de comandos de contenido de una extensión que coincida 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 llama, siempre que la secuencia de comandos de contenido ya esté insertada en la página inspeccionada. De lo contrario, la expresión no se evalúa y se invoca la devolución de llamada con el parámetro de excepción establecido en un objeto que tiene el campo isError establecido en verdadero y el campo code establecido en E_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

        string

        Se establece si el error se produjo en el lado de DevTools antes de que se evalúe la expresión.

      • descripción

        string

        Se establece si el error se produjo en el lado de DevTools antes de que se evalúe la expresión.

      • detalles

        cualquiera[]

        Se establece si el error se produjo en el lado de DevTools 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

        booleano

        Se establece si el error se produjo en el lado de DevTools antes de que se evalúe la expresión.

      • isException

        booleano

        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,
): void

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,
): void

Vuelve a cargar la página inspeccionada.

Parámetros

  • reloadOptions

    objeto opcional

    • ignoreCache

      booleano opcional

      Cuando es verdadero, el cargador omite la caché para todos los recursos de la página inspeccionada que se cargan 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

      string opcional

      Si se especifica, la secuencia de comandos se insertará en cada marco de la página inspeccionada inmediatamente después de la carga, 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

      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 ejecute 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., 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