Opis
Interfejs API chrome.devtools.inspectedWindow
umożliwia interakcję ze sprawdzanym oknem: uzyskanie identyfikatora karty badanej strony, ocena kodu w kontekście sprawdzanego okna, ponowne załadowanie strony lub uzyskanie listy zasobów na stronie.
Plik manifestu
Aby można było używać tego interfejsu API, następujące klucze muszą być zadeklarowane w pliku manifestu.
"devtools_page"
Użyj polecenia chrome.devtools.inspectedWindow
, aby wejść w interakcję ze badanym oknem: uzyskać identyfikator karty badanej strony, ocenić kod w kontekście sprawdzanego okna, ponownie załadować stronę lub wyświetlić listę zasobów na stronie.
Zobacz podsumowanie interfejsów API DevTools, aby uzyskać ogólne informacje o korzystaniu z interfejsów API Narzędzi dla programistów.
Przegląd
Właściwość tabId
podaje identyfikator karty, którego możesz używać w wywołaniach interfejsu API chrome.tabs.*
. Pamiętaj jednak, że interfejs API chrome.tabs.*
nie jest widoczny na stronach rozszerzeń Narzędzi dla programistów ze względów bezpieczeństwa – trzeba przekazać identyfikator karty na stronę w tle i tam wywołać funkcje interfejsu API chrome.tabs.*
.
Do ponownego wczytania sprawdzanej strony można użyć metody reload
. Element wywołujący może też określić zastąpienie ciągu klienta użytkownika, skrypt, który będzie wstrzykiwany na początku wczytywania strony, lub opcję wymuszania ponownego wczytywania zasobów zapisanych w pamięci podręcznej.
Aby uzyskać listę zasobów (dokumentów, arkuszy stylów, skryptów, obrazów itd.), użyj wywołania getResources
i zdarzenia onResourceContent
. Metody getContent
i setContent
klasy Resource
razem ze zdarzeniem onResourceContentCommitted
mogą być używane do obsługi modyfikacji zawartości zasobu, np. przez edytora zewnętrznego.
Wykonywanie kodu w sprawdzanym oknie
Metoda eval
umożliwia rozszerzeniom wykonywanie kodu JavaScript w kontekście sprawdzanej strony. Ta metoda jest skuteczna, gdy jest używana w odpowiednim kontekście, a nieprawidłowo stosowana, jest niebezpieczna. 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 korzysta z izolowanego świata dla ocenianego kodu, więc kod JavaScript ma dostęp do stanu sprawdzanego okna. Użyj tej metody, jeśli wymagany jest dostęp do stanu JavaScriptu sprawdzanej strony. - Kontekst wykonania ocenianego kodu obejmuje interfejs Developer Tools Console API.
Na przykład w kodzie można używać znaków
inspect
i$0
. - Oceniony kod może zwrócić wartość, która jest przekazywana do wywołania zwrotnego rozszerzenia. Zwrócona wartość musi być prawidłowym obiektem JSON (może zawierać tylko podstawowe typy JavaScript i acykliczne odwołania do innych obiektów JSON). Zachowaj szczególną ostrożność podczas przetwarzania danych otrzymanych ze sprawdzanej strony – kontekst wykonywania jest w zasadzie kontrolowany przez sprawdzaną stronę, a złośliwa strona może mieć wpływ 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 oraz dodatkowy kontekst dla każdego rozszerzenia, które ma w niej uruchomione skrypty treści.
Domyślnie metoda eval
uruchamia się w kontekście głównej ramki sprawdzanej strony.
Metoda eval
przyjmuje opcjonalny drugi argument, którego możesz używać do określenia kontekstu, w którym jest oceniany kod. Obiekt options może zawierać jeden lub więcej tych kluczy:
frameURL
- Pozwala określić ramkę inną niż ramka główna badanej strony.
contextSecurityOrigin
- Pozwala wybrać kontekst w określonej ramce zgodnie z jej pochodzeniem z internetu.
useContentScriptContext
- Jeśli ma wartość prawda, uruchom skrypt w tym samym kontekście co skrypty treści rozszerzenia. (Odpowiednik określania własnej organizacji internetowej rozszerzenia jako źródła zabezpieczeń kontekstu). Można go wykorzystać do wymiany danych ze skryptem treści.
Przykłady
Następujący kod sprawdza wersję biblioteki 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 devtools API z repozytorium chrome-extension-samples.
Typy
Resource
Zasób na badanej stronie, np. dokument, skrypt lub obraz.
Właściwości
-
URL
string,
Adres URL zasobu.
-
getContent
void
Pobiera zawartość zasobu.
Funkcja
getContent
wygląda tak:(callback: function) => {...}
-
wywołanie zwrotne
funkcja
Parametr
callback
wygląda tak:(content: string, encoding: string) => void
-
treści, które są
string,
Treść zasobu (potencjalnie zakodowana).
-
kodowanie
string,
Puste, jeśli treść nie jest zakodowana. W przeciwnym razie nazwa kodowania. Obecnie obsługiwany jest tylko format base64.
-
-
-
setContent
void
Ustawia zawartość zasobu.
Funkcja
setContent
wygląda tak:(content: string, commit: boolean, callback?: function) => {...}
-
treści, które są
string,
Nowa treść zasobu. Obecnie obsługiwane są tylko zasoby typu tekstowego.
-
zatwierdź
boolean
Prawda, jeśli użytkownik zakończył edytowanie zasobu i nowa zawartość zasobu powinna być zachowywana. Wartość false, jeśli jest to niewielka zmiana, którą użytkownik edytuje podczas edytowania zasobu.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(error?: object) => void
-
error
obiekt opcjonalnie
Ustaw jako nieokreśloną, jeśli treść zasobu została ustawiona prawidłowo; w innym przypadku opisuje błąd.
-
-
Właściwości
tabId
Identyfikator sprawdzanej karty. Tego identyfikatora można używać z chrome.tabs.* API.
Typ
Liczba
Metody
eval()
chrome.devtools.inspectedWindow.eval(
expression: string,
options?: object,
callback?: function,
)
Analizuje wyrażenie JavaScript w kontekście głównej ramki sprawdzanej strony. Wyrażenie musi określać 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 występujący podczas oceny. W obu przypadkach parametr result
wywołania zwrotnego to undefined
. W przypadku błędu po stronie Narzędzi deweloperskich parametr isException
ma wartość inną niż null, a parametr isError
ma wartość prawda, a pole code
zawiera kod błędu. W przypadku błędu JavaScriptu funkcja isException
ma wartość true, a value
jest wartością ciągu tekstowego zgłoszonego obiektu.
Parametry
-
wyrażenie
string,
Wyrażenie do sprawdzenia.
-
Opcje
obiekt opcjonalnie
Parametr „options” może zawierać jedną lub więcej opcji.
-
frameURL
ciąg znaków opcjonalny
Jeśli zostanie określone, będzie ono oceniane w elemencie iframe, którego adres URL pasuje do podanego adresu. Domyślnie wyrażenie jest sprawdzane w górnej ramce sprawdzanej strony.
-
scriptExecutionContext
ciąg znaków opcjonalny
Chrome 107 i nowsze wersjeOceń wyrażenie w kontekście skryptu treści rozszerzenia, które pasuje do określonego źródła. Jeśli zostanie podany, skrypt scriptExecutionContext zastępuje ustawienie „true” w atrybucie useContentScriptContext.
-
useContentScriptContext
wartość logiczna opcjonalna
Oceń wyrażenie w kontekście skryptu treści rozszerzenia wywołującego, o ile skrypt treści jest już wstawiony na sprawdzanej stronie. W przeciwnym razie wyrażenie nie będzie sprawdzane, a wywołanie zwrotne jest wywoływane z parametrem wyjątku ustawionym na obiekt, dla którego w polu
isError
ustawiono wartość prawda, a polecode
–E_NOTFOUND
.
-
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(result: object, exceptionInfo: object) => void
-
wynik
obiekt
Wynik oceny.
-
exceptionInfo
obiekt
Obiekt zawierający informacje o tym, czy podczas oceny wyrażenia wystąpił wyjątek.
-
kod
string,
Określa, jeśli błąd wystąpił po stronie Narzędzi deweloperskich przed obliczeniem wyrażenia.
-
opis
string,
Określa, jeśli błąd wystąpił po stronie Narzędzi deweloperskich przed obliczeniem wyrażenia.
-
szczegóły
każdy[]
Ustawienie, jeśli błąd wystąpił po stronie Narzędzi deweloperskich przed obliczeniem wyrażenia. Zawiera tablicę wartości, które można zastąpić w ciągu opisu, aby uzyskać więcej informacji o przyczynie błędu.
-
isError
boolean
Określa, jeśli błąd wystąpił po stronie Narzędzi deweloperskich przed obliczeniem wyrażenia.
-
isException
boolean
Ustaw tę wartość, jeśli oceniany kod generuje nieobsługiwany wyjątek.
-
value
string,
Ustaw tę wartość, jeśli oceniany kod generuje nieobsługiwany wyjątek.
-
-
getResources()
chrome.devtools.inspectedWindow.getResources(
callback: function,
)
Pobiera listę zasobów ze sprawdzanej strony.
Parametry
reload()
chrome.devtools.inspectedWindow.reload(
reloadOptions?: object,
)
Wczytuje ponownie sprawdzaną stronę.
Parametry
-
reloadOptions
obiekt opcjonalnie
-
ignoreCache
wartość logiczna opcjonalna
Jeśli ma wartość prawda, program wczytujący pomija pamięć podręczną w przypadku wszystkich sprawdzonych zasobów strony, które zostały wczytane przed uruchomieniem zdarzenia
load
. Efekt jest podobny do naciskania klawiszy Ctrl + Shift + R w sprawdzanym oknie lub w oknie Narzędzi dla programistów. -
injectedScript
ciąg znaków opcjonalny
Jeśli zostanie określony, skrypt będzie wstrzykiwany w każdej ramce sprawdzanej strony bezpośrednio po wczytaniu, przed skryptami ramki. Skrypt nie będzie wstrzykiwany po kolejnych ładowaniu, np. gdy użytkownik naciśnie Ctrl + R.
-
userAgent
ciąg znaków opcjonalny
Jeśli zostanie podany, zastąpi on wartość nagłówka HTTP
User-Agent
, która jest wysyłana podczas wczytywania zasobów sprawdzanej strony. Ciąg znaków zastąpi też wartość właściwościnavigator.userAgent
zwracaną do wszystkich skryptów uruchomionych na sprawdzanej stronie.
-
Wydarzenia
onResourceAdded
chrome.devtools.inspectedWindow.onResourceAdded.addListener(
callback: function,
)
Uruchamiane, gdy do sprawdzanej strony zostanie dodany nowy zasób.
Parametry
-
wywołanie zwrotne
funkcja
Parametr
callback
wygląda tak:(resource: Resource) => void
-
zasób
-
onResourceContentCommitted
chrome.devtools.inspectedWindow.onResourceContentCommitted.addListener(
callback: function,
)
Uruchamiane po zatwierdzeniu nowej wersji zasobu (np. użytkownik zapisze zmodyfikowaną wersję zasobu w narzędziach dla programistów).