Klucz "content_scripts" określa statycznie wczytywany plik JavaScript lub CSS, który ma być używany przy każdym otwarciu strony, który pasuje do określonego wzorca adresu URL. Rozszerzenia mogą też wstrzykiwać skrypty treści programowo. Więcej informacji znajdziesz w sekcji Wstawianie skryptów.
Plik manifestu
Oto obsługiwane klucze w usłudze "content_scripts". Wymagany jest tylko klucz "matches" i "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 ma zostać wstrzykiwany.
"css"– tablica- Opcjonalny. Tablica ścieżek plików CSS wstrzykiwana w kolejności określonej dla tej tablicy, a przed konstrukcją DOM lub renderowaniem strony.
"js"– tablica,- Opcjonalny. Tablica ścieżek plików JavaScript wstrzykiwana w kolejności, w jakiej występują w tej tablicy, po wstrzykiwaniu plików CSS. Każdy ciąg w tablicy musi być ścieżką względną do zasobu w katalogu głównym rozszerzenia. Ukośniki na początku („/”) są automatycznie przycinane.
Dopasuj adresy URL
Wymagana jest tylko właściwość "matches". Następnie za pomocą reguł "exclude_matches", "include_globs" i "exclude_globs" możesz określić, w których adresach URL ma być wstrzyknięty kod. Klucz "matches" wywoła ostrzeżenie.
"matches"– tablica- Wymagane. Określa wzorce adresu URL, w 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, do których mają być wstrzykiwane skrypty treści. Informacje o składni znajdziesz w sekcji Wzorce dopasowania.
"include_globs"– tablica- Opcjonalny. Jest stosowana po dopasowaniu, aby uwzględnić tylko te adresy URL, które również pasują do tego glob. Służy do emulacji słowa kluczowego @include Greasemonkey.
"exclude_globs"– tablica- Opcjonalny. Stosowane po dopasowaniu, aby wykluczyć adresy URL pasujące do tego glob. Służy do emulacji słowa kluczowego Greasemonkey @excl.
Adresy URL glob to takie, które 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:
- Jego adres URL pasuje do wszelkich wzorców
"matches"i"include_globs". - URL nie pasuje do wzorca
"exclude_matches"ani"exclude_globs".
Przykłady obiektów Globs i dopasowania 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 ustawisz wartość false, zdjęcie będzie wstrzyknięte tylko w najwyższej ramce. Można go używać razem z elementem "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 sekcji Wstrzykiwanie 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 ma wartość Prawda, klatka jest wstrzykiwana we wszystkich klatkach, nawet jeśli nie jest to najwyższa klatka na karcie. Każda ramka jest sprawdzana niezależnie pod kątem wymagań dotyczących adresu URL i nie zostanie wstawiona do ramek podrzędnych, jeśli te wymagania nie zostaną spełnione. "match_about_blank"– wartość logiczna- Opcjonalny. Domyślna wartość to
false. Określa, czy skrypt powinien wstrzykiwać się w ramceabout:blank, w której nadrzędny adres URL pasuje do jednego z wzorców zadeklarowanych w zasadzie"matches". "match_origin_as_fallback"– wartość logiczna- Opcjonalny. Domyślna wartość to
false. Określa, czy skrypt ma wstrzykiwać ramki utworzone przez pasujące źródło, ale ich adres URL lub źródło mogą nie pasować bezpośrednio do wzorca. Są to ramki o różnych schematach, np.about:,data:,blob:ifilesystem:.
Czas działania i środowisko wykonawcze
Domyślnie skrypty treści są wstrzykiwane po zakończeniu wczytywania dokumentu i wszystkich zasobów. Działają w prywatnym, wyodrębnionym środowisku wykonawczym, które jest niedostępne dla strony ani innych rozszerzeń. Ustawienia domyślne możesz zmienić za pomocą tych klawiszy:
"run_at"–document_start|document_end|document_idle- Opcjonalny. Określa, kiedy skrypt powinien zostać wstawiony na stronie. Odpowiada ono stanom wczytywania Document.readyState:
"document_start": wciąż trwa wczytywanie DOM."document_end": wciąż trwa wczytywanie zasobów strony"document_idle": DOM i zasoby zostały wczytane. Jest to ustawienie domyślne.
"world"–ISOLATED|MAIN- Opcjonalny. Świat JavaScriptu, w którym skrypt ma zostać wykonany. Domyślna wartość to
"ISOLATED", czyli środowisko wykonawcze unikalne dla skryptu treści. Wybranie świata"MAIN"oznacza, że skrypt będzie współużytkować środowisko wykonawcze z kodem JavaScript strony hostującej. Więcej informacji znajdziesz w artykule Praca w odizolowanych światach. .
Przykład
Aby dowiedzieć się, jak utworzyć rozszerzenie, które wstawia skrypt treści w pliku manifestu, zapoznaj się z samouczkiem Uruchom na każdej stronie.