瀏覽器外掛開發-manifest檔案解讀

調研資料

• manifest.json 官方文件
• Chrome Extension API
• 360瀏覽器的外掛文件 中文, 雖然核心差不多但是不一定與 Chrome api 一致, 可以作為參考
• Chrome 官方案例庫
• 案例
• 如何實現網頁和Chrome外掛之間的通訊
• 訊息傳遞

manifest.json 配置說明

manifest.json 用於描述 Chrome 外掛的源資料，配置資訊等，基本內容如下

{
    "name": "名稱",
    "description"
 
: "描述",
    "version": "打包完成後用於判斷外掛是否需要更新",
    "manifest_version": 2,
    "browser_action": {
        "default_popup": "xxx.html 右上角點選後的彈窗，可以用一個頁面定義",
        "default_icon": "xxx.png 顯示在右上角的圖示button"
    },
}

配置項簡介

1. manifest_version 必填

清單檔案格式的版本， Chrome 18 開發 寫 2 即可

2. name 必填

外掛名稱

3. version 必填

外掛版本，釋出新版本後，瀏覽器會比較其已安裝的外掛的版本，有更新的版本則會自動更新

4. description

外掛的描述，132個字元限制

5. icons

外掛的圖示，可以用在 Chrome 商店展示(128 * 128) | 外掛管理介面 (48 * 48) | 擴充套件頁圖示 (16 * 16) 最好是 png 格式

6. browser_action

可以用來定義點選圖示後展示的視窗，對應介面 chrome.browserAction，這項配置與 page_action

是對立的，只能二選一，以下是 browser_action 子項的配置

• default_icon: Object | string 一個或者一組圖示的路徑
• default_title 設定 tooltip
• default_popup 指定彈出的視窗，可以是任意 html
• badges “徽章” 就是小圖示上的一個標記，用來展示一些狀態

7. page_action

代表可以在當前頁面執行的操作，不活動時顯示灰色,對應介面 chrome.pageAction

• default_icon: Object | string 一個或者一組圖示的路徑
• 可用 pageAction.(show|hide) 改變外掛活動狀態

browser_action 和 page_action都用來定義放置在工具欄右上角的圖示點選情況，但是兩者的活動狀態展示 | 點選後的展示 | 主要負責場景是不一致的

猜測 browser_action 適用於使用者需要點選圖示後在彈窗中操作的場景 page_action 試用與在後臺執行，重要工作是監聽使用者行為的外掛

官方建議：如果要實現的功能只針對某一個頁面有用則建議使用 page_action 否則使用 browser_action

8. background

用來定義後臺指令碼部分

擴充套件是基於事件的程式，這些事件包括導航到新頁面、刪除書籤、或者關閉選項卡，擴充套件在他們的後臺指令碼中監視這些事件，然後用指定的指令進行響應

關於後臺指令碼的狀態

1. 首次下載後或者更新後被載入
2. 後臺指令碼下載後會處於休眠狀態，直到它偵聽的某個事件被觸發，
3. 偵聽到事件後，會使用指定的指令響應（怎麼相應自定義）

以下情況會需要呼叫到後臺指令碼

1. 擴充套件首次下載或者版本更新
2. 後臺指令碼中正在監聽事件，並且這事件被觸發了
3. content_script 或者其他擴充套件中呼叫了 sendMessage
4. 當前擴充套件中的其他部分，例如彈窗中呼叫了 runtime.getBackgroundPage

後臺指令碼定義選項

{
    ...
    "background": {
        "scripts": ["bg1.js", "bg2.js"], // 後臺指令碼可以註冊多個
        "persistent": false // 是否是持久的，一般為 false, 某些特殊情況需要參考文件 
    }
}

事件過濾器，有些事件支援事件過濾，比如選項卡的切換可以監聽

// background.js
chrome.webNavigation.onCompleted.addListener(function () {}, {
    url: [{urlMatches: 'http://www.baidu.com'}] // 過濾
});

9. chrome setting 修改 | chrome 使用者介面展示修改 | chrome 一些內建頁面的替換

1. setting 使用 chrome_settings_overrides 配置，詳細配置檢視文件
2. 使用者介面 使用 chrome_ui_overrides 配置，詳細配置檢視文件,可以設定一些書籤方面的規則
3. 內建頁面替換 使用 chrome_url_overrides 配置，詳細配置檢視文件，標籤頁、歷史頁、新 tab 都可替換

10. commands

可以通過 commands 選項定義觸發擴充套件事件的快捷鍵

{
    ...,
    commands: {
        "xxx": {
            "suggested_key": {
                "default": "Ctrl+X",
                "mac": "Command+X",
                "windows": "Ctrl+X"
            }
        },
        "_execute_browser_action": {...},
        "_execute_page_action": {...}
    }
}

操作快捷鍵後，外掛後臺會監聽到對應的事件

// background.js
chrome.commands.onCommand.addListener(function(command) {});

注意：\ _execute_browser_action \ _execute_page_action 這兩個命令不會被監聽，他們是觸發 popup 彈出的，要監聽 視窗彈出事件可以使用 popup_page 的onDomReady

11. content_scripts

content_script 在一個特殊的環境中執行，可以稱之為隔離環境，在這裡可以訪問所注入頁面的DOM，但是不能訪問裡邊的任何 javascript 變數和函式，反之，頁面中的js 也不能訪問 content_script 中的變數和函式

訪問目標網站的 DOM ，可以用來進行通訊

分為兩種情況，一種是宣告型注入指令碼，使用 content_scripts 配置項，另一種是程式設計方式注入使用 permissions: ["activeTab"] 選項，

1. 宣告型注入指令碼 content_scripts 值可以是一個數組，設定不同站點的不同注入檔案
   • 需要設定 matches: ["http://"] 指定匹配的網址，
   • js 設定注入指令碼
   • css 設定注入樣式
   • run_at 定義注入要本的時機 document_idle 表示瀏覽器幫你把握時機，會在 DOM 完成 與 window.onload 之後注入；document_start 在 CSS 注入之後，其他任何指令碼或者 DOM 之前注入；document.end DOM 完成之後立即注入，但是在影象等資源之前
2. 程式設計方式注入，不需要指定可訪問的域名，可以針對當前活動的選項卡執行，獲取臨時訪問許可權 permissions: ["tabs"] 程式設計方式注入會在 chrome.tabs.executeScript(tabId, details, callback) 介面中詳細介紹

通訊案例，通過 content_script 與頁面 共享 DOM，來實現頁面與擴充套件間的通訊

// page.js 頁面中觸發一個postMessage

document.getElementById('btn').addEventListener('click', () => {
    window.postMessage({type: 'TO_CONNECT_EXTERNAL', data: 'data'});
})

// content_script.js 中做中轉

var port = chrome.runtime.connect();

window.addEventListener('message', (e) => {
    if (e.source !== window) {return};

    if (event.data.type && (event.data.type == "FROM_PAGE")) {
        port.postMessage(event.data.data); // 發訊息給擴充套件
    }
}, false);

12. externally_connectable

這項配置直接實現網站與外掛間通訊，但是需要在 manifest.json 中作出如下配置

{
    "externally_connectable": {
        "matches": ["http://*.xx.com"] // 只有匹配的網站才可以通訊
    }
}

// page.js 中發出請求

var editorExtensionId = "abcdefghijklmnoabcdefhijklmnoabc";

chrome.runtime.sendMessage(
    editorExtensionId, 
    {type: 'MsgFromPage', msg: 'Hello, I am page~'}, 
    function(response) {
      console.log(response);
    }
);

// background.js

chrome.runtime.onMessageExternal.addListener(function(request, sender, sendResponse) {
  // 可以針對sender做一些白名單檢查
  // sendResponse返回響應
  if (request.type == 'MsgFromPage') {
    sendResponse({tyep: 'MsgFromChrome', msg: 'Hello, I am chrome extension~'});
  }
});

13. offline_enabled

擴充套件是否需要離線工作，預設為 true, 當chrome 檢測到離線時，程式會被高亮顯示

14. permissions | optional_permissions

宣告 許可權（外掛實現基礎功能所需要的） | 可選許可權 （外掛中可選的特性所需要的），兩者的子配置項是一樣的

選項的值是一個數組，代表每一個許可權，許可權可以是已知的許可權字串 也可以是一個主機的匹配模式
許可權字串大多都對應著一個同名的 chrome[permissionName] API,全部的許可權字串可以點選上邊連結檢視，一下列出常用的許可權

• activeTab 允許使用者在呼叫擴充套件時臨時訪問當前活動的選項卡，
• background 後臺許可權，可以用來增加Chrome 執行時間，即開機即執行（雖然是不可見的）
• bookmarks 書籤操作許可權
• browsingData 瀏覽器資料操作許可權，主要用來清除瀏覽器資料 cookie storage 等
• contentSettings 瀏覽器設定許可權
• contextMenus 上下文選單新增許可權
• cookies cookie 的查詢、修改、onChange 監聽
• history 瀏覽器歷史記錄操作許可權
• storage chrome.storage 的使用許可權（注意不是瀏覽器的 localStorage）
• tabs 選項卡許可權，允許建立、修改、重新排列選項卡
• webNavigation 請求進行過程中的操作許可權
• webRequest | webRequestBlocking 開放 正在執行請求的 攔截、阻塞、或修改的許可權

15. web_accessible_resources

指定打包資源的的路徑字串陣列，這些資源是在擴充套件中是可用了，例如 content_script會用到的資源等,

16. content_security_policy

內容安全策略, 預設的安全策略為 script-src 'self'; object-src 'self' 他會有如下限制

1. 禁止 eval 及相關函式
2. 禁止內聯<script>塊和內聯事件處理程式(例如，<button onclick="…">)
3. 只有擴充套件包內的指令碼和資源才會被載入！通過Web即時下載的將不會被載入

可以通過 白名單 使用萬用字元設定哪些外部資源是可以訪問的（僅支援 https），如下

"content_security_policy": "script-src 'self' https://*.xxx.com; object-src 'self'"