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

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.

Manifest

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

"devtools_page"

Ejecuta el 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 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 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 campo code como 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

        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

  • callback

    la 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 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 propiedad navigator.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

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

    la función

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

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