お断り (2022-12-13 追記)
この記事はマニフェストのバージョンが2の時点で作成したものですが、マニフェストの最新バージョンは3であり、Chrome Web Store においてはバージョン2の拡張機能が すでに受け付けられない状態 です。
それでもなおこの記事を参照される場合は、公式の マイグレーションガイド も合わせてご確認いただければと思います。
Overview
https://developer.chrome.com/extensions/manifest についての自分用おぼえがきです。 マニフェストファイルの書き方にフォーカスしていますので、個々の用語の説明などは端折ったりしています。記載が必須の項目
以下の項目は、マニフェストファイルに必須です。manifest_version
マニフェストファイル自身のバージョンです。 現在のバージョンは2で、なおかつ現在有効なバージョンは2しかありません。 なので、とにかくmanifest.json
"manifest_version": 2
manifest.json
"name": "Extension name"
また、これは必須ではないですが、short_name で略称を定義することもできます。12 文字までが推奨されます。
manifest.json
"short_name": "Ext name"
version
拡張機能のバージョンです。
1から4つの数値を dot で区切って並べて作ることができます。それぞれの数値は 0 から 65535 までの範囲を取ることができます。
0 以外の数字の前に 0 をつけることはできません。つまり "032" などはできません。
拡張機能の自動更新機能でバージョンの上下関係がチェックされるので、適当に付けてはいけないし、拡張機能を更新する際には必ずバージョンが上がってなくてはなりません。
manifest.json
"version": "1.0.12.3456"
バージョンの比較
バージョン間の比較をする際は、ドット区切りのより左にあるバージョンが優先されます。つまり
1.1 は 1.0.9999 より上位のバージョンとみなされます。
区切りが4つ未満の時は、足りない部分は 0 が入っているとみなされます。なので 1.1.0.1 は 1.1 より上位のバージョンとなります。
記載が推奨される項目
以下の項目は、必須ではありませんが、記載することが推奨されています。default_locale
拡張機能のデフォルトの言語を指定します。manifest.json
"default_locale": "ja_JP"
この項目の必要性はちょっと特殊で、当該拡張機能が I18N に対応している場合︵_locales ディレクトリ以下が存在する場合︶は記載が必須、そうでない場合は記載 してはいけません 。
description
拡張機能の説明文です。132 文字まで。I18N に対応しています。manifest.json
"description": "a extention for Google Chrome",
icons
拡張機能のアイコンです。サイズは 128x128, 48x48, 16x16 があるといいようです。それぞれ、Chrome ウェブストアや拡張機能の管理ページやファビコンなどに使われます。
画像の形式は png が推奨されています。
manifest.json
"icons": {
"16": "icon16.png",
"48": "icon48.png",
"128": "icon128.png"
},
どちらか一つ（またはどちらも選ばない）
manifest.json
"browser_action": {
"default_icon": {
"19": "icon19.png"
},
"default_title": "Ext title",
"default_popup": "popup.html"
},
子要素
default_icon browser_action に対する任意の項目で、アドレスバーの右に表示するアイコンを指定します。サイズは 19px が推奨されます。︵大きいサイズのアイコンを指定した場合、表示サイズに縮小されます。︶ default_title browser_action に対する任意の項目で、アドレスバーの右に表示するアイコンから出るツールチップに表示される文字列です。省略すると、name が使われます。 default_popup browser_action に対する任意の項目で、アドレスバーの右に表示するアイコンをクリックした際に表示されるポップアップの中の html を指定します。page_action
ページアクションを使用する場合に記載します。manifest.json
"page_action": {
"default_icon": {
"19": "icon19.png"
},
"default_title": "Ext title",
"default_popup": "popup.html"
},
browser_action が page_action になった以外は、マニフェストファイルの書式としては同じです。
オプション項目
以下の項目は必要に応じて追加します。
content_scripts
コンテントスクリプトを使用する場合に記載します。
manifest.json
"content_scripts": [
{
"matches": [ "http://*/*", "https://*/*" ],
"js": [ "script.js" ]
}
],
子要素
matches content_scripts に対する必須の項目で、動作対象となる URL を Match Patterns の形式で設定します。もちろんリストです。 js content_scripts に対する任意の項目で、動作させるスクリプトをリストで設定します。background
バックグラウンドページまたはイベントページを使用する場合に記載します。 注意‥バックグラウンドページの解説ページの冒頭に警告が記載されているとおり、バックグラウンドページの使用は推奨されていません。可能な限りイベントページを使用するようにしましょう。manifest.json
"background": {
"scripts": [ "background.js" ],
// recommended
"persistent": false
},
子要素
- scripts
- バックグラウンドで動作する JavaScript ファイルを設定します。 複数のファイルが使えるので、設定値はファイル名のリストになることに注意。
- persistent
- `"persistent": false` が含まれる場合がイベントページで、それ以外がバックグラウンドページとなります。`persistent` というキーワードでわかるように、バックグラウンドページは永続的に裏で動き続けるのに対して、イベントページにすると必要に応じてのみロードされるようになります。そのため、可能な限りイベントページを使用することが推奨されています。
permissions
主に chrome.* API を使うときなどに、使う対象を設定する必要があります。
設定できるパーミッションの一覧
manifest.json
"permissions": [
"tabs",
"bookmarks"
],
options_page
オプションページを使用する場合に設定します。
manifest.json
"options_page": "options.html",
minimum_chrome_version
拡張機能が最低限必要とする Chrome のバージョンを設定します。特定のバージョン以降でしか動かない機能を使っているのなら設定します。
homepage_url
拡張機能のホームページの URL を設定します。 ウェブストアや拡張機能の管理ページや、ブラウザアクションを使用している場合、アイコンを右クリックした時に出るメニューの一番上のタイトルをクリックした時の遷移先などにも使用されます。わかる人・必要な人だけが設定すればいい項目
content_security_policy
Content Security Policy を設定します。 下記の設定例がデフォルトの設定となります。manifest.json
"content_security_policy": "script-src 'self'; object-src 'self'",
外部との接続を許可したりする場合に設定を変更する項目であり、うかつな設定はセキュリティに直接関わってきます。
セキュリティについての知識が足りず意味がわからないという人はこの設定を触るべきではありません。また、ローカルで閉じていて eval やインラインスクリプトを使わない拡張機能を作る分にはそもそも設定する必要はありません。