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受權以下：

1 {
2         ...
3         "permissions": [
4           "tabs"
5         ],
6         ...
7 }

 

當前窗口是包含正在運行的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受權以下：

1 {
2         ...
3         "permissions": [
4           "tabs"
5         ],
6         ...
7 }

 

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