Klucz "content_scripts" określa statycznie ładowany plik JavaScript lub CSS, który ma być używany przy każdym otwarciu strony pasującej do określonego wzorca adresu URL. Rozszerzenia mogą też automatycznie wstawiać skrypty treści. Szczegółowe informacje znajdziesz w sekcji Wstrzykiwanie skryptów.
Plik manifestu
Oto lista obsługiwanych kluczy w usłudze "content_scripts". Wymagany jest tylko klucz "matches" oraz "js" lub "css".
manifest.json
{
"name": "My extension",
...
"content_scripts": [
{
"matches": ["https://*.example.com/*"],
"css": ["my-styles.css"],
"js": ["content-script.js"],
"exclude_matches": ["*://*/*foo*"],
"include_globs": ["*example.com/???s/*"],
"exclude_globs": ["*bar*"],
"all_frames": false,
"match_origin_as_fallback": false,
"match_about_blank": false,
"run_at": "document_idle",
"world": "ISOLATED",
}
],
...
}
Files
Każdy plik musi zawierać ścieżkę względną do zasobu w katalogu głównym rozszerzenia. Początkowe ukośniki (/) są automatycznie przycinane. Klucz "run_at" określa, kiedy każdy plik ma być wstrzykiwany.
"css"– tablica- Opcjonalny. Tablica ścieżek do plików CSS wstrzykiwana w kolejności tej tablicy przed rozpoczęciem jakiejkolwiek konstrukcji DOM lub renderowania strony.
"js"– tablica,- Opcjonalny. Tablica ścieżek do plików JavaScript wstrzykiwana w kolejności, w jakiej występują w tej tablicy, po wstrzyknięciu plików CSS. Każdy ciąg w tablicy musi być ścieżką względną do zasobu w katalogu głównym rozszerzenia. Początkowe ukośniki („/”) są automatycznie przycinane.
Dopasuj adresy URL
Wymagana jest tylko właściwość "matches". Następnie użyj atrybutów "exclude_matches", "include_globs" i "exclude_globs", aby określić, w których adresach URL ma być wstawiony kod. Klawisz "matches" wywołuje ostrzeżenie.
"matches"– tablica- Wymagane. Określa wzorce adresów URL, do których mają być wstrzykiwane skrypty treści. Informacje o składni znajdziesz w sekcji Wzorce dopasowania.
"exclude_matches"– tablica- Opcjonalny. Wyklucza wzorce adresów URL, w których mają być wstrzykiwane skrypty treści. Informacje o składni znajdziesz w sekcji Wzorce dopasowania.
"include_globs"– tablica- Opcjonalny. Stosowana po dopasowaniach, aby uwzględniać tylko te adresy URL, które również pasują do tego wzorca. Służy do emulacji słowa kluczowego @include Greasemonkey.
"exclude_globs"– tablica- Opcjonalny. Stosowana po dopasowaniach, aby wykluczać adresy URL pasujące do tego wzorca. Ma na celu emulowanie słowa kluczowego @excluded „Greasemonkey”.
Adresy URL obiektów Glob zawierają symbole wieloznaczne * i znaki zapytania. Symbol wieloznaczny * pasuje do dowolnego ciągu o dowolnej długości, w tym do pustego ciągu, a znak zapytania ? odpowiada dowolnemu pojedynczemu znakowi.
Skrypt treści jest wstawiany na stronie, jeśli:
- Jej adres URL pasuje do dowolnych wzorców
"matches"i"include_globs". - URL nie pasuje do wzorców
"exclude_matches"ani"exclude_globs".
Przykłady dopasowania kulis i adresów URL
"include_globs"
manifest.json
{
...
"content_scripts": [
{
"matches": ["https://*.example.com/*"],
"include_globs": ["https://???.example.com/foo/*"],
"js": ["content-script.js"]
}
],
...
}
https://www.example.com/foo/bar https://the.example.com/foo/
https://my.example.com/foo/bar https://example.com/foo/* https://www.example.com/foo
manifest.json
{
...
"content_scripts": [
{
"matches": ["https://*.example.com/*"],
"include_globs": ["*example.com/???s/*"],
"js": ["content-script.js"]
}
],
...
}
https://www.example.com/arts/index.html https://www.example.com/jobs/index.html
https://www.example.com/sports/index.html https://www.example.com/music/index.html
"exclude_globs"
manifest.json
{
...
"content_scripts": [
{
"matches": ["https://*.example.com/*"],
"exclude_globs": ["*science*"],
"js": ["content-script.js"]
}
],
...
}
https://history.example.com https://.example.com/music
https://science.example.com https://www.example.com/science
Przykład zaawansowanego dostosowania
manifest.json
{
...
"content_scripts": [
{
"matches": ["https://*.example.com/*"],
"exclude_matches": ["*://*/*business*"],
"include_globs": ["*example.com/???s/*"],
"exclude_globs": ["*science*"],
"js": ["content-script.js"]
}
],
...
}
https://www.example.com/arts/index.html https://.example.com/jobs/index.html
https://science.example.com https://www.example.com/jobs/business https://www.example.com/science
Klatki
Klucz "all_frames" określa, czy skrypt treści powinien być wstrzykiwany we wszystkich ramkach spełniających określone wymagania dotyczące adresu URL. Jeśli zasada ma wartość false, następuje wstrzykiwanie tylko do najwyższej klatki. Można go używać razem z atrybutem "match_about_blank", aby wstrzykiwać do ramki about:blank.
Aby stosować wstrzykiwanie w innych ramkach, takich jak data:, blob: i filesystem:, ustaw "match_origin_as_fallback" na true. Więcej informacji znajdziesz w sekcji Wstawianie w powiązanych klatkach.
"all_frames"– wartość logiczna- Opcjonalny. Wartość domyślna to
false, co oznacza, że dopasowywana jest tylko górna klatka. Jeśli zasada ma wartość Prawda, kod jest wstrzykiwany do wszystkich klatek, nawet jeśli nie jest ona najwyższą klatką na karcie. Każda ramka jest sprawdzana niezależnie pod kątem wymagań dotyczących adresów URL. Jeśli te wymagania nie zostaną spełnione, nie będzie wstrzykiwana do ramek podrzędnych. "match_about_blank"– wartość logiczna- Opcjonalny. Domyślna wartość to
false. Określa, czy skrypt powinien wstrzykiwać się do ramkiabout:blank, w której nadrzędny adres URL pasuje do jednego z wzorców zadeklarowanych w"matches". "match_origin_as_fallback"– wartość logiczna- Opcjonalny. Domyślna wartość to
false. Określa, czy skrypt ma wstrzykiwać elementy do ramek, które zostały utworzone przez pasujące źródło, ale których adres URL lub źródło może nie pasować bezpośrednio do wzorca. Należą do nich klatki o różnych schematach, np.about:,data:,blob:ifilesystem:.
Środowisko wykonawcze i środowisko wykonawcze
Domyślnie skrypty treści są wstrzykiwane po zakończeniu wczytywania dokumentu i wszystkich zasobów i działają w prywatnym, izolowanym środowisku wykonawczym, które nie jest dostępne dla strony i innych rozszerzeń. Możesz zmienić te wartości domyślne przy użyciu tych kluczy:
"run_at"–document_start|document_end|document_idle- Opcjonalny. Określa, kiedy skrypt powinien zostać wstawiony na stronie. Odpowiada on stanom wczytywania Document.readyState:
"document_start": interfejs DOM nadal się wczytuje."document_end": zasoby strony nadal się wczytują"document_idle": DOM i zasoby zostały wczytane. Jest to ustawienie domyślne.
"world"–ISOLATED|MAIN- Opcjonalny. Świat JavaScriptu, w którym ma być wykonywany skrypt. Wartość domyślna to
"ISOLATED", czyli środowisko wykonawcze unikalne dla skryptu treści. Wybór środowiska"MAIN"oznacza, że skrypt współdzieli środowisko wykonawcze z JavaScriptem strony hosta. Więcej informacji znajdziesz w artykule Praca w izolowanym świecie.
Przykład
Zobacz samouczek Uruchamianie na każdej stronie, aby utworzyć rozszerzenie, które wstrzykuje skrypt treści w pliku manifestu.