Format pliku manifestu

Każda wersja rozszerzenia musi mieć w katalogu głównym plik manifest.json, który zawiera ważne informacje o strukturze i zachowaniu tej wersji. Na tej stronie wyjaśniamy strukturę plików manifestów rozszerzeń i funkcje, które mogą one zawierać.

Przykłady

Poniżej znajdziesz przykładowe manifesty, które zawierają podstawową strukturę pliku manifestu oraz niektóre często używane funkcje. Mogą one posłużyć Ci 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 zawartoś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//"
      ]
    }
  ]
}

Wstrzyknięcie skryptu dotyczącego zawartoś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"]
}

{
  "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 manifestu

Poniżej znajduje się lista wszystkich obsługiwanych kluczy pliku manifestu.

Klucze wymagane przez platformę rozszerzeń

"manifest_version"
Całka określająca wersję formatu pliku manifestu używanego przez Twoje rozszerzenie. Jedyną obsługiwaną wartością jest 3.
"name"
Ciąg znaków identyfikujący rozszerzenie w Chrome Web Store, oknie instalacji i na stronie użytkownika z rozszerzeniami Chrome (chrome://extensions). Maksymalna długość to 75 znaków. Informacje o używaniu nazw w konkretnych lokalizacjach znajdziesz w artykule Tłumaczenie na inne języki.
"version"
Ciąg znaków identyfikujący numer wersji rozszerzenia. Informacje o formatowaniu numeru wersji znajdziesz w artykule Wersja.

Klucze wymagane przez Chrome Web Store

"description"
Ciąg znaków opisujący rozszerzenie w Chrome Web Store i na stronie zarządzania rozszerzeniami użytkownika. Maksymalna długość to 132 znaki. Informacje o lokalizowaniu opisów znajdziesz w artykule Internacjonalizacja.
"icons"
Co najmniej 1 ikona reprezentująca rozszerzenie. Informacje o sprawdzonych metodach znajdziesz w artykule Ikony.

Opcjonalne klucze

"action"
Określa wygląd i działanie ikony rozszerzenia na pasku narzędzi Google. Więcej informacji znajdziesz w artykule chrome.action.
"background"
Określa plik JavaScriptu zawierający usługę instancji roboczej rozszerzenia, która działa jako moduł obsługi zdarzeń. Więcej informacji znajdziesz w artykule Skrypty service worker.
"chrome_settings_overrides"
Określa zastąpienia wybranych ustawień Chrome. Więcej informacji znajdziesz w artykule Nadrzędne ustawienia 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 w 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, których może używać rozszerzenie. Więcej informacji znajdziesz w zasadach dotyczących bezpieczeństwa treści.
"cross_origin_embedder_policy"
Określa wartość nagłówka HTTP Cross-Origin-Embedder-Policy, który 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 umożliwia zadbanie o to, aby strona rozszerzenia najwyższego poziomu nie udostępniała kontekstu przeglądania grupie dokumentów z innych domen.
"declarative_net_request"
Określa reguły statyczne dla interfejsu declarativeNetRequest API, który umożliwia blokowanie i modyfikowanie żądań sieciowych.
"default_locale"
Ciąg znaków określający domyślny język rozszerzenia, które obsługuje wiele lokalizacji. Przykłady to „pl” i „pl_PL”. Ten klucz jest wymagany w rozszerzeniach zlokalizowanych i nie można go używać w rozszerzeniach, które nie są zlokalizowane. Więcej informacji znajdziesz w artykule Tłumaczenie na inne języki.
"devtools_page"
Określa strony, które korzystają z interfejsów API DevTools.
"export"
Zezwalanie na eksportowanie zasobów z rozszerzenia. Więcej informacji znajdziesz w sekcji Eksportowanie.
"externally_connectable"
Określa, które inne strony i rozszerzenia mogą łączyć się z Twoimi rozszerzeniami. Więcej informacji znajdziesz w artykule "externally_connectable".
"homepage_url"
Ciąg znaków określający adres URL strony głównej rozszerzenia. Jeśli nie jest zdefiniowana, domyślnie jest to strona rozszerzenia w Chrome Web Store. To pole jest szczególnie przydatne, jeśli rozszerzenie jest hostowane na Twojej stronie.
"host_permissions"
Wyświetla listę stron internetowych, z którymi rozszerzenie może wchodzić w interakcję, zdefiniowanych za pomocą wzorów dopasowywania adresów URL. Podczas instalacji użytkownik jest proszony o zezwolenie na dostęp do tych witryn. Więcej informacji znajdziesz w artykule Uprawnienia hosta.
"import"
Pozwala na importowanie zasobów do rozszerzenia. Więcej informacji znajdziesz w artykule Importowanie.
"incognito"
Określa, jak rozszerzenie ma się zachowywać w trybie incognito. Obsługiwane wartości to "spanning", "split" i "not_allowed". Więcej informacji znajdziesz w artykule Tryb incognito.
"key"
Określa identyfikator rozszerzenia na potrzeby różnych zastosowań programistycznych. Więcej informacji znajdziesz w sekcji Klucz.
"minimum_chrome_version"
Określa najstarszą wersję Chrome, w której można zainstalować rozszerzenie. Wartość musi być podciągiem znaków istniejącej wersji przeglądarki Chrome, np. "107" lub "107.0.5304.87". Użytkownicy korzystający z wersji Chrome starszych niż wersja minimalna zobaczą w Chrome Web Store ostrzeżenie „Niekompatybilne” i nie będą mogli zainstalować rozszerzenia. Jeśli dodasz to do istniejącego rozszerzenia, użytkownicy korzystający ze starszej wersji Chrome nie będą otrzymywać automatycznych aktualizacji rozszerzenia. Dotyczy to użytkowników biznesowych w trybie tymczasowym.
"oauth2"
Zezwalanie na używanie identyfikatora zabezpieczeń OAuth 2.0. Wartość tego klucza musi być obiektem z właściwościami "client_id" i "scopes". Szczegółowe informacje znajdziesz w samouczku OAuth 2.0.
"omnibox"
Zezwalanie rozszerzeniu na rejestrowanie słowa kluczowego na pasku adresu w Chrome. Więcej informacji znajdziesz w sekcji Omniboks.
"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óry ma być używany przez rozszerzenie jako strona opcji. Więcej informacji znajdziesz w artykule Daj użytkownikom opcje
.
"options_ui"
Określa ścieżkę do pliku HTML, który umożliwia użytkownikowi zmianę opcji rozszerzenia na stronie Rozszerzenia Chrome. Więcej informacji znajdziesz w sekcji Opcje osadzania.
"permissions"
Włącza używanie określonych interfejsów API rozszerzeń. Ogólne informacje znajdziesz w sekcji Uprawnienia. Na stronach referencyjnych poszczególnych interfejsów API podano wymagane uprawnienia.
"requirements"
Wykaz 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ń ani bezpośredniego dostępu do stron nieobjętych piaskownicą. Więcej informacji znajdziesz w piaskownicy.
"short_name"
Ciąg tekstowy zawierający skróconą wersję nazwy rozszerzenia, która ma być używana, gdy ilość znaków jest ograniczona. Maksymalna długość to 12 znaków. Jeśli nie jest zdefiniowany, zamiast niego wyświetlana jest skrócona wersja klucza „name”.
"side_panel"
Określa plik HTML, który ma być wyświetlany w sidePanel.
"storage"
Określa schemat JSON dla obszaru magazynu zarządzanego. Więcej informacji znajdziesz w pliku manifestu dla obszarów miejsca na dane.
"tts_engine"
Rejestruje rozszerzenie jako mechanizm zamiany tekstu na mowę. Więcej informacji znajdziesz w interfejsie API ttsEngine.
"update_url"
Ciąg tekstowy zawierający adres URL strony aktualizacji rozszerzenia. Użyj tego klucza, jeśli rozszerzenie jest hostowane poza Chrome Web Store.
"version_name"
Ciąg tekstowy opisujący wersję rozszerzenia. Przykłady: "1.0 beta" i "build rc2". Jeśli nie podasz tej wartości, na stronie zarządzania rozszerzeniem będzie widoczna wartość „wersja”.
"web_accessible_resources"
Określa pliki w rozszerzeniu, do których mają dostęp strony internetowe lub inne rozszerzenia. Więcej informacji znajdziesz w artykule Dostępność stron internetowych.

Opcjonalne klawisze w 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ą obsługiwać rozszerzenia ChromeOS. Więcej informacji znajdziesz w file_handlers.
"file_system_provider_capabilities"
Umożliwia dostęp do interfejsu fileSystemProviderAPI, który umożliwia rozszerzeniom tworzenie systemów plików, których może używać ChromeOS.
"input_components"
Zezwala na używanie interfejsu Input Method Editor API. Więcej informacji znajdziesz w sekcji input_components.