chrome.devtools.inspectedWindow

refresh date: 2026-09-25 robots: noindex

Opis

Użyj interfejsu chrome.devtools.inspectedWindow API, aby wchodzić w interakcje ze sprawdzanym oknem: uzyskać identyfikator karty sprawdzanej strony, ocenić kod w kontekście sprawdzanego okna, ponownie załadować stronę lub uzyskać listę zasobów na stronie.

Plik manifestu

Aby korzystać z tego interfejsu API, musisz zadeklarować w pliku manifestu te klucze:

"devtools_page"

Użyj chrome.devtools.inspectedWindow, aby wchodzić w interakcje ze sprawdzanym oknem: uzyskać identyfikator karty sprawdzanej strony, ocenić kod w kontekście sprawdzanego okna, ponownie załadować stronę lub uzyskać listę zasobów na stronie.

Ogólne wprowadzenie do korzystania z interfejsów API Narzędzi deweloperskich znajdziesz w podsumowaniu interfejsów API Narzędzi deweloperskich.

Przegląd

Właściwość tabId zawiera identyfikator karty, którego możesz używać w wywołaniach interfejsu API chrome.tabs.*. Pamiętaj jednak, że ze względów bezpieczeństwa interfejs chrome.tabs.* API nie jest udostępniany stronom rozszerzenia Narzędzia deweloperskie. Musisz przekazać identyfikator karty do strony w tle i wywołać z niej funkcje interfejsu chrome.tabs.* API.

Do ponownego załadowania sprawdzanej strony można użyć metody reload. Dodatkowo osoba wywołująca może określić zastąpienie ciągu agenta użytkownika, skryptu, który zostanie wstrzyknięty na wczesnym etapie wczytywania strony, lub opcję wymuszenia ponownego wczytania zasobów z pamięci podręcznej.

Użyj wywołania getResources i zdarzenia onResourceContent, aby uzyskać listę zasobów (dokumentów, arkuszy stylów, skryptów, obrazów itp.) na sprawdzanej stronie. Metody getContent i setContent klasy Resource oraz zdarzenie onResourceContentCommitted mogą być używane do obsługi modyfikacji treści zasobu, np. przez edytor zewnętrzny.

Wykonywanie kodu w oknie inspekcji

Metoda eval umożliwia rozszerzeniom wykonywanie kodu JavaScript w kontekście sprawdzanej strony. Ta metoda jest skuteczna, gdy jest używana we właściwym kontekście, a niebezpieczna, gdy jest stosowana nieodpowiednio. Używaj metody tabs.executeScript, chyba że potrzebujesz konkretnej funkcji, którą zapewnia metoda eval.

Oto główne różnice między metodami eval i tabs.executeScript:

  • Metoda eval nie używa odizolowanego środowiska dla ocenianego kodu, więc kod ma dostęp do stanu JavaScriptu w sprawdzanym oknie. Użyj tej metody, gdy potrzebujesz dostępu do stanu JavaScript sprawdzanej strony.
  • Kontekst wykonania ocenianego kodu obejmuje interfejs API konsoli Narzędzi deweloperskich. Na przykład kod może używać wartości inspect i $0.
  • Oceniony kod może zwrócić wartość, która jest przekazywana do wywołania zwrotnego rozszerzenia. Zwracana wartość musi być prawidłowym obiektem JSON (może zawierać tylko podstawowe typy JavaScript i acykliczne odwołania do innych obiektów JSON). Podczas przetwarzania otrzymanych danych zachowaj szczególną ostrożność. Kontekst wykonania jest w zasadzie kontrolowany przez sprawdzaną stronę. Złośliwa strona może wpływać na dane zwracane do rozszerzenia.

Pamiętaj, że strona może zawierać wiele różnych kontekstów wykonania JavaScriptu. Każda ramka ma własny kontekst, a także dodatkowy kontekst dla każdego rozszerzenia, które ma w niej uruchomione skrypty treści.

Domyślnie metoda eval jest wykonywana w kontekście ramki głównej sprawdzanej strony.

Metoda eval przyjmuje opcjonalny drugi argument, który umożliwia określenie kontekstu, w którym kod jest oceniany. Obiekt options może zawierać co najmniej 1 z tych kluczy:

frameURL
Użyj, aby określić ramkę inną niż ramka główna sprawdzanej strony.
contextSecurityOrigin
Użyj, aby wybrać kontekst w określonej ramce zgodnie z jej origin strony.
useContentScriptContext
Jeśli ma wartość „true”, skrypt jest wykonywany w tym samym kontekście co skrypty treści rozszerzeń. (Odpowiednik określenia własnego źródła internetowego rozszerzenia jako źródła bezpieczeństwa kontekstu). Można go używać do wymiany danych ze skryptem treści.

Przykłady

Poniższy kod sprawdza wersję jQuery używaną na sprawdzanej stronie:

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);
    }
  }
);

Aby wypróbować ten interfejs API, zainstaluj przykłady interfejsu API narzędzi deweloperskich z repozytorium chrome-extension-samples.

Typy

Resource

Zasób na sprawdzanej stronie, np. dokument, skrypt lub obraz.

Właściwości

  • URL

    tekst

    Adres URL zasobu.

  • getContent

    pusty

    Obietnica

    Pobiera zawartość zasobu.

    Funkcja getContent wygląda tak:

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

    • callback

      funkcja opcjonalna

      Parametr callback wygląda tak:

      (response: object) => void

      • odpowiedź

        obiekt

        Chrome 151 lub nowsza

        Obiekt zawierający treść zasobu i jej kodowanie.

        • treść

          tekst

          Treść zasobu (potencjalnie zakodowana).

        • kodowanie,

          tekst

          Puste, jeśli treść nie jest zakodowana, w przeciwnym razie nazwa kodowania. Obecnie obsługiwany jest tylko format base64.

    • returns

      Promise<object>

      Chrome 151 lub nowsza

      Funkcja, która otrzymuje treść zasobu po zakończeniu żądania.

      Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

  • setContent

    pusty

    Obietnica

    Ustawia zawartość zasobu.

    Funkcja setContent wygląda tak:

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

    • treść

      tekst

      Nowa treść zasobu. Obecnie obsługiwane są tylko zasoby typu tekstowego.

    • zatwierdź

      wartość logiczna

      Wartość „true”, jeśli użytkownik zakończył edytowanie zasobu i nowa treść zasobu powinna zostać zachowana; wartość „false”, jeśli jest to niewielka zmiana wysłana w trakcie edytowania zasobu przez użytkownika.

    • callback

      funkcja opcjonalna

      Parametr callback wygląda tak:

      (error?: object) => void

      • błąd

        obiekt opcjonalny

        Ustaw na wartość undefined, jeśli zawartość zasobu została ustawiona prawidłowo. W przeciwnym razie opisuje błąd.

    • returns

      Promise<object>

      Chrome 151 lub nowsza

      Funkcja wywoływana po zakończeniu żądania.

      Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

Właściwości

tabId

Identyfikator sprawdzanej karty. Ten identyfikator może być używany z chrome.tabs.* a także przy użyciu Google Cloud CLI lub Compute Engine API.

Typ

liczba

Metody

eval()

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

Ocenia wyrażenie JavaScript w kontekście ramki głównej sprawdzanej strony. Wyrażenie musi zwracać obiekt zgodny z formatem JSON, w przeciwnym razie zostanie zgłoszony wyjątek. Funkcja eval może zgłosić błąd po stronie Narzędzi deweloperskich lub wyjątek JavaScriptu, który wystąpi podczas oceny. W obu przypadkach parametr result wywołania zwrotnego ma wartość undefined. W przypadku błędu po stronie Narzędzi deweloperskich parametr isException nie ma wartości null, a parametr isError ma wartość true, a parametr code ma wartość kodu błędu. W przypadku błędu JavaScript zmienna isException przyjmuje wartość „true”, a zmienna value przyjmuje wartość ciągu wyrzuconego obiektu.

Parametry

  • wyrażenie

    tekst

    Wyrażenie do oceny.

  • Opcje

    obiekt opcjonalny

    Parametr options może zawierać co najmniej 1 opcję.

    • frameURL

      ciąg znaków opcjonalny

      Jeśli jest określone, wyrażenie jest obliczane w ramce iframe, której adres URL pasuje do podanego adresu. Domyślnie wyrażenie jest obliczane w górnej ramce sprawdzanej strony.

    • scriptExecutionContext

      ciąg znaków opcjonalny

      Chrome 107 lub nowsza

      Ocenia wyrażenie w kontekście skryptu treści rozszerzenia, które pasuje do określonego pochodzenia. Jeśli podano wartość, scriptExecutionContext zastępuje ustawienie „true” w przypadku parametru useContentScriptContext.

    • useContentScriptContext

      wartość logiczna opcjonalna

      Ocenia wyrażenie w kontekście skryptu treści rozszerzenia wywołującego, pod warunkiem że skrypt treści jest już wstrzyknięty do sprawdzanej strony. W przeciwnym razie wyrażenie nie jest obliczane, a wywołanie zwrotne jest wywoływane z parametrem wyjątku ustawionym na obiekt, w którym pole isError ma wartość true, a pole code ma wartość E_NOTFOUND.

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (response: object) => void

    • odpowiedź

      obiekt

      Chrome 151 lub nowsza

      Wynik oceny i informacje o wyjątkach.

      • exceptionInfo

        obiekt

        Obiekt zawierający szczegóły, jeśli podczas obliczania wyrażenia wystąpił wyjątek.

        • kod

          tekst

          Określa, czy błąd wystąpił po stronie Narzędzi deweloperskich przed obliczeniem wyrażenia.

        • opis

          tekst

          Określa, czy błąd wystąpił po stronie Narzędzi deweloperskich przed obliczeniem wyrażenia.

        • szczegóły

          any[]

          Określa, czy błąd wystąpił po stronie Narzędzi deweloperskich przed obliczeniem wyrażenia. Zawiera tablicę wartości, które można wstawić do ciągu opisu, aby podać więcej informacji o przyczynie błędu.

        • isError

          wartość logiczna

          Określa, czy błąd wystąpił po stronie Narzędzi deweloperskich przed obliczeniem wyrażenia.

        • isException

          wartość logiczna

          Określa, czy oceniany kod generuje nieobsłużony wyjątek.

        • wartość

          tekst

          Określa, czy oceniany kod generuje nieobsłużony wyjątek.

      • wynik

        obiekt

        Wynik oceny.

Zwroty

  • Promise<object>

    Chrome 151 lub nowsza

    Funkcja wywoływana po zakończeniu oceny.

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

getResources()

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

Pobiera listę zasobów ze sprawdzanej strony.

Parametry

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (resources: Resource[]) => void

    • zasoby

      Zasób[]

      zasoby na stronie,

Zwroty

  • Promise<Resource[]>

    Chrome 151 lub nowsza

    Funkcja, która otrzymuje listę zasobów po zakończeniu żądania.

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

reload()

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

Ponownie wczytuje sprawdzaną stronę.

Parametry

  • reloadOptions

    obiekt opcjonalny

    • ignoreCache

      wartość logiczna opcjonalna

      Jeśli ma wartość true, moduł wczytujący pominie pamięć podręczną w przypadku wszystkich zasobów sprawdzanej strony wczytanych przed wywołaniem zdarzenia load. Działa to podobnie jak naciśnięcie klawiszy Ctrl+Shift+R w sprawdzanym oknie lub w oknie Narzędzi deweloperskich.

    • injectedScript

      ciąg znaków opcjonalny

      Jeśli to określisz, skrypt zostanie wstrzyknięty do każdej ramki sprawdzanej strony natychmiast po jej wczytaniu, przed wszystkimi skryptami ramki. Skrypt nie zostanie wstrzyknięty po kolejnych przeładowaniach, np. gdy użytkownik naciśnie Ctrl+R.

    • userAgent

      ciąg znaków opcjonalny

      Jeśli ten ciąg znaków zostanie określony, zastąpi wartość nagłówka HTTP User-Agent wysyłanego podczas wczytywania zasobów sprawdzanej strony. Ciąg znaków zastąpi też wartość właściwości navigator.userAgent, która jest zwracana do wszystkich skryptów działających na sprawdzanej stronie.

Wydarzenia

onResourceAdded

chrome.devtools.inspectedWindow.onResourceAdded.addListener(
  callback: function,
)

Wywoływane, gdy do sprawdzanej strony zostanie dodany nowy zasób.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (resource: Resource) => void

onResourceContentCommitted

chrome.devtools.inspectedWindow.onResourceContentCommitted.addListener(
  callback: function,
)

Wywoływane, gdy zostanie zatwierdzona nowa wersja zasobu (np. użytkownik zapisze edytowaną wersję zasobu w Narzędziach deweloperskich).

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

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