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

Descripción general

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

El método reload se puede usar 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 inyectará al principio de la carga de 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étera) 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, por 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 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 devolver un valor que se pasa a la devolución de llamada de la extensión. El valor devuelto debe ser un objeto JSON válido (puede contener solo tipos primitivos de JavaScript y referencias acíclicas a otros objetos JSON). Ten especial cuidado al procesar los datos que recibes de la página inspeccionada, ya que el contexto de ejecución está controlado esencialmente por la página inspeccionada. 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, además de un contexto adicional para cada extensión que tenga 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 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 el script en el mismo contexto que los scripts de contenido de las extensiones. (Equivalente a especificar el origen web propio de la extensión como el origen de seguridad del contexto). 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 de chrome-extension-samples.

Tipos

Resource

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

Propiedades

  • url

    string

    Es la URL del recurso.

  • getContent

    void

    Promise

    Obtiene el contenido del recurso.

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

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

    • callback

      función opcional

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

      (response: object) => void

      • respuesta

        objeto

        Pendiente

        Objeto que contiene el contenido del recurso y su codificación.

        • contenido

          string

          Contenido del recurso (posiblemente codificado).

        • encoding

          string

          Estará vacío si el contenido no está codificado; de lo contrario, contendrá el nombre de la codificación. Actualmente, solo se admite base64.

    • muestra

      Promise<object>

      Pendiente

      Es una función que recibe contenido de recursos cuando se completa la solicitud.

      Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

  • setContent

    void

    Promise

    Establece el contenido del recurso.

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

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

    • contenido

      string

      Es el contenido nuevo del recurso. Actualmente, solo se admiten los 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, describe el error.

    • muestra

      Promise<object>

      Pendiente

      Función que se llama cuando se completa la solicitud.

      Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

Propiedades

tabId

Es el ID de la pestaña que se inspecciona. Este ID se puede usar con chrome.tabs.* de Compute Engine o Google Cloud CLI.

Tipo

número

Métodos

eval()

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

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 Herramientas para desarrolladores, el parámetro isException no es nulo y tiene isError establecido como verdadero y code establecido como 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 lanzado.

Parámetros

  • expresión

    string

    Es una expresión que se 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 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 parámetro de 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 se haya insertado 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 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: 

    (response: object) => void

    • respuesta

      objeto

      Pendiente

      Es el resultado de la evaluación y la información de excepción.

      • exceptionInfo

        objeto

        Es un objeto que proporciona detalles si se produjo una excepción durante la evaluación de la expresión.

        • código

          string

          Se establece si el error ocurrió del lado de Herramientas para desarrolladores antes de que se evaluara la expresión.

        • descripción

          string

          Se establece si el error ocurrió del lado de Herramientas para desarrolladores antes de que se evaluara la expresión.

        • detalles

          cualquiera[]

          Se establece si el error ocurrió del lado de 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

          booleano

          Se establece si el error ocurrió del lado de Herramientas para desarrolladores antes de que se evaluara 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.

      • resultado

        objeto

        Es el resultado de la evaluación.

Muestra

  • Promise<object>

    Pendiente

    Es una función que se llama cuando se completa la evaluación.

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

getResources()

Promise 
chrome.devtools.inspectedWindow.getResources(
  callback?: function,
): Promise<Resource[]>

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

Parámetros

  • callback

    función opcional

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

    (resources: Resource[]) => void

    • recursos

      Resource[]

      Son los recursos dentro de la página.

Muestra

  • Promise<Resource[]>

    Pendiente

    Es una función que recibe la lista de recursos cuando se completa la solicitud.

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

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 omitirá la caché para 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 la carga, antes de cualquier secuencia de comandos del marco. El script 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 propiedad navigator.userAgent que se devuelve a 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

    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 Herramientas para desarrolladores).

Parámetros

  • callback

    función

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

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