chrome.devtools.inspectedWindow

refresh date: 2026-09-25 robots: noindex

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 de la página.

Manifiesto

Las siguientes claves se deben declarar en el manifiesto para usar esta API.

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

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

Se puede usar el método reload para volver a cargar la página inspeccionada. Además, el emisor puede especificar una anulación para la cadena del usuario-agente, una secuencia de comandos que se insertará al principio de la carga de 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.

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 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 entorno 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 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, en esencia, 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 que se ejecuten 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 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 las extensiones. (Equivale a especificar el origen web 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 Herramientas para desarrolladores desde el repositorio 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

        Chrome 151 y versiones posteriores

        Es un objeto que contiene el contenido del recurso y su codificación.

        • contenido

          string

          Contenido del recurso (potencialmente codificado).

        • encoding

          string

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

    • muestra

      Promise<object>

      Chrome 151 y versiones posteriores

      Es una función que recibe el contenido del recurso 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. Por el momento, 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 enviado 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 estableció correctamente; de lo contrario, describe el error.

    • muestra

      Promise<object>

      Chrome 151 y versiones posteriores

      Es una función a la 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 está inspeccionando. Este ID se puede usar con chrome.tabs.* de REST.

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 las 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 en verdadero y value se establece en el valor de cadena del objeto arrojado.

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

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

      Chrome 151 y versiones posteriores

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

      • exceptionInfo

        objeto

        Es 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 las Herramientas para desarrolladores antes de que se evalúe la expresión.

        • descripción

          string

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

        • detalles

          any[]

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

          booleano

          Se establece si el error se produjo en el lado de las Herramientas para desarrolladores 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.

      • resultado

        objeto

        Es el resultado de la evaluación.

Muestra

  • Promise<object>

    Chrome 151 y versiones posteriores

    Es una función a la 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 que se encuentran dentro de la página.

Muestra

  • Promise<Resource[]>

    Chrome 151 y versiones posteriores

    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 cargaron antes de que se active el evento load. El efecto es similar a presionar Ctrl + Mayúsculas + R en la ventana inspeccionada o en 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 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 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 las Herramientas para desarrolladores).

Parámetros

  • callback

    función

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

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