chrome.devtools.inspectedWindow

Opis

Użyj interfejsu chrome.devtools.inspectedWindow API, aby wchodzić w interakcję 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.

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ć funkcje interfejsu chrome.tabs.* API z tej strony.

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 User-Agent, skrypt, 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 wraz ze zdarzeniem onResourceContentCommitted mogą być używane do obsługi modyfikacji treści zasobu, np. przez edytor zewnętrzny.

Plik manifestu

Aby używać tego interfejsu API, musisz zadeklarować te klucze w pliku manifestu.

"devtools_page"

Wykonaj kod w sprawdzanym oknie

Metoda eval umożliwia rozszerzeniom wykonywanie kodu JavaScript w kontekście sprawdzanej strony. Ta metoda jest skuteczna, gdy jest stosowana we właściwym kontekście, a niebezpieczna, gdy jest używana 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 JavaScript sprawdzanego okna. 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ć znaczników inspect i $0.
  • Wykonany kod może zwrócić wartość, która zostanie przekazana 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 danych otrzymanych ze sprawdzanej strony zachowaj szczególną ostrożność – kontekst wykonania jest zasadniczo 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, za pomocą którego możesz określić kontekst, 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 wartość to prawda, skrypt jest wykonywany w tym samym kontekście co skrypty treści rozszerzeń. (Odpowiednik określenia własnego origin strony rozszerzenia jako pochodzenia zabezpieczenia kontekstu). Można go używać do wymiany danych ze skryptem treści.

Przykłady

Poniższy kod sprawdza wersję jQuery używaną przez sprawdzaną stronę:

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

    ciąg znaków

    Adres URL zasobu.

  • getContent

    pusty

    Pobiera zawartość zasobu.

    Funkcja getContent wygląda tak:

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

    • callback

      funkcja

      Parametr callback wygląda tak:

      (content: string, encoding: string) => void

      • treść

        ciąg znaków

        Treść zasobu (potencjalnie zakodowana).

      • kodowanie,

        ciąg znaków

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

  • setContent

    pusty

    Ustawia zawartość zasobu.

    Funkcja setContent wygląda tak:

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

    • treść

      ciąg znaków

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

    • zatwierdź

      Wartość logiczna

      Wartość „prawda”, jeśli użytkownik zakończył edytowanie zasobu i nowa treść zasobu powinna zostać zachowana. Wartość „fałsz”, jeśli jest to drobna 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.

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()

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

Ocenia wyrażenie JavaScript w kontekście głównej ramki 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 JavaScript, 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 wartość isException jest ustawiona na „true” (prawda), a wartość value jest ustawiona na wartość ciągu znaków wyrzuconego obiektu.

Parametry

  • wyrażenie

    ciąg znaków

    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 elemencie iframe, którego adres URL jest zgodny z określonym adresem. 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 ona ustawienie „true” w przypadku parametru useContentScriptContext.

    • useContentScriptContext

      wartość logiczna opcjonalna

      Ocenia wyrażenie w kontekście skryptu treści wywołującego rozszerzenia, pod warunkiem że skrypt treści jest już wstrzyknięty na sprawdzaną stronę. 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:

    (result: object, exceptionInfo: object) => void

    • wynik

      obiekt

      Wynik oceny.

    • exceptionInfo

      obiekt

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

      • kod

        ciąg znaków

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

      • opis

        ciąg znaków

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

      • szczegóły

        dowolny[]

        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ść

        ciąg znaków

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

getResources()

chrome.devtools.inspectedWindow.getResources(
  callback: function,
): void

Pobiera listę zasobów ze sprawdzanej strony.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (resources: Resource[]) => void

reload()

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

Ponownie ładuje 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 sprawdzonych zasobów strony wczytanych przed wywołaniem zdarzenia load. Działa to podobnie jak naciśnięcie Ctrl+Shift+R w sprawdzanym oknie lub w oknie Narzędzi deweloperskich.

    • injectedScript

      ciąg znaków opcjonalny

      Jeśli zostanie to określone, skrypt zostanie wstrzyknięty do każdej ramki sprawdzanej strony natychmiast po jej załadowaniu, 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 ciąg znaków zostanie określony, zastąpi on wartość nagłówka HTTP User-Agent wysyłanego podczas ładowania 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

    • zasób

      Zasób

    • treść

      ciąg znaków