Każde rozszerzenie musi mieć w swoim katalogu głównym plik manifest.json z ważnymi informacjami o jego strukturze i działaniu.
Na tej stronie opisujemy strukturę plików manifestu rozszerzeń i ich funkcje.
Przykłady
Te przykładowe pliki manifestu zawierają podstawową strukturę i często używane funkcje jako punkt wyjścia do utworzenia własnego pliku manifestu:
Minimalny plik manifestu
{
"manifest_version": 3,
"name": "Minimal Manifest",
"version": "1.0.0",
"description": "A basic example extension with only required keys",
"icons": {
"48": "images/icon-48.png",
"128": "images/icon-128.png"
},
}
Rejestrowanie skryptu dotyczącego treści
{
"manifest_version": 3,
"name": "Run script automatically",
"description": "Runs a script on www.example.com automatically when user installs the extension",
"version": "1.0",
"icons": {
"16": "images/icon-16.png",
"32": "images/icon-32.png",
"48": "images/icon-48.png",
"128": "images/icon-128.png"
},
"content_scripts": [
{
"js": [
"content-script.js"
],
"matches": [
"http://*.example.com//"
]
}
]
}
Wstaw skrypt treści
{
"manifest_version": 3,
"name": "Click to run",
"description": "Runs a script when the user clicks the action toolbar icon.",
"version": "1.0",
"icons": {
"16": "images/icon-16.png",
"32": "images/icon-32.png",
"48": "images/icon-48.png",
"128": "images/icon-128.png"
},
"background": {
"service_worker": "service-worker.js"
},
"action": {
"default_icon": {
"16": "images/icon-16.png",
"32": "images/icon-32.png",
"48": "images/icon-48.png",
"128": "images/icon-128.png"
}
},
"permissions": ["scripting", "activeTab"]
}
Wyskakujące okienko z uprawnieniami
{
"manifest_version": 3,
"name": "Popup extension that requests permissions",
"description": "Extension that includes a popup and requests host permissions and storage permissions .",
"version": "1.0",
"icons": {
"16": "images/icon-16.png",
"32": "images/icon-32.png",
"48": "images/icon-48.png",
"128": "images/icon-128.png"
},
"action": {
"default_popup": "popup.html"
},
"host_permissions": [
"https://*.example.com/"
],
"permissions": [
"storage"
]
}
Panel boczny
{
"manifest_version": 3,
"name": "Side panel extension",
"version": "1.0",
"description": "Extension with a default side panel.",
"icons": {
"16": "images/icon-16.png",
"48": "images/icon-48.png",
"128": "images/icon-128.png"
},
"side_panel": {
"default_path": "sidepanel.html"
},
"permissions": ["sidePanel"]
}
Klucze pliku manifestu
Poniżej znajduje się lista wszystkich obsługiwanych kluczy pliku manifestu.
Klucze wymagane przez platformę rozszerzeń
"manifest_version"- Liczba całkowita określająca wersję formatu pliku manifestu, którego używa rozszerzenie. Jedyną obsługiwaną wartością jest
3. "name"- Ciąg znaków identyfikujący rozszerzenie w Chrome Web Store, okno instalacji i stronę rozszerzeń Chrome użytkownika (
chrome://extensions). Maksymalna długość to 75 znaków. Informacje o korzystaniu z nazw lokalnych znajdziesz w sekcji Internacjonalizacja. "version"- Ciąg znaków, który określa numer wersji rozszerzenia. Więcej informacji o formatowaniu numerów wersji znajdziesz w sekcji Wersja.
Klucze wymagane przez Chrome Web Store
"description"- Ciąg tekstowy opisujący rozszerzenie zarówno w Chrome Web Store, jak i na stronie zarządzania rozszerzeniami użytkownika. Maksymalna długość to 132 znaki. Informacje o lokalizowaniu opisów znajdziesz w sekcji Internacjonalizacja.
"icons"- Co najmniej jedna ikona reprezentująca rozszerzenie. Informacje o sprawdzonych metodach znajdziesz w sekcji Ikony.
Klawisze opcjonalne
"action"- Określa wygląd i działanie ikony rozszerzenia na pasku narzędzi Google. Więcej informacji:
chrome.action. "author"- Określa adres e-mail konta użytego do utworzenia rozszerzenia.
"background"- Określa plik JavaScript zawierający skrypt service worker rozszerzenia, który działa jako moduł obsługi zdarzeń. Więcej informacji znajdziesz w artykule Informacje o skryptach service worker rozszerzeń.
"chrome_settings_overrides"- Określa zastąpienia wybranych ustawień Chrome. Więcej informacji znajdziesz w artykule Zastępowanie ustawień Chrome.
"chrome_url_overrides"- Określa zastąpienia dla domyślnych stron Chrome. Więcej informacji znajdziesz w artykule Zastępowanie stron Chrome.
"commands"- Określa skróty klawiszowe w rozszerzeniu. Więcej informacji znajdziesz na stronie chrome.commands.
"content_scripts"- Określa pliki JavaScript lub CSS, które mają być używane, gdy użytkownik otworzy określone strony internetowe. Więcej informacji znajdziesz w artykule Skrypty treści.
"content_security_policy"- Określa ograniczenia dotyczące skryptów, stylów i innych zasobów, z których może korzystać rozszerzenie. Więcej informacji znajdziesz w artykule na temat polityki bezpieczeństwa treści.
"cross_origin_embedder_policy"- Określa wartość nagłówka HTTP Cross-Origin-Embedder-Policy, która konfiguruje umieszczanie zasobów z innych domen na stronie rozszerzenia.
"cross_origin_opener_policy"- Określa wartość nagłówka HTTP Cross-Origin-Opener-Policy, która sprawia, że strona rozszerzenia najwyższego poziomu nie współużytkuje grupy kontekstu przeglądania z dokumentami z innych domen.
"declarative_net_request"- Definiuje reguły statyczne dla interfejsu API declarativeNetRequest, które umożliwiają blokowanie i modyfikowanie żądań sieciowych.
"default_locale"- Ciąg znaków określający domyślny język rozszerzenia, które obsługuje wiele języków. Przykłady to „en” i „pt_BR”. Ten klucz jest wymagany w przypadku rozszerzeń zlokalizowanych i nie można go używać w rozszerzeniach, które nie są przetłumaczone. Więcej informacji znajdziesz w sekcji Internacjonalizacja.
"devtools_page"- Definiuje strony korzystające z interfejsów API DevTools.
"export"- Umożliwia eksportowanie zasobów z rozszerzenia. Więcej informacji znajdziesz w artykule o eksportowaniu.
"externally_connectable"- Określa, jakie inne strony i rozszerzenia mogą łączyć się z Twoimi rozszerzeniami. Więcej informacji:
"externally_connectable". "homepage_url"- Ciąg znaków określający adres URL strony głównej rozszerzenia. Jeśli to ustawienie nie jest zdefiniowane, domyślną stroną główną jest strona rozszerzenia w Chrome Web Store. To pole jest szczególnie przydatne, jeśli hostujesz rozszerzenie we własnej witrynie.
"host_permissions"- Lista stron internetowych, z którymi Twoje rozszerzenie może wchodzić w interakcje, określone za pomocą wzorców dopasowania adresów URL. Uprawnienia użytkownika dotyczące tych witryn są pytane podczas instalacji. Więcej informacji znajdziesz w artykule Uprawnienia hosta.
"import"- Umożliwia importowanie zasobów do rozszerzenia. Więcej informacji znajdziesz w artykule o importowaniu.
"incognito"- Określa sposób działania rozszerzenia w trybie incognito. Obsługiwane wartości to
"spanning","split"i"not_allowed". Więcej informacji znajdziesz w sekcji Tryb incognito. "key"- Określa identyfikator rozszerzenia do różnych celów programistycznych. Więcej informacji znajdziesz w sekcji Klucz.
"minimum_chrome_version"- Określa najstarszą wersję Chrome, która może zainstalować rozszerzenie. Wartość musi być podłańcuchem istniejącego ciągu znaków wersji przeglądarki Chrome, np.
"107"lub"107.0.5304.87". Użytkownicy wersji Chrome starszej niż minimalna widzą w Chrome Web Store ostrzeżenie „Niezgodna” i nie mogą zainstalować rozszerzenia. Jeśli dodasz to rozszerzenie do istniejącego rozszerzenia, użytkownicy starszej wersji Chrome nie będą otrzymywać jego automatycznych aktualizacji. Obejmuje to też użytkowników biznesowych w trybie efemerycznym. "oauth2"- Zezwalaj na używanie identyfikatora zabezpieczeń OAuth 2.0. Wartość tego klucza musi być obiektem o właściwościach
"client_id"i"scopes". Więcej informacji znajdziesz w samouczku OAuth 2.0. "omnibox"- Umożliwia rozszerzeniu rejestrowanie słowa kluczowego na pasku adresu Chrome. Więcej informacji znajdziesz w sekcji Omnibox.
"optional_host_permissions"- Deklaruje opcjonalne uprawnienia hosta dla rozszerzenia.
"optional_permissions"- Deklaruje opcjonalne uprawnienia rozszerzenia.
"options_page"- Określa ścieżkę do pliku options.html, które ma zostać użyte przez rozszerzenie jako stronę opcji. Więcej informacji znajdziesz w artykule Daj użytkownikom różne opcje.
"options_ui"- Określa ścieżkę do pliku HTML, która umożliwia użytkownikowi zmianę opcji rozszerzenia na stronie Rozszerzenia Chrome. Więcej informacji znajdziesz w sekcji Opcje wbudowane.
"permissions"- Umożliwia korzystanie z określonych interfejsów API rozszerzeń. Ogólne wyjaśnienie znajdziesz w sekcji Uprawnienia. Na stronach dotyczących poszczególnych interfejsów API znajdziesz informacje o wymaganych uprawnieniach.
"requirements"- Wyświetla listę technologii wymaganych do korzystania z rozszerzenia. Listę obsługiwanych wymagań znajdziesz w sekcji Wymagania.
"sandbox"- Określa zestaw stron rozszerzeń, które nie mają dostępu do interfejsów API rozszerzeń lub bezpośredniego dostępu do stron poza piaskownicą. Więcej informacji znajdziesz na stronie Piaskownica.
"short_name"- Ciąg tekstowy zawierający skróconą wersję nazwy rozszerzenia używany w przypadku ograniczonej liczby znaków. Maksymalna długość to 12 znaków. Jeśli jest on nieokreślony, zamiast niego wyświetla się skrócona wersja klucza „name”.
"side_panel"- Identyfikuje plik HTML, który ma zostać wyświetlony w sidePanel.
"storage"- Deklaruje schemat JSON dla zarządzanego obszaru pamięci masowej. Więcej informacji znajdziesz w pliku manifestu dotyczącym obszarów przechowywania.
"tts_engine"- Rejestruje rozszerzenie jako mechanizm zamiany tekstu na mowę. Więcej informacji znajdziesz w artykule o interfejsie API ttsEngine.
"update_url"- Ciąg tekstowy zawierający adres URL strony aktualizacji rozszerzenia. Użyj tego klucza, jeśli hostujesz rozszerzenie poza Chrome Web Store.
"version_name"- Ciąg tekstowy opisujący wersję rozszerzenia. Przykłady:
"1.0 beta"i"build rc2". Jeśli go nie podasz, na stronie zarządzania rozszerzeniami wyświetli się wartość „version”. "web_accessible_resources"- Definiuje pliki w ramach rozszerzenia, do których strony internetowe lub inne rozszerzenia mają dostęp. Więcej informacji znajdziesz w artykule o zasobach dostępnych w internecie (w języku angielskim).
Opcjonalne klucze ChromeOS
"file_browser_handlers"- Zapewnia dostęp do interfejsu API
fileBrowserHandler, który umożliwia rozszerzeniom dostęp do przeglądarki plików w ChromeOS. "file_handlers"- Określa typy plików, które mają być obsługiwane przez rozszerzenia do ChromeOS. Więcej informacji:
file_handlers. "file_system_provider_capabilities"- Umożliwia dostęp do interfejsu API
fileSystemProvider, który umożliwia rozszerzeniom tworzenie systemów plików, których może używać ChromeOS. "input_components"- Umożliwia korzystanie z interfejsu API Edytora metody wprowadzania. Więcej informacji:
input_components.