chrome.devtools.inspectedWindow

Opis

Użyj interfejsu chrome.devtools.inspectedWindow API, aby wchodzić w interakcję ze sprawdzanym oknem: pobierać identyfikator karty sprawdzanej strony, oceniać kod w kontekście sprawdzanego okna, ponownie wczytywać stronę lub pobierać listę zasobów na stronie.

Ogólne informacje o korzystaniu 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 chrome.tabs.* API. Pamiętaj jednak, że interfejs chrome.tabs.* API nie jest udostępniany stronom rozszerzeń Narzędzi dla deweloperów ze względów bezpieczeństwa. Musisz przekazać identyfikator karty na stronę w tle i wywołać funkcje interfejsu chrome.tabs.* API z tej strony.

Metody reload można użyć do ponownego wczytania sprawdzanej strony. Dodatkowo wywołujący może określić zastąpienie ciągu user-agent, 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 oraz zdarzenie onResourceContentCommitted mogą służyć do obsługi modyfikacji zawartości zasobu, np. przez edytor zewnętrzny.

Plik manifestu

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

"devtools_page"

Wykonywanie kodu w sprawdzanym oknie

Metoda eval umożliwia rozszerzeniom wykonywanie kodu JavaScript w kontekście sprawdzanej strony. Ta metoda jest przydatna, gdy jest używana w odpowiednim kontekście, ale niebezpieczna, gdy jest używana nieprawidłowo. 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 izolowanego świata do 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 dla deweloperów. Kod może na przykład używać funkcji 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 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 JavaScript. Każda ramka ma swój 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 głównej ramki 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
Użyj, aby określić ramkę inną niż główna ramka sprawdzanej strony.
contextSecurityOrigin
Użyj, aby wybrać kontekst w określonej ramce według 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 origin strony rozszerzenia jako pochodzenia 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ę:

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 dla deweloperów 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

    void

    Pobiera zawartość zasobu.

    Funkcja getContent wygląda tak: 

    () => {...}

    • returns

      Promise<object>

      Oczekuje

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

  • setContent

    void

    Ustawia zawartość zasobu.

    Funkcja setContent wygląda tak: 

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

    • treść

      ciąg znaków

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

    • zatwierdź

      Wartość logiczna

      Wartość true, jeśli użytkownik skończył edytować zasób i nowa zawartość zasobu powinna zostać zachowana. Wartość false, jeśli jest to drobna zmiana wysłana w trakcie edytowania zasobu przez użytkownika.

    • returns

      Promise<object>

      Oczekuje

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

Właściwości

tabId

Identyfikator sprawdzanej karty. Tego identyfikatora można używać w chrome.tabs.* API.

Typ

liczba

Metody

eval()

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

Ocenia wyrażenie JavaScript w kontekście głównej ramki sprawdzanej strony. Wyrażenie musi być oceniane jako obiekt zgodny z JSON, w przeciwnym razie zostanie zgłoszony wyjątek. Funkcja eval może zgłosić błąd po stronie Narzędzi dla deweloperów 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 dla deweloperów parametr isException ma wartość niezerową, a parametr isError ma wartość true, a parametr code ma wartość kodu błędu. W przypadku błędu JavaScript parametr isException ma wartość true, a parametr value ma 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ślony, wyrażenie jest oceniane w elemencie iframe, którego adres URL pasuje do określonego adresu URL. Domyślnie wyrażenie jest oceniane w górnej ramce sprawdzanej strony.

    • scriptExecutionContext

      ciąg znaków opcjonalny

      Chrome 107+

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

    • useContentScriptContext

      wartość logiczna opcjonalna

      Oceń 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 oceniane, a wywołanie zwrotne jest wywoływane z parametrem wyjątku ustawionym na obiekt, który ma pole isError ustawione na true, a pole code ustawione na E_NOTFOUND.

Zwroty

  • Promise<object>

    Oczekuje

    Funkcja wywoływana po zakończeniu oceny.

getResources()

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

Pobiera listę zasobów ze sprawdzanej strony.

Zwroty

  • Promise<Resource[]>

    Oczekuje

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

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ą wszystkich zasobów sprawdzanej 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 deweloperów.

    • injectedScript

      ciąg znaków opcjonalny

      Jeśli jest określony, skrypt zostanie wstrzyknięty do każdej ramki sprawdzanej strony natychmiast po wczytaniu, przed jakimkolwiek skryptem ramki. Skrypt nie zostanie wstrzyknięty po kolejnych ponownych wczytaniach, np. jeśli użytkownik naciśnie Ctrl+R.

    • userAgent

      ciąg znaków opcjonalny

      Jeśli jest określony, ciąg znaków 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 zwracanej 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 dla deweloperów).

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak: 

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

    • zasób

      Zasób

    • treść

      ciąg znaków