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()。