瀏覽器外掛開發-常用API

調研資料

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

常用 API

1. chrome.runtime

管理 background 返回關於清單的詳細資訊，並偵聽和響應應用程式或擴充套件生命週期中的事件。您還可以使用這個API將url的相對路徑轉換為完全限定的url。

1. chrome.runtime.getBackgroundPage(background: Window => {...}) 返回當前擴充套件的 background 物件
2. chrome.runtime.ma 返回清單檔案
3. chrome.runtime.getURL 返回擴充套件中檔案相對於安裝位置的路徑
4. chrome.runtime.setUninstallURL 設定解除安裝時要訪問的 URL
5. chrome.runtime.reload 重新載入擴充套件

2. chrome.cookies

使用前需要先註冊許可權

{
 

    "permission": [
        "cookies",
        "https://*.xxx.com"
    ]
}

常規方法 get | remove | set | getAll 等除外，以下是可能會用到的 api

1. chrome.cookies.onChanged.addListener(({removed, cookie}) => {...}) removed=true 表示的是cookie被刪除的情況，否則表示被新增或者設定，cookie 表示操作的cookie

3. chrome.tabs

瀏覽器標籤操作，需要開通標籤操作的許可權

{
    "permission": [
        "tabs",
        "https://*.xxx.com"
    ]
}

1. chrome.tabs.create(params, callback) 建立一個新的標籤，以下是 params 引數
   • windowId 建立新標籤的目標視窗，預設當前視窗
   • index 標籤在視窗中的位置
   • url 標籤導航的初始頁面
   • selected 是否為選中的 預設是true
   • pinned 標籤是否為固定
   • callback(tab) tab 是建立後的標籤的細節，包括id
2. chrome.tabs.executeScript(tabId, details, callback) 向標籤頁注入指令碼
   • tabId 標籤頁ID，預設為當前選中視窗
   • details.code 直接注入的指令碼程式碼
   • details.file 也可以指定注入的指令碼檔案，與 details.code 二選一
3. chrome.tabs.get(tabId, callback) 獲取指定標籤頁的細節
4. chrome.tabs.getSelected(windowId, callback) 獲取特定視窗（windowId 預設為當前視窗） 的選中的標籤
5. chrome.tabs.insertCSS(tabId, details, callback) 向頁面注入樣式
6. chrome.tabs.remove(tabId, callback) 移除標籤
7. 其他資訊參照文件

4. chrome.extension

主要被用於通訊支援，提供 擴充套件與 content_script 之間， 擴充套件與擴充套件之間，與大多數 chrome.* API 不同，chrome.extension 部分功能可以直接在 content_script 中使用

注意 chrome.extension 與 chrome.runtime 由很多重疊的 api , chrome.extension 比較老舊，儘量使用 chrome.runtime

1. chrome.extension.connect(extensionId, connectInfo) 嘗試連線到擴充套件內的其他監聽者，主要用於 content_script => 擴充套件程序 的連線，由擴充套件程序 => content_script 的主動連線則可通過 chrome.tabs.connect() 連線
   • extensionId 想要連線的擴充套件的擴充套件ID, 預設為注入這個 content_script 的擴充套件
2. chrome.extension.onConnect.addListener(listener) 監聽到發來的連線時觸發的監聽函式
3. chrome.extension.sendMessage(extensionId, message, responseCallback) 向擴充套件內的其他監聽者傳送訊息
   • extensionId 擴充套件Id, 預設為函式呼叫者所在的擴充套件
   • message
   • responseCallback(response) 返回的響應資料
4. chrome.extension.onMessage.addListener(details => {...}) 接收到本擴充套件中訊息後的監聽函式
   • details.message 資訊
   • details.sender 資訊傳送者
   • details.sendRender() 傳送響應訊息，只能呼叫一次
5. chrome.extension.getURL(path) 將擴充套件內的檔案路徑轉換為 普通頁面可用的檔案路徑
6. chrome.extension.getBackgroundPage() 返回擴充套件中當前執行的 background 頁面
7. chrome.extension.getViews(fetchProperties) 返回指定型別的頁面，包括標籤頁、後臺頁、彈窗頁等
   • fetchProperties.type 可以是 [“tabs”, “popup”, “infobar”, “notification”] 省略這項會返回所有吧型別的頁面 包括 background

注意，只有以下 extension API 可以在 content_script 中使用

1. chrome.extension.connect
2. chrome.extension.onConnect
3. chrome.extension.sendMessage
4. chrome.extension.onMessage
5. chrome.extension.getURL

5. chrome.webNavigation

處理正在進行中的導航請求，需要開通許可權

{
    "permission": [
        "webNavigation",
    ]
}

一個普通的導航從開始到導航結束所經歷的生命週期如下

onBeforeNavigate => onCommitted => onDOMContentLoaded => onCompleted

1. transitionType 各個監聽事件中都會返回的一個型別值，表示當前導航的觸發原因
   • 可以包含的值：["link", "typed", "auto_bookmark", "reload", ...] 多數情況下用來指引，新開啟的標籤頁是怎麼觸發的
2. chrome.webNavigation.onBeforeNavigate.addListener(details => {...}) 導航即將發生時觸發
   • details.tabId 導航即將開啟的 tab 的 id
   • details.url 即將開啟的 url
   • details…
3. chrome.webNavigation.onCommitted.addListener(details => {...}) 導航提交時觸發，在這個時候，document 仍然在下載，它所引用的資源也可能在下載，但是瀏覽器已經接受少部分文件，並決定切換到新的文件
   • details.tabId 導航即將開啟的 tab 的 id
   • details.url 即將開啟的 url
   • details.transitionType 導航的原因
4. chrome.webNavigation.onDOMContentLoaded.addListener(details => {...}) 在頁面 DOM 構造完成時觸發，但是DOM所引用的資源不一定載入完成
   • details.tabId 導航即將開啟的 tab 的 id
   • details.url 即將開啟的 url
5. chrome.webNavigation.onCompleted.addListener(details => {...}) DOM 及其引用的資源全部載入完成時觸發
   • details.tabId 發生導航的 tab 的 id
   • details.url 發生導航的 url

6. chrome.storage

使用者資料的儲存、檢索、跟蹤，與localStorage 相比做了很多的優化，使用時需要獲取許可權

{
    "permissions": [
      "storage"
    ]
}

關鍵點

1. content_script 中可以直接訪問
2. 可以是非同步的，可以批量讀寫
3. 可以儲存物件，而不像 localStorage 只能存字串
4. 可以同步到 Chrome 賬戶，需要使用 storage.sync

storage.sync 與 storage.local 都用來儲存資料 只不過 storage.sync 可以同步到 Chrome 賬戶，以下以 storage.local 為例

1. chrome.storage.onChanged.addListener((changes, namespace) => {...}) 監聽儲存事件
   • changes[key].newValue 更新後的值
   • changes[key].oldValue 更新前的值
2. chrome.storage.local.get(key|keyArray, callback) 讀取儲存 key 可以是字元春或者陣列，陣列代表獲取多個 key 對應的儲存，key=null 獲取所有儲存 callback 中可以得到獲取的值，必填
3. chrome.storage.local.set(Object, callback) 設定或者耿勳儲存，會觸發 onChanged 事件
4. chrome.storage.local.remove('name', callback) 移除某一個儲存
5. chrome.storage.local.clear(callback) 清除所有儲存