每个扩展程序的根目录中都必须包含一个 manifest.json
文件,其中会列出有关该扩展程序的结构和行为的重要信息。本页将介绍扩展程序清单的结构及其可以包含的功能。
示例
以下示例清单展示了基本的清单结构和一些常用功能,您可以从这里开始创建自己的清单:
最小清单
{
"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"]
}
清单键
以下是所有受支持的清单键的列表。
扩展平台所需的密钥
"manifest_version"
- 一个整数,用于指定扩展程序使用的清单文件格式版本。唯一支持的值是
3
。 "name"
- 一个字符串,用于在 Chrome 应用商店、安装对话框和用户的 Chrome 扩展程序页面 (
chrome://extensions
) 中标识扩展程序。长度上限为 75 个字符。如需了解如何使用特定于语言区域的名称,请参阅国际化。 "version"
- 用于标识扩展程序版本号的字符串。如需了解如何设置版本号的格式,请参阅版本。
Chrome 应用商店所需的密钥
"description"
- 一个字符串,用于描述 Chrome 应用商店和用户扩展程序管理页面上的扩展程序。长度上限为 132 个字符。如需了解如何将说明本地化,请参阅国际化。
"icons"
- 代表扩展程序的一个或多个图标。如需了解最佳做法,请参阅图标。
可选键
"action"
- 定义扩展程序图标在 Google 工具栏中的外观和行为。如需了解详情,请参阅
chrome.action
。 "author"
- 指定用于创建扩展程序的帐号的电子邮件地址。
"background"
- 指定包含扩展程序 Service Worker 的 JavaScript 文件,该 Service Worker 充当事件处理脚本。如需了解详情,请参阅扩展程序 Service Worker 简介。
"chrome_settings_overrides"
- 定义所选 Chrome 设置的替换项。如需了解详情,请参阅替换 Chrome 设置。
"chrome_url_overrides"
- 定义默认 Chrome 网页的替换值。如需了解详情,请参阅替换 Chrome 网页。
"commands"
- 定义扩展程序中的键盘快捷键。如需了解详情,请参阅 chrome.commands。
"content_scripts"
- 指定在用户打开某些网页时要使用的 JavaScript 或 CSS 文件。如需了解详情,请参阅内容脚本。
"content_security_policy"
- 定义对扩展程序可使用的脚本、样式和其他资源的限制。如需了解详情,请参阅内容安全政策。
"cross_origin_embedder_policy"
- 为 Cross-Origin-Embedder-Policy HTTP 标头指定值,该值用于配置在扩展程序页面中嵌入跨源资源。
"cross_origin_opener_policy"
- 指定 Cross-Origin-Opener-Policy HTTP 标头的值,可让您确保顶级扩展程序页面不会与跨源文档共享浏览上下文组。
"declarative_net_request"
- 定义 declarativeNetRequest API 的静态规则,以允许屏蔽和修改网络请求。
"default_locale"
- 一个字符串,用于定义支持多个语言区域的扩展程序的默认语言。例如“en”和“pt_BR”。此键在已本地化的扩展程序中是必需的,不得在未本地化的扩展程序中使用。如需了解详情,请参阅国际化。
"devtools_page"
- 定义使用 DevTools API 的页面。
"export"
- 允许从扩展程序导出资源。如需了解详情,请参阅导出。
"externally_connectable"
- 指定哪些其他网页和扩展程序可以连接到您的扩展程序。如需了解详情,请参阅
"externally_connectable"
。 "homepage_url"
- 一个字符串,用于指定扩展程序首页的网址。如未定义,则主页默认为扩展程序的 Chrome 应用商店页面。如果您在自己的网站上托管扩展程序,此字段会特别有用。
"host_permissions"
- 列出允许您的扩展程序与之互动的网页,使用网址匹配模式定义。系统会在安装应用时请求这些网站的用户权限。如需了解详情,请参阅主机权限。
"import"
- 允许将资源导入扩展程序。如需了解详情,请参阅导入。
"incognito"
- 定义扩展程序在无痕模式下的行为方式。支持的值包括
"spanning"
、"split"
和"not_allowed"
。如需了解详情,请参阅无痕模式。 "key"
- 指定用于各种开发用例的扩展程序 ID。如需了解详情,请参阅键。
"minimum_chrome_version"
- 定义可安装扩展程序的最低 Chrome 版本。该值必须是现有 Chrome 浏览器版本字符串的子字符串,例如
"107"
或"107.0.5304.87"
。如果用户的 Chrome 版本低于最低版本,则会在 Chrome 应用商店中看到“不兼容”警告,并且无法安装您的扩展程序。如果您将此扩展程序添加到现有扩展程序,则 Chrome 版本较低的用户不会收到您的扩展程序的自动更新。这包括处于临时模式的企业用户。 "oauth2"
- 允许使用 OAuth 2.0 安全 ID。此键的值必须是具有
"client_id"
和"scopes"
属性的对象。如需了解详情,请参阅 OAuth 2.0 教程。 "omnibox"
- 允许此扩展程序在 Chrome 地址栏中注册关键字。如需了解详情,请参阅多功能框。
"optional_host_permissions"
- 为您的扩展程序声明可选的主机权限。
"optional_permissions"
- 为您的扩展程序声明可选权限。
"options_page"
- 指定 options.html 文件的路径,以使扩展程序用作选项页面。如需了解详情,请参阅为用户提供选项。
"options_ui"
- 指定 HTML 文件的路径,该文件允许用户从 Chrome 扩展程序页面更改扩展程序选项。如需了解详情,请参阅嵌入式选项。
"permissions"
- 允许使用特定的扩展程序 API。如需了解一般说明,请参阅权限。各个 API 的参考页面列出了它们所需的权限。
"requirements"
- 列出使用扩展程序所需的技术。如需查看受支持要求的列表,请参阅要求。
"sandbox"
- 定义一组无权访问扩展程序 API 或直接访问非沙盒化页面的扩展程序页面。如需了解详情,请参阅沙盒。
"short_name"
- 一个字符串,其中包含在字符空间有限时要使用的扩展名称的缩写版本。长度上限为 12 个字符。如果未指定,则会显示“name”键的截断版本。
"side_panel"
- 标识要在 sidePanel 中显示的 HTML 文件。
"storage"
- 为代管式存储区域声明 JSON 架构。如需了解详情,请参阅存储区域的清单。
"tts_engine"
- 将扩展程序注册为文字转语音引擎。如需了解详情,请参阅 ttsEngine API。
"update_url"
- 一个字符串,包含扩展程序的更新页面的网址。如果您在 Chrome 应用商店之外托管扩展程序,请使用此密钥。
"version_name"
- 一个描述扩展程序版本的字符串。例如
"1.0 beta"
和"build rc2"
。如果未指定,则“版本”值会显示在扩展程序管理页面上。 "web_accessible_resources"
- 定义扩展程序中可由网页或其他扩展程序访问的文件。如需了解详情,请参阅可通过 Web 访问的资源。
可选的 ChromeOS 密钥
"file_browser_handlers"
- 提供对
fileBrowserHandler
API 的访问权限,该 API 可让扩展程序访问 ChromeOS 文件浏览器。 "file_handlers"
- 指定让 ChromeOS 扩展程序处理的文件类型。如需了解详情,请参阅
file_handlers
。 "file_system_provider_capabilities"
- 允许访问
fileSystemProvider
API,以便扩展程序创建 ChromeOS 可以使用的文件系统。 "input_components"
- 允许使用 Input Method Editor API。如需了解详情,请参阅
input_components
。