Chrome瀏覽器擴充套件開發系列之十六：擴充套件中可用的Chrome瀏覽器API

除了Chrome瀏覽器支援的chrome.* API之外，Chrome瀏覽器擴充套件還可以使用Chrome瀏覽器為Web頁面或Chrome app提供的APIs。對於Chrome瀏覽器2支援的API，還可以繫結第三方API庫到Chrome瀏覽器擴充套件程式。

Chrome瀏覽器擴充套件程式可以使用的API包括：

• 標準JavaScript API，即Web應用中常用的JavaScript核心API和DOM API
• XMLHttpRequest API
• HTML5 API
• WebKit API，特別是WebKit的CSS特性，如過濾器、動畫和變換
• Chrome V8 API，如JSON
• 其他第三方類庫API，如jQuery，可以繫結這些API到Chrome瀏覽器擴充套件程式，就如同在Web頁面中使用這些API

本系列將首先介紹一些常用的Chrome瀏覽器API。

1. Chrome sessions API

Chrome瀏覽器擴充套件程式通過chrome.sessions API，可以從瀏覽器的會話中存取windows視窗和tab頁。

chrome.sessions.Session物件的屬性如下：

屬性名	型別	必選/可選	註釋
lastModified	整型	必選	視窗或tab頁被關閉或修改的時間，ms
tab	chrome.tabs.Tab	與window兩者必選其一	tab頁
window	chrome.windows.Window	與tab兩者必選其一	視窗

 

chrome.sessions API中的常用方法：

• 獲得最近被關閉的windows視窗或tab頁的列表

chrome.sessions.getRecentlyClosed(Filter filter, function(array of Session))

• 獲得同步會話中的所有裝置

chrome.sessions.getDevices(Filter filter, function(array of Session))

• 恢復開啟指定會話中的視窗或tab頁

chrome.sessions.restore(string sessionId, function(Session session))

 

2. Chrome windows API

Chrome瀏覽器擴充套件程式通過chrome.windows API，可以與瀏覽器的視窗系統互動，如建立瀏覽器視窗、修改瀏覽器視窗和重新編排瀏覽器視窗。

chrome.windows API本身無需宣告任何授權。但是一個chrome.windows.Window物件包含一個chrome.tabs.Tab型別的陣列，如果要運算元組中的tabs的url、title、favIconUrl屬性，則需要在manifest.json檔案中宣告tabs授權如下：

{
        ...
        "permissions": [
          "tabs"
        ],
        ...
}

 

當前視窗是包含正在執行的JavaScript程式碼的視窗。這與當前擁有焦點的視窗可能不是同一個視窗。

chrome.windows.Window物件的屬性如下：

屬性名	型別	必選/可選	註釋
id	整型	可選	視窗的ID，在瀏覽器會話範圍內唯一。有些情況下的視窗沒有ID
focused	布林型	可選	視窗是否擁有焦點
top	整型	可選	視窗離螢幕頂部邊緣偏移的畫素值。有些情況下的視窗沒有top
left	整型	可選	視窗離螢幕左部邊緣偏移的畫素值。有些情況下的視窗沒有left
width	整型	可選	視窗的寬度畫素值，包括邊框。有些情況下的視窗沒有width
height	整型	可選	視窗的高度畫素值，包括邊框。有些情況下的視窗沒有height
tabs	chrome.tabs.Tab的陣列	可選	視窗中擁有的tabs
incognito	布林型	可選	視窗是否執行在隱身模式下
type	WindowType	可選	瀏覽器視窗的型別。 列舉值"normal", "popup", "panel", "app", "devtools"
state	WindowState	可選	瀏覽器視窗的狀態。列舉值"normal", "minimized", "maximized", "fullscreen", "docked"
alwaysOnTop	布林型	必選	視窗是否總是位於頂層（模式視窗）
sessionId	字串	可選	從Chrome.sessions API獲取的會話ID，用以唯一標識一個視窗

 

chrome.tabs API中的常用方法：

• 建立一個新的瀏覽器視窗

chrome.windows.create(object createData, function(Window window){…})

createData物件是可選的，表示採用預設值建立視窗。createData物件的屬性同chrome.windows.Window物件。

• 關閉一個指定的瀏覽器視窗

chrome.windows.remove(integer windowId, function(){…})

• 修改一個指定的瀏覽器視窗的引數

chrome.windows.update(integer windowId, object updateInfo, function(Window window){…})

updateInfo物件是必選的，其中未涉及的Window屬性則保持不變。

• 獲取指定ID的視窗物件

chrome.windows.get(integer windowId, object getInfo, function(Window window){…})

getInfo物件是可選的，其有兩個引數。一個是名為populate的布林型引數，true表示該方法得到的chrome.windows.Window物件裡包含chrome.tabs.Tab型別的陣列。另一個名為windowTypes的WindowType型引數，表示通過windowTypes進行篩選視窗。

• 獲取所有的視窗物件

chrome.windows.getAll(object getInfo, function(array of Window){…})

getInfo物件是可選的，其有兩個引數。一個是名為populate的布林型引數，true表示該方法得到的chrome.windows.Window物件裡包含chrome.tabs.Tab型別的陣列。另一個名為windowTypes的WindowType型引數，表示通過windowTypes進行篩選視窗。

 

 3. Chrome tabs API

Chrome瀏覽器擴充套件程式通過chrome.tabs API，可以與瀏覽器的tab系統互動，如建立瀏覽器tab、修改瀏覽器tab和重新編排瀏覽器tabs。

大多數chrome.tabs API無需宣告任何授權，但是如果要操作tab的url、title、favIconUrl屬性，則需要在manifest.json檔案中宣告tabs授權如下：

{
        ...
        "permissions": [
          "tabs"
        ],
        ...
}

 

chrome.tabs.Tab物件的屬性如下：

屬性名	型別	必須/可選	註釋
id	整型	可選	tab的ID，在瀏覽器會話中唯一。有些情況下的tab沒有ID
index	整型	可選	從0開始的tab在視窗中的位置序號
windowId	整型	可選	tab所依託的視窗
openerTabId	整型	可選	tab的id，該tab開啟當前tab。兩個tabs都應該位於同一個視窗中
selected	布林型	可選	已過期。tab是否被選中
highlighted	布林型	可選	tab是否高亮顯示
active	布林型	可選	tab是否成為視窗中的啟用tab，無論視窗是否擁有焦點
pinned	布林型	可選	tab是否訂住
audible	布林型	可選	tab是否在剛剛過去的幾秒鐘裡發出過聲音（當未必被聽見，因為可能被靜音）
mutedInfo	MutedInfo型別	可選	tab的靜音狀態
url	字串	可選	tab顯示的url，需要擁有tabs許可權
title	字串	可選	tab顯示的title，需要擁有tabs許可權
favIconUrl	字串	可選	tab的favicon的url，需要擁有tabs許可權。tab載入過程中為空
status	字串	可選	tab的狀態，列舉值"loading", "complete"
incognito	布林型	可選	tab所在視窗是否為隱身視窗
width	整型	可選	tab的寬度畫素值
height	整型	可選	tab的高度畫素值
sessionId	字串	可選	從Chrome.sessions API獲取的會話ID，用以唯一標識一個tab

 

chrome.tabs API中的常用方法：

• 建立一個新tab

chrome.tabs.create(object createProperties, function(Tab tab){…})

createProperties物件的屬性如下：

屬性名	型別	必須/可選	註釋
windowId	整型	可選	建立tab所依託的視窗，預設為當前視窗
index	整型	可選	被建立的tab在視窗中的位置序號，0~tab數量
url	字串	可選	被建立的tab的初始url。完整的URL類似於http://www.yourdomain.com，相對的URL可以是相對於擴充套件中的當前頁面。
active	布林型	可選	被建立的tab是否成為啟用tab，無論視窗是否擁有焦點。預設為true
selected	布林型	可選	已過期。被建立的tab是否成為被選中tab，預設true
pinned	布林型	可選	被建立的tab是否訂住，預設false
openerTabId	整型	可選	tab的id，該tab開啟新建立的tab。兩個tabs都應該位於同一個視窗中

• 複製一個新tab

chrome.tabs.duplicate(integer tabId, function(Tab tab){…})

• 關閉tabs

chrome.tabs.remove(integer or array of integer tabIds, function(){…})

• 修改tab的屬性

chrome.tabs.update(integer tabId, object updateProperties, function(Tab tab){…})

updateProperties物件是必選的，其中未涉及的tab屬性則保持不變。

• 獲取指定id的tab

chrome.tabs.get(integer tabId, function(Tab tab){…})

• 根據指定的若干屬性查詢tabs

chrome.tabs.query(object queryInfo, function(array of Tab){…})

queryInfo物件的屬性如下：

屬性名	型別	必須/可選	註釋
active	布林型	可選	tab是否成為視窗中的啟用tab
pinned	布林型	可選	tab是否訂住
audible	布林型	可選	tab是否在剛剛過去的幾秒鐘裡發出過聲音（當未必被聽見，因為可能被靜音）
muted	布林型	可選	tab是否處於靜音狀態
highlighted	布林型	可選	tab是否高亮顯示
currentWindow	布林型	可選	tab是否位於當前視窗
lastFocusedWindow	布林型	可選	tab是否位於最近擁有焦點的視窗中
status	TabStatus型別	可選	tab的狀態，列舉值"loading", "complete"
title	字串	可選	tab顯示的title，需要擁有tabs許可權
url	字串	可選	tab顯示的url，需要擁有tabs許可權
windowId	整型	可選	tab所依託的視窗
windowType	WindowType型別	可選	tab所在視窗的型別 列舉值"normal", "popup", "panel", "app", "devtools"
index	整型	可選	從0開始的tab在視窗中的位置序號

 

• 注入JavaScript程式碼到頁面中

chrome.tabs.executeScript(integer tabId, object details, function(array of any){…})

details物件的屬性如下：

屬性名	型別	必須/可選	註釋
code	字串	與file兩者必選其一	要注入的JavaScript程式碼或CSS程式碼
file	字串	與code兩者必選其一	要注入的JavaScript程式碼或CSS檔案路徑
allFrames	布林型	可選	true表示CSS將注入到當前頁面的所有frames。預設false，表示CSS只注入到頂層frame
matchAboutBlank	布林型	可選	true表示CSS將注入about:blank和about:srcdoc，當不好注入到about:-frames。預設false
runAt	列舉型 "document_start","document_end", "document_idle"	可選	CSS最早注入的時機

• 注入CSS檔案到頁面中

chrome.tabs.insertCSS(integer tabId, object details, function(){…})

details物件的屬性同executeScript()。