browser.devtools.inspectedWindow

Opis

Użyj interfejsu API chrome.devtools.inspectedWindow, aby wejść 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 podaje identyfikator karty, którego możesz używać z wywołaniami interfejsu API browser.tabs.*. Jednak ze względów bezpieczeństwa interfejs API browser.tabs.* nie jest dostępny na stronach rozszerzeń narzędzi dla programistów – musisz przekazać identyfikator karty do strony działającej w tle i wywołać funkcje interfejsu API browser.tabs.* z tego miejsca.

Do ponownego załadowania sprawdzanej strony można użyć metody reload. Dodatkowo wywołujący może określić zastąpienie ciągu klienta użytkownika, skrypt, który zostanie wstrzyknięty na początku 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 zawartości zasobu, na przykład przez zewnętrzny edytor.

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 używana we właściwym kontekście, i niebezpieczna, gdy jest używana niewłaściwie. 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 stan JavaScriptu w sprawdzanym oknie jest dostępny dla kodu. Użyj tej metody, gdy wymagany jest dostęp do stanu JavaScriptu sprawdzanej strony.
  • Kontekst wykonywania ocenianego kodu obejmuje interfejs API konsoli Narzędzi dla programistów. Kod może na przykład używać inspect i $0.
  • Oceniany 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 JavaScriptu i acykliczne odwołania do innych obiektów JSON). Zachowaj szczególną ostrożność podczas przetwarzania danych otrzymanych ze sprawdzanej strony – kontekst wykonywania jest zasadniczo kontrolowany przez sprawdzaną stronę. Szkodliwa strona może wpływać na dane zwracane do rozszerzenia.

Pamiętaj, że strona może zawierać wiele różnych kontekstów wykonywania kodu JavaScript. Każda ramka ma własny kontekst oraz dodatkowy kontekst dla każdego rozszerzenia, które ma skrypty treści działające w tej ramce.

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

Metoda eval przyjmuje opcjonalny drugi argument, którego możesz użyć do określenia kontekstu, w którym kod jest oceniany. Ten obiekt options może zawierać co najmniej 1 z tych kluczy:

frameURL
Służy do określania ramki innej niż ramka główna sprawdzanej strony.
contextSecurityOrigin
Służy do wybierania kontekstu w określonej ramce zgodnie z jej origin strony.
useContentScriptContext
Jeśli ma wartość Prawda, skrypt jest wykonywany w tym samym kontekście co skrypty treści rozszerzenia. (Odpowiada to określeniu origin strony rozszerzenia jako źródła zabezpieczeń 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ę:

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

    unieważnienie,

    Pobiera zawartość zasobu.

    Funkcja getContent wygląda tak:

    () => {...}

    • returns

      Promise<object>

      Chrome 151 lub nowsza browser.* od Chrome 152

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

  • setContent

    unieważnienie,

    Ustawia zawartość zasobu.

    Funkcja setContent wygląda tak:

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

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

    • returns

      Promise<object>

      Chrome 151 lub nowsza browser.* od Chrome 152

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

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

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

Ocenia wyrażenie JavaScript w kontekście ramki głównej sprawdzanej strony. Wyrażenie musi zwracać obiekt zgodny z 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 to undefined. W przypadku błędu po stronie Narzędzi deweloperskich parametr isException nie ma wartości null, a parametr isError ma wartość true, natomiast parametr code ma wartość kodu błędu. W przypadku błędu JavaScriptu zmienna isException ma wartość „true”, a zmienna value ma wartość ciągu znaków zgłoszonego obiektu.

Parametry

  • wyrażenie

    tekst

    Wyrażenie do oceny.

  • Opcje

    object opcjonalny

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

    • frameURL

      ciąg znaków opcjonalny

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

    • scriptExecutionContext

      ciąg znaków opcjonalny

      Chrome 107 lub nowsza browser.* od Chrome 152

      Oceń wyrażenie w kontekście skryptu treści rozszerzenia, które pasuje do określonego źródła. Jeśli podasz parametr scriptExecutionContext, zastąpi on ustawienie „true” (prawda) parametru useContentScriptContext.

    • useContentScriptContext

      boolean opcjonalne

      Oceń wyrażenie w kontekście skryptu treści wywołującego rozszerzenia, pod warunkiem że skrypt treści został już wstrzyknięty na sprawdzaną stronę. Jeśli nie, wyrażenie nie jest oceniane, a wywołanie zwrotne jest wywoływane z parametrem wyjątku ustawionym na obiekt, który ma pole isError ustawione na wartość true, a pole code ustawione na wartość E_NOTFOUND.

Zwroty

  • Promise<object>

    Chrome 151 lub nowsza browser.* od Chrome 152

    Funkcja wywoływana po zakończeniu oceny.

getResources()

browser.devtools.inspectedWindow.getResources(): Promise<Resource[]>

Pobiera listę zasobów ze sprawdzonej strony.

Zwroty

  • Promise<Resource[]>

    Chrome 151 lub nowsza browser.* od Chrome 152

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

reload()

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

Ponownie wczytuje sprawdzaną stronę.

Parametry

  • reloadOptions

    object opcjonalny

    • ignoreCache

      boolean opcjonalne

      Jeśli ma wartość „true”, moduł ładujący będzie pomijać pamięć podręczną w przypadku wszystkich sprawdzonych zasobów strony wczytanych przed wywołaniem zdarzenia load. Efekt jest podobny do naciśnięcia Ctrl + Shift + R w sprawdzanym oknie lub w oknie Narzędzi dla programistów.

    • injectedScript

      ciąg znaków opcjonalny

      Jeśli podasz skrypt, zostanie on 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 – na przykład jeśli użytkownik naciśnie Ctrl+R.

    • userAgent

      ciąg znaków opcjonalny

      Jeśli podasz ciąg znaków, zastąpi on 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 zwracaną do skryptów uruchomionych na sprawdzanej stronie.

Wydarzenia

onResourceAdded

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

Uruchamiane, gdy do sprawdzanej strony zostanie dodany nowy zasób.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (resource: Resource) => void

onResourceContentCommitted

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

Uruchamiane, gdy zostanie zatwierdzona nowa wersja zasobu (np. użytkownik zapisze edytowaną wersję zasobu w Narzędziach dla programistów).

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

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