Format pliku manifestu

Każde rozszerzenie musi mieć w katalogu głównym plik manifest.json, który zawiera ważne informacje o strukturze i działaniu rozszerzenia. Z tej strony dowiesz się, jak wygląda struktura manifestów rozszerzeń i jakie funkcje mogą one zawierać.

Przykłady

Poniższe przykłady manifestów pokazują podstawową strukturę manifestu i niektóre często używane funkcje. Możesz je wykorzystać jako punkt wyjścia do utworzenia własnego 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"
  }
}

{
  "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//"
      ]
    }
  ]
}

{
  "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"
  ]
}

{
  "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 znajdziesz listę wszystkich obsługiwanych kluczy manifestu.

Klucze wymagane przez platformę rozszerzeń

"manifest_version"

Liczba całkowita określająca wersję formatu pliku manifestu używanego przez rozszerzenie. Jedyną obsługiwaną wartością jest 3.

"name"

Ciąg znaków, który identyfikuje rozszerzenie w Chrome Web Store, oknie instalacji i na stronie rozszerzeń Chrome (chrome://extensions). Maksymalna długość to 75 znaków. Więcej informacji o używaniu nazw dostosowanych do ustawień regionalnych, zobacz Internacjonalizacja.

"version"

Ciąg znaków, który identyfikuje numer wersji rozszerzenia. Więcej informacji o formatowaniu numeru wersji znajdziesz w artykule Wersja.

Klucze wymagane przez Chrome Web Store

"description"

Ciąg znaków, który opisuje rozszerzenie w Chrome Web Store i na stronie zarządzania rozszerzeniami użytkownika. Maksymalna długość to 132 znaki. Więcej informacji o lokalizowaniu opisów znajdziesz w artykule o internacjonalizacji.

"icons"

Co najmniej 1 ikona reprezentująca rozszerzenie. Więcej informacji o sprawdzonych metodach znajdziesz w artykule Icons.

Klucze opcjonalne

"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 JavaScript zawierający skrypt service worker rozszerzenia, który działa jako moduł obsługi zdarzeń. Więcej informacji znajdziesz w artykule 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 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 artykule 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 dotyczące zawartoś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 artykule Zasady bezpieczeństwa treści.

"cross_origin_embedder_policy"

Określa wartość nagłówka HTTP Cross-Origin-Embedder-Policy, który konfiguruje osadzanie zasobów z innych domen na stronie rozszerzenia.

"cross_origin_opener_policy"

Określa wartość nagłówka HTTP Cross-Origin-Opener-Policy, która pozwala zapewnić, że strona rozszerzenia najwyższego poziomu nie będzie współdzielić grupy kontekstu przeglądania z dokumentami z innych domen.

"declarative_net_request"

Określa statyczne reguły interfejsu declarativeNetRequest API, który umożliwia blokowanie i modyfikowanie żądań sieciowych.

"default_locale"

Ciąg znaków, który określa domyślny język rozszerzenia obsługującego wiele ustawień regionalnych. Przykłady: „en” i „pt_BR”. Ten klucz jest wymagany w rozszerzeniach zlokalizowanych i nie może być używany w rozszerzeniach, które nie są zlokalizowane. Więcej informacji znajdziesz w artykule o internacjonalizacji.

"devtools_page"

Określa strony, które używają interfejsów DevTools API.

"export"

Umożliwia eksportowanie zasobów z rozszerzenia. Więcej informacji znajdziesz w artykule 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 ta wartość jest niezdefiniowana, strona główna domyślnie będzie stroną rozszerzenia w Chrome Web Store. To pole jest szczególnie przydatne, jeśli hostujesz rozszerzenie w swojej witrynie.

"host_permissions"

Zawiera listę stron internetowych, z którymi rozszerzenie może wchodzić w interakcje. Są one zdefiniowane za pomocą wzorców dopasowania adresów URL. Uprawnienia użytkownika do tych witryn są wymagane podczas instalacji. Więcej informacji znajdziesz w artykule Uprawnienia hosta.

"import"

Umożliwia 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 w różnych przypadkach użycia podczas programowania. Więcej informacji znajdziesz w artykule Klucz.

"mime_types_handler"

Rejestruje rozszerzenie jako moduł obsługi obsługiwanych typów MIME, takich jak application/pdf. Więcej informacji znajdziesz w artykule mimeHandler API.

"minimum_chrome_version"

Określa najstarszą wersję Chrome, w której można zainstalować rozszerzenie. Wartość musi być podciągiem istniejącego ciągu wersji przeglądarki Chrome, np. "107" lub "107.0.5304.87". Użytkownicy, którzy mają wersję Chrome starszą niż minimalna, zobaczą w Chrome Web Store ostrzeżenie „Niekompatybilne” i nie będą mogli zainstalować rozszerzenia. Jeśli dodasz ten klucz do istniejącego rozszerzenia, użytkownicy, którzy mają starszą wersję Chrome, nie będą otrzymywać automatycznych aktualizacji rozszerzenia. Dotyczy to też użytkowników biznesowych w trybie tymczasowym.

"oauth2"

Umożliwia używanie identyfikatora zabezpieczeń OAuth 2.0. Wartość tego klucza musi być obiektem z "client_id" i "scopes" właściwościami. Więcej informacji znajdziesz w samouczku OAuth 2.0.

"omnibox"

Umożliwia rozszerzeniu zarejestrowanie słowa kluczowego na pasku adresu w Chrome. Więcej informacji znajdziesz w artykule Omniboks.

"optional_host_permissions"

Deklaruje opcjonalne uprawnienia hosta dla rozszerzenia.

"optional_permissions"

Deklaruje opcjonalne uprawnienia dla rozszerzenia.

"options_page"

Określa ścieżkę do pliku options.html, którego rozszerzenie ma używać jako strony opcji. Więcej informacji znajdziesz w artykule Udostępnianie opcji użytkownikom.

"options_ui"

Określa ścieżkę do pliku HTML, który umożliwia użytkownikowi zmianę opcji rozszerzenia na stronie rozszerzeń Chrome. Więcej informacji znajdziesz w artykule Opcje osadzone.

"permissions"

Umożliwia korzystanie z określonych interfejsów API rozszerzeń. Ogólne wyjaśnienie znajdziesz w artykule Uprawnienia. Na stronach referencyjnych poszczególnych interfejsów API znajdziesz listę uprawnień, których wymagają.

"requirements"

Zawiera listę technologii wymaganych do korzystania z rozszerzenia. Listę obsługiwanych wymagań znajdziesz w artykule Wymagania.

"sandbox"

Określa zestaw stron rozszerzenia, które nie mają dostępu do interfejsów API rozszerzeń ani bezpośredniego dostępu do stron spoza piaskownicy. Więcej informacji znajdziesz w artykule Piaskownica.

"short_name"

Ciąg znaków zawierający skróconą wersję nazwy rozszerzenia, która ma być używana, gdy liczba znaków jest ograniczona. Maksymalna długość to 12 znaków. Jeśli ta wartość jest niezdefiniowana, zamiast niej wyświetla się skrócona wersja wartości klucza „name”.

"side_panel"

Identyfikuje plik HTML, który ma być wyświetlany w sidePanel.

"storage"

Deklaruje schemat JSON dla zarządzanego obszaru pamięci. Więcej informacji znajdziesz w artykule Manifest dla obszarów pamięci.

"tts_engine"

Rejestruje rozszerzenie jako mechanizm zamiany tekstu na mowę. Więcej informacji znajdziesz w artykule ttsEngine API.

"update_url"

Ciąg znaków zawierający adres URL strony aktualizacji rozszerzenia. Użyj tego klucza, jeśli hostujesz rozszerzenie poza Chrome Web Store.

"version_name"

Ciąg znaków opisujący wersję rozszerzenia. Przykłady: "1.0 beta" i "build rc2". Jeśli ta wartość nie jest określona, na stronie zarządzania rozszerzeniami wyświetla się wartość „version”.

"web_accessible_resources"

Określa pliki w rozszerzeniu, do których mogą mieć dostęp strony internetowe lub inne rozszerzenia. Więcej informacji znajdziesz w artykule Zasoby dostępne w internecie.

Opcjonalne klucze ChromeOS

"file_browser_handlers"

Umożliwia dostęp do interfejsu fileBrowserHandler API, który pozwala rozszerzeniom uzyskiwać dostęp do przeglądarki plików ChromeOS.

"file_handlers"

Określa typy plików, które mają być obsługiwane przez rozszerzenia ChromeOS. Więcej informacji znajdziesz w artykule zobacz file_handlers.

"file_system_provider_capabilities"

Umożliwia dostęp do interfejsu fileSystemProvider API, który pozwala rozszerzeniom tworzyć systemy plików, z których może korzystać ChromeOS.

"input_components"

Umożliwia korzystanie z interfejsu Input Method Editor API. Więcej informacji znajdziesz w artykule input_components.