格式：Manifest文件 · Chrome 擴展開發文檔

# 格式：Manifest文件 ## 目錄 1. [字段說明](#overview_) 2. [字段的含義](#details) 1. [app](#app) 2. [default_locale](#default_locale) 3. [description](#description) 4. [homepage_url](#homepage_url) 5. [icons](#icons) 6. [incognito](#incognito) 7. [intents](#intents) 8. [key](#key) 9. [minimum_chrome_version](#minimum_chrome_version) 10. [name](#name) 11. [nacl_modules](#nacl_modules) 12. [offline_enabled](#offline_enabled) 13. [permissions](#permissions_) 14. [requirements](#requirements) 15. [version](#version) 16. [manifest_version](#manifest_version) 17. [web_accessible_resources](#web_accessible_resources) 每一個擴展、可安裝的WebApp、皮膚，都有一個[JSON](http://www.json.org/)格式的manifest文件，叫manifest.json，里面提供了重要的信息。 <a name="overview_">?</a> ## 字段說明下面的JSON示例了manifest支持的字段，每個字段都有連接指向專有的說明。必須的字段只有：name和version。 ``` { _// 必須的字段_ "[name](#name)": "_My Extension_", "[version](#version)": "_versionString_", "[manifest_version](#manifest_version)": 2, _// 建議提供的字段_ "[description](#description)": "_A plain text description_", "[icons](#icons)": { ... }, "[default_locale](#default_locale)": "_en_", _// 多選一，或者都不提供_ "[browser_action](browserAction.html)": {...}, "[page_action](pageAction.html)": {...}, "[theme](themes.html)": {...}, "[app](#app)": {...}, _// 根據需要提供_ "[background](background_pages.html)": {...}, "[chrome_url_overrides](override.html)": {...}, "[content_scripts](content_scripts.html)": [...], "[content_security_policy](contentSecurityPolicy.html)": "_policyString_", "[file_browser_handlers](http://code.google.com/chrome/extensions/fileBrowserHandler.html)": [...], "[homepage_url](#homepage_url)": "http://_path/to/homepage_", "[incognito](#incognito)": "spanning" _or_ "split", "[intents](#intents)": {...} "[key](#key)": "_publicKey_", "[minimum_chrome_version](#minimum_chrome_version)": "_versionString_", "[nacl_modules](#nacl_modules)": [...], "[offline_enabled](#offline_enabled)": true, "[omnibox](omnibox.html)": { "keyword": "_aString_" }, "[options_page](options.html)": "_aFile_.html", "[permissions](#permissions_)": [...], "[plugins](npapi.html)": [...], "[requirements](#requirements)": {...}, "[update_url](autoupdate.html)": "http://_path/to/updateInfo_.xml", "[web_accessible_resources](#web_accessible_resources)": [...] } ``` ## 字段的含義部分字段的詳細的含義如下： ### app 可安裝的webapp，包括打包過的app，需要這個字段來指定app需要使用的url。最重要的是app的啟動頁面------當用戶在點擊app的圖標后，瀏覽器將導航到的地方。更詳細的信息，請參考文檔[hosted apps](developers_guide.html)和[packaged apps](http://code.google.com/chrome/extensions/apps.html).： ### default_locale 指定這個擴展保的缺省字符串的子目錄：_lcoales。如果擴展有_locales目錄，這個字段是必須的。如果沒有_locales目錄，這個字段是必須不存在的。具體見[Internationalization](i18n.html).。 ### description 描述擴種的一段字符串（不能是html或者其他格式，不能超過132個字符）。這個描述必須對瀏覽器擴展的管理界面和[Chrome Web Store](https://chrome.google.com/webstore)都合適。你可以指定本地相關的字符串，具體參考:[Internationalization](i18n.html)。 ### homepage_url 這個擴展的主頁 url。擴展的管理界面里面將有一個鏈接指向這個url。[如果你將擴展放在自己的網站上](hosting.html)，這個url就很有用了。如果你通過了[Extensions Gallery](https://chrome.google.com/extensions)和[Chrome Web Store](https://chrome.google.com/webstore)來分發擴展，主頁缺省就是擴展的頁面。 ### icons 一個或者多個圖標來表示擴展，app，和皮膚。你通常可以提供一個128x128的圖標，這個圖標將在webstore安裝時候使用。擴展需要一個48x48的圖標，擴展管理頁面需要這個圖標。同時，你還可以提供給一個16x16的圖標作為擴頁面的fa網頁圖標。這個16x16的圖標，還將顯示在實驗性的擴展[infobar](http://code.google.com/chrome/extensions/experimental.infobars.html)特性上。圖標要求是png格式，因為png格式是對透明支持最好的。你也可以用其他webkit支持的格式，如BMP,GIF,ICON和JPEG。下面有個例子： ``` "icons": { "16": "icon16.png", "48": "icon48.png", "128": "icon128.png" }, ``` 注意：請只使用文檔說明的圖標大小。可能你已經注意到了，chrome有時候會將這些圖標尺寸變小，比如，安裝對話框將128-像素圖標縮小為69-像素了。然而，Chrome的界面細節可能每個版本都不一樣，但每次變動都假設開發者使用的是文檔標注過的尺寸。如果你使用了其他的尺寸，你的圖標可能看起來很丑，在將來的某個版本中。如果你使用[Chrome Developer Dashboard](https://chrome.google.com/webstore/developer/dashboard)上傳你的擴展、app、皮膚，你需要上傳附帶的圖片，包括至少一張擴展的縮略圖。更多信息請參考：[Chrome Web Store developer documentation](http://code.google.com/chrome/webstore/)。 ### incognito 可選值："spanning"和"split"，指定當擴展在允許隱身模式下運行時如何響應。擴展的缺省值是Spanning，這意味著擴展將在一個共享的進程里面運行。隱身標簽頁的事件和消息都會發送到這個共享進程，來源通過incognito標志來區分。可安裝的webapp的缺省值是split，這個意思是隱身模式下的webapp都將運行在他們自己的隱身進程中。如果app或擴展有背景頁面，也將運行在隱身進程中。隱身進程和普通進程一樣，只是cookie保存在內存中而已。每個進程只可看到和自己相關的事件和消息（比如，隱身進程只能看到隱身標簽也更新）。這些進程之間不能互相通信。根據經驗，如果你的擴展或app需要在隱身瀏覽器里面開一個標簽頁，使用split；如果你的擴展或app需要登記錄到遠程服務器或者本地永久配置，用spanning。 ### intents 一個字典，用于描述擴展或app所提供的全部intent handler。字典里的每個鍵指定了一個action verb。下面這個例子為"[http://webintents.org/share](http://webintents.org/share)"這個action verb指定了2個的intent handler。 ``` { "name": "test", "version": "1", "intents": { "http://webintents.org/share": [ { "type": ["text/uri-list"], "href": "/services/sharelink.html", "title" : "Sample Link Sharing Intent", "disposition" : "inline" }, { "type": ["image/*"], "href": "/services/shareimage.html", "title" : "Sample Image Sharing Intent", "disposition" : "window" } ] } } ``` “type”指定handler所支持的一組MIME。 “href”指定了處理intent的頁面URL。對于托管的apps，這個URL必須在屬于允許URL集。對于擴展，這個頁面必須是擴展自帶的，其URL是相對擴展根目錄的相對路徑。當用戶觸發handler對應的動作時，“title”會顯示在intent選擇界面中。 “disposition”可以是“inline”或“window”。當intent被觸發時，“window”表示將在一個新標簽中打開，而“inline”表示直接在當前標簽頁打開。更多Web Intent信息請參考網站： [Web Intents specification](http://dvcs.w3.org/hg/web-intents/raw-file/tip/spec/Overview.html) 和 [webintents.org](http://www.webintents.org)。 ### key 開發時為擴展指定的唯一標識值。注意：通常您并不需要直接使用這個值，而是在您的代碼中使用相對路徑或者[chrome.extension.getURL()](extension.html#method-getURL)得到的絕對路徑。這個值并不是開發時顯式指定的，而是Chrome在安裝`.crx`時輔助生成的。(開發時可以通過[上傳擴展](https://chrome.google.com/webstore/developer/dashboard)或者[手工打包](packaging.html)生成crx文件)。安裝完crx，在Chrome的[用戶數據目錄](http://www.chromium.org/user-experience/user-data-directory)下的`Default/Extensions/_<extensionId>_/_<versionString>_/manifest.json`文件中，您可以看到這個擴展的key。 ### minimum_chrome_version 擴展，app或皮膚需要的chrome的最小版本，如果有這個需要的話。這個字符串的格式和 [version](manifest.html#version)字段一樣。 ### name 用來標識擴展的簡短純文本。這個文字將出現在安裝對話框，擴展管理界面，和[store](https://chrome.google.com/webstore)里面。你可以指定一個本地相關的字符串為這個字段，具體參考：[Internationalization](i18n.html)。 ### nacl_modules 一個或多個從MIME到處理這個MIME的本地客戶端模塊之間的映射。例如，下段代碼中加粗部分將一個本地客戶端模塊注冊為處理OpenOffice電子表格MIME。 ``` { "name": "Native Client OpenOffice Spreadsheet Viewer", "version": "0.1", "description": "Open OpenOffice spreadsheets, right in your browser.", **"nacl_modules": [{ "path": "OpenOfficeViewer.nmf", "mime_type": "application/vnd.oasis.opendocument.spreadsheet" }]** } ``` "path" 指定一個NaCl 的manifest（就像擴展有各自的manifest一樣，NaCl 也有自己的manifest文件，不同的是NaCl 的以`.nmf`作為后綴）。這個路徑是相對于擴展根目錄的。更多NaCl 信息和`.nmf` 文件格式請參考[NaCl 技術概述](http://code.google.com/chrome/nativeclient/docs/technical_overview.html)。一個MIME只能與一個“.nmf”文件關聯，但一個“.nmf”文件可處理多個MIME。下面例子的擴展有2個“.nmf”文件，但處理了3個MIME。 ``` { "name": "Spreadsheet Viewer", "version": "0.1", "description": "Open OpenOffice and Excel spreadsheets, right in your browser.", "nacl_modules": [{ "path": "OpenOfficeViewer.nmf", "mime_type": "application/vnd.oasis.opendocument.spreadsheet" }, { "path": "OpenOfficeViewer.nmf", "mime_type": "application/vnd.oasis.opendocument.spreadsheet-template" }, { "path": "ExcelViewer.nmf", "mime_type": "application/excel" }] } ``` **注意：**擴展不在manifest中指定“nacl_modules”也可以使用NaCl。僅在擴展希望自己的NaCl 被瀏覽器知道并用于顯示關聯的MIME內容時才需要指定。 ### offline_enabled 指定本擴展或app是否支持脫機運行。當Chrome檢測到處于脫機狀態，此項設置為“是”的app將會在新標簽頁中高亮顯示。 ### permissions 擴展或app將使用的一組權限。每個權限是一列已知字符串列表中的一個，如geolocatioin或者一個匹配模式，來指定可以訪問的一個或者多個主機。權限可以幫助限定危險，如果你的擴展或者app被攻擊。一些權限在安裝之前，會告知用戶，具體參考：[Permission Warnings](http://code.google.com/chrome/extensions/permission_warnings.html). 如果一個擴展api需要你的聲明一個權限在manifest文件，一般的，api的文檔將告訴怎么做。例如，[Tabs](tabs.html)頁面告訴你這么聲明一個tabs權限。這是一個擴展的manifest文件的權限設置的一部分。 ``` "permissions": [ "tabs", "bookmarks", "http://www.blogger.com/", "http://*.google.com/", "unlimitedStorage" ], ``` 下面的表格列舉了一個擴展或者app可以使用的權限。注意：托管的app能使用權限:xxx,其他的都不能使用。 | Permission | Description | | --- | --- | | _match pattern_ | Specifies a_host permission_. Required if the extension wants to interact with the code running on pages. Many extension capabilities, such as [cross-origin XMLHttpRequests](xhr.html),[programmatically injected content scripts](content_scripts.html#pi), and [the cookies API](cookies.html) require host permissions. For details on the syntax, see [Match Patterns](match_patterns.html). | | "background" | Makes Chrome start up early and and shut down late, so that apps and extensions can have a longer life. When any installed hosted app, packaged app, or extension has "background" permission, Chrome runs (invisibly) as soon as the user logs into their computer—before the user launches Chrome. The "background" permission also makes Chrome continue running (even after its last window is closed) until the user explicitly quits Chrome. **Note:**Disabled apps and extensions are treated as if they aren't installed. You typically use the "background" permission with a [background page](background_pages.html) or (for hosted apps) a [background window](http://code.google.com/chrome/apps/docs/background.html). | | "bookmarks" | Required if the extension uses the [chrome.bookmarks](bookmarks.html) module. | | "chrome://favicon/" | Required if the extension uses the "chrome://favicon/_url_" mechanism to display the favicon of a page. For example, to display the favicon of http://www.google.com/, you declare the "chrome://favicon/" permission and use HTML code like this: `<img src='chrome://favicon/http://www.google.com/' />` | | "contextMenus" | Required if the extension uses the [chrome.contextMenus](contextMenus.html) module. | | "cookies" | Required if the extension uses the [chrome.cookies](cookies.html) module. | | "experimental" | Required if the extension uses any [chrome.experimental.* APIs](http://code.google.com/chrome/extensions/experimental.html). | | "geolocation" | Allows the extension to use the proposed HTML5 [geolocation API](http://dev.w3.org/geo/api/spec-source.html) without prompting the user for permission. | | "history" | Required if the extension uses the [chrome.history](history.html) module. | | "idle" | Required if the extension uses the [chrome.idle](http://code.google.com/chrome/extensions/idle.html) module. | | "management" | Required if the extension uses the [chrome.management](management.html) module. | | "notifications" | Allows the extension to use the proposed HTML5 [notification API](http://www.chromium.org/developers/design-documents/desktop-notifications/api-specification) without calling permission methods (such ascheckPermission()). For more information see [Desktop Notifications](notifications.html). | | "tabs" | Required if the extension uses the [chrome.tabs](tabs.html) or [chrome.windows](windows.html) module. | | "unlimitedStorage" | Provides an unlimited quota for storing HTML5 client-side data, such as databases and local storage files. Without this permission, the extension is limited to 5 MB of local storage. **Note:**This permission applies only to Web SQL Database and application cache (see issue [58985](http://crbug.com/58985)). Also, it doesn't currently work with wildcard subdomains such ashttp://*.example.com. | ### requirements 指定本app或擴展所需的特殊技術功能。安裝擴展時，擴展商店根據這個清單，必要時勸阻用戶在不支持所需功能的電腦上安裝這些擴展。目前只支持指定“3D”，也就是GPU加速。您可以指定所需的3D相關功能，比如： ``` "requirements": { "3D": { "features": ["css3d", "webgl"] } } ``` "css3d"的詳細信息請參考[CSS 3D Transforms 規范](http://www.w3.org/TR/css3-3d-transforms/)，"webgl"請參考[WebGL API](http://www.khronos.org/webgl/)。 Chrome 3D功能的支持情況請參考[WebGL and 3D graphics](http://www.google.com/support/chrome/bin/answer.py?answer=1220892)。未來可能會增加更多技術功能的檢測指定。 ### version 擴展的版本用一個到4個數字來表示，中間用點隔開。這些數字有些規則：必須在0到65535之間，非零數字不能0開頭，比如，99999和032是不合法的。下面是一些版本字符串例子： * "version": "1" * "version": "1.0" * "version": "2.10.2" * "version": "3.1.2.4567" 自動升級系統將比較版本來確定一個已經安裝的擴展是否需要升級。如果一個發布的擴展有一個更新的版本字符串，比一個安裝的擴展，這個擴展將自動升級。版本字符串從比較從左邊開始。如果這些數字相等，這個數字的右邊的數字將被比較，這樣持續下去。比如：1.2.0就比1.1.9.9999更新。缺少的數字將用0來代替。例子，1.1.9.9999就比1.1.更新。具體信息請參考[Autoupdating](autoupdate.html)。 ### manifest_version 用整數表示manifest文件自身格式的版本號。從Chrome 18開始，開發者應該（不是必須，但是2012年底左右就必須了）指定版本號為2（沒有引號），如下所示： ``` "manifest_version": 2 ``` manifest版本1從Chrome 18才開始逐步被棄用，版本2目前并不是必須的，但預計我們將在2012年底強制只支持版本2。還沒有準備好支持manifest版本2的擴展、應用和主題，可以明確指定版本1，或者索性不提供本字段。版本1到2之間的變化細節可以參考[`manifest_version`文檔。](http://code.google.com/chrome/extensions/manifestVersion.html) 在Chrome17（極速5.2）或之前的指定版本2將會發生不可預料的事情。 ### web_accessible_resources 一組字符串，指定本擴展在注入的目標頁面上所需使用的資源的路徑（相對于擴展的安裝根目錄）。例如，擴展在example.com上注入腳本以構建制界面，將其間所需的資源（圖片、圖標、樣式、腳本等）加入白名單，如下所示： ``` { ... "web_accessible_resources": [ "images/my-awesome-image1.png", "images/my-amazing-icon1.png", "style/double-rainbow.css", "script/double-rainbow.js" ], ... } ``` 這些資源的訪問URL是 `chrome-extension://[PACKAGE ID]/[PATH]`，可通過調用`chrome.extension.getURL`構造出。這些白名單資源是通過[CORS](http://www.w3.org/TR/cors/)頭提供的，因此可被類似XHR這樣的機制使用。擴展的content scripts自身不需要加入白名單 #### 資源的缺省可用性 manifest_version為2的擴展，缺省將不能使用除web_accessible_resources中指定外的任何其它任何擴展包內資源。 manifest_version為1的擴展，缺省仍可訪問任何擴展包內資源。_但是_，一旦指定web_accessible_resources，將也只能訪問其中指定的資源。