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
.