Klucz "content_scripts" określa statycznie wczytywany plik JavaScript lub CSS, który ma być używany za każdym razem, gdy otwierana jest strona pasująca do określonego wzorca adresu URL. Rozszerzenia mogą też wstrzykiwać skrypty treści automatycznie. Szczegółowe informacje znajdziesz w artykule o wstrzykiwaniu skryptów.
Plik manifestu
Oto obsługiwane klucze dla: "content_scripts". Wymagane są 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",
}
],
...
}
Pliki
Każdy plik musi zawierać ścieżkę względną do zasobu w katalogu głównym rozszerzenia. Ukośniki na początku (/) są automatycznie usuwane. Klucz "run_at" określa, kiedy każdy plik zostanie wstrzyknięty.
"css"– tablica- Opcjonalny. Tablica ścieżek do plików CSS, wstrzykiwana w kolejności podanej w tablicy i przed utworzeniem modelu DOM lub wyrenderowaniem strony.
"js"– tablica,- Opcjonalny. Tablica ścieżek plików JavaScript, wstrzykiwanych w kolejności, w jakiej pojawiają się w tej tablicy, po wstrzyknięciu plików CSS. Każdy ciąg znaków w tablicy musi być ścieżką względną do zasobu w katalogu głównym rozszerzenia. Ukośniki na początku ('/') są automatycznie usuwane.
Dopasowanie adresów URL
Wymagana jest tylko właściwość "matches". Następnie możesz użyć "exclude_matches", "include_globs" i "exclude_globs", aby dostosować adresy URL, do których chcesz wstawić kod. Klucz "matches" wywoła ostrzeżenie.
"matches"– tablica- Wymagany. Określa wzorce adresów URL, do których mają być wstrzykiwane skrypty treści. Składnię znajdziesz w artykule Wzorce dopasowania.
"exclude_matches"– tablica- Opcjonalny. Wyklucza wzorce adresów URL, do których mają być wstrzykiwane skrypty treści. Składnię znajdziesz w artykule Wzorce dopasowania.
"include_globs"– tablica- Opcjonalny. Stosowany po dopasowaniach, aby uwzględnić tylko te adresy URL, które pasują również do tego wzorca. Ma naśladować słowo kluczowe @include Greasemonkey.
"exclude_globs"– tablica- Opcjonalny. Stosowane po dopasowaniach, aby wykluczyć adresy URL pasujące do tego wzorca. Ma naśladować słowo kluczowe @exclude Greasemonkey.
Adresy URL z globalnymi wzorcami to takie, które zawierają symbole wieloznaczne * i znaki zapytania. Symbol wieloznaczny * odpowiada dowolnemu ciągowi znaków o dowolnej długości, w tym pustemu ciągowi, a znak zapytania ? odpowiada dowolnemu pojedynczemu znakowi.
Skrypt treści jest wstrzykiwany na stronę, jeśli:
- Adres URL jest zgodny z dowolnymi wzorcami
"matches"i"include_globs". - Adres URL nie pasuje do wzorców
"exclude_matches"ani"exclude_globs".
Przykłady dopasowywania wzorców 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 dostosowywania
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 zostać wstrzyknięty do wszystkich ramek spełniających określone wymagania dotyczące adresu URL. Jeśli ustawisz wartość false, skrypt będzie wstrzykiwany tylko do ramki najwyższego poziomu. Można go używać razem z "match_about_blank" do wstrzykiwania do ramki about:blank.
Aby wstrzyknąć do innych ramek, takich jak data:, blob: i filesystem:, ustaw "match_origin_as_fallback" na true. Szczegółowe informacje znajdziesz w artykule Wstrzykiwanie w powiązanych ramkach.
"all_frames"– wartość logiczna- Opcjonalny. Domyślna wartość to
false, co oznacza, że dopasowywana jest tylko górna ramka. Jeśli ma wartość „true”, skrypt zostanie wstrzyknięty do wszystkich ramek, nawet jeśli ramka nie jest najwyższą ramką na karcie. Każda ramka jest sprawdzana niezależnie pod kątem wymagań dotyczących adresów URL. Jeśli wymagania te nie są spełnione, skrypt nie zostanie wstrzyknięty do ramek podrzędnych. "match_about_blank"– wartość logiczna- Opcjonalny. Domyślna wartość to
false. Określa, czy skrypt powinien zostać wstrzyknięty do ramkiabout:blank, w której nadrzędny adres URL pasuje do jednego ze wzorców zadeklarowanych w"matches". "match_origin_as_fallback"– wartość logiczna- Opcjonalny. Domyślna wartość to
false. Określa, czy skrypt powinien być wstrzykiwany do ramek utworzonych przez pasujące źródło, ale których adres URL lub źródło mogą nie pasować bezpośrednio do wzorca. Obejmuje to ramki z różnymi schematami, takimi jakabout:,data:,blob:ifilesystem:.
Środowisko wykonawcze i czas działania
Domyślnie skrypty treści są wstrzykiwane po zakończeniu wczytywania dokumentu i wszystkich zasobów. Znajdują się one w prywatnym, odizolowanym środowisku wykonawczym, które nie jest dostępne dla strony ani innych rozszerzeń. Możesz zmienić te wartości domyślne w tych kluczach:
"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": DOM jest nadal wczytywany."document_end": zasoby strony nadal się wczytują."document_idle": DOM i zasoby zostały wczytane. Jest to ustawienie domyślne.
"world"–ISOLATED|MAIN- Opcjonalny. Środowisko JavaScript, w którym ma zostać wykonany skrypt. Domyślna wartość to
"ISOLATED", czyli środowisko wykonawcze unikalne dla skryptu treści. Wybranie świata"MAIN"oznacza, że skrypt będzie współdzielić środowisko wykonawcze z kodem JavaScript strony hosta. Więcej informacji znajdziesz w artykule Praca w odizolowanych środowiskach.
Przykład
Aby utworzyć rozszerzenie, które wstrzykuje skrypt treści w pliku manifestu, zapoznaj się z samouczkiem Uruchamianie na każdej stronie.