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