chrome.tabs

描述 使用 chrome.tabs API 与浏览器标签页交互。您可以使用该 API 创建、修改或重新排列浏览器中的标签页。
可用版本 从 Chrome 5 开始支持。
权限 大部分 chrome.tabs API 不需要任何权限就能使用。然而, TaburltitlefavIconUrl 属性需要有 "tabs" 权限后才会给出。tabs.captureVisibleTab 需要 "<all_urls>""activeTab" 权限才能使用。

清单文件

您不需要在应用的清单文件中声明任何权限就能使用 chrome.tabs 的大多数方法和事件。然而,如果您需要访问 tabs.TaburltitlefavIconUrl 属性,您必须在清单文件中声明 "tabs" 权限,如下所示:

      {
        "name": "我的应用",
        ...
        "permissions": [
          "tabs"
        ],
        ...
      }
      

摘要

<
类型
Tab
InjectDetails
ZoomSettings
方法
get chrome.tabs.get(integer tabId, function callback)
getCurrent chrome.tabs.getCurrent(function callback)
connect runtime.Port chrome.tabs.connect(integer tabId, object connectInfo)
sendRequest chrome.tabs.sendRequest(integer tabId, any request, function responseCallback)
sendMessage chrome.tabs.sendMessage(integer tabId, any message, function responseCallback)
getSelected chrome.tabs.getSelected(integer windowId, function callback)
getAllInWindow chrome.tabs.getAllInWindow(integer windowId, function callback)
create chrome.tabs.create(object createProperties, function callback)
duplicate chrome.tabs.duplicate(integer tabId, function callback)
query chrome.tabs.query(object queryInfo, function callback)
update chrome.tabs.update(integer tabId, object updateProperties, function callback)
reload chrome.tabs.reload(integer tabId, object reloadProperties, function callback)
remove chrome.tabs.remove(integer or array of integer tabIds, function callback)
detectLanguage chrome.tabs.detectLanguage(integer tabId, function callback)
captureVisibleTab chrome.tabs.captureVisibleTab(integer windowId, types.ImageDetails options, function callback)
executeScript chrome.tabs.executeScript(integer tabId, tabs.InjectDetails details, function callback)
insertCSS chrome.tabs.insertCSS(integer tabId, tabs.InjectDetails details, function callback)
事件
onCreated
onUpdated
onActiveChanged
onActivated
onRemoved

类型

Tab

属性
integer id

标签页的标识符。标签页的标识符在浏览器会话中唯一。在某些情况下,标签页可能没有标识符,例如使用 sessions API 查询外来标签页时,此时可能存在会话标识符。

integer index

标签页在所在窗口中的索引,从 0 开始。

integer windowId

标签页所在窗口的标识符。

integer (可选)
openerTabId

从 Chrome 18 开始支持。

打开这一标签页的标签页标识符(如果存在的话),只有该标签页仍然存在时才会有这一属性。

boolean selected

从 Chrome 33 开始弃用请使用 tabs.Tab.highlighted

标签页是否选中。

boolean highlighted

从 Chrome 16 开始支持。

标签页是否高亮突出。

boolean active

从 Chrome 16 开始支持。

标签页是否是窗口中的活动标签页。(窗口不一定有焦点。)

boolean pinned

从 Chrome 9 开始支持。

标签页是否固定。

string (可选)
url

标签页中显示的 URL,只有当应用拥有 "tabs" 权限时该属性才会存在。

string (可选)
title

标签页的标题,只有当应用拥有 "tabs" 权限时该属性才会存在,如果标签页正在加载它也可能是空字符串。

string (可选)
favIconUrl

标签页的收藏夹图标 URL,只有当应用拥有 "tabs" 权限时该属性才会存在,如果标签页正在加载它也可能是空字符串。

string (可选)
status

"loading"(正在加载)或 "complete"(完成)。

boolean incognito

标签页是否在隐身窗口中。

integer (可选)
width

从 Chrome 31 开始支持。

标签页宽度,以像素为单位。

integer (可选)
height

从 Chrome 31 开始支持。

标签页高度,以像素为单位。

string (可选)
sessionId

从 Chrome 31 开始支持。

会话标识符,用于唯一标识由 sessions API 获取的标签页。

InjectDetails

从 Chrome 22 开始支持。

要插入的脚本或 CSS 的详情。必须设置 code 和 file 属性中的某一个,而且不能同时设置。
属性
string (可选)
code

要插入的 JavaScript 或 CSS 代码。

警告:
使用 code 参数时要特别小心,不恰当的使用可能会使您的应用遭到跨站脚本攻击。

string (可选)
file

要插入的 JavaScript 或 CSS 文件。

boolean (可选)
allFrames

如果 allFrames 为 true,则意味着当前页面中的所有框架都要插入 JavaScript 或 CSS。默认情况下为 false,只在顶层主框架中插入。

boolean (可选)
matchAboutBlank

从 Chrome 37 开始支持。 警告: 目前为 Beta 分支。

如果 matchAboutBlank 为 true,代码同时也会插入 about:blank 和 about:srcdoc 框架(如果您的应用有权限访问所属文档)。不能在顶层 about: 框架中插入代码。默认情况下为 false

enum of "document_start", "document_end", or "document_idle" (可选)
runAt

JavaScript 或 CSS 插入标签页的最早时间,默认为 "document_idle"。

ZoomSettings

从 Chrome 38 开始支持。 警告: 目前为 Dev 分支。

定义标签页中缩放设置更改的处理方式与范围。
属性
enum of "automatic", "manual", or "disabled" (可选)
mode

定义缩放设置更改的处理方式,即哪一方负责网页的实际缩放,默认为 automatic

automatic
缩放设置的更改由浏览器自动处理。
manual
替换缩放更改的自动处理。 onZoomChange 事件还是会分发,并且应用需要监听该事件,手动缩放网页。该模式下不支持 per-origin(不同来源独立缩放),因此忽略 scope(范围)缩放设置,始终为 per-tab(仅在当前标签页中生效)
disabled
禁用标签页中的所有缩放,标签页恢复为默认(100%)的缩放比例,所有缩放更改都会忽略。
enum of "per-origin", or "per-tab" (可选)
scope

定义缩放更改是根据网页来源保存,还是仅在当前标签页中生效。automatic(自动)模式下默认为 per-origin,其他模式下则为 per-tab

per-origin
缩放更改保存在经过缩放的网页来源中,即导航到同一来源的其他标签页也同样会缩放。此外, per-origin 缩放更改与来源一起保存,也就是说导航到同一来源的其他网页时,也同样会缩放至相同的比例。 per-origin 范围只能在 automatic 模式下使用。
per-tab
缩放更改仅在当前标签页中生效,其他标签页中的缩放更改也不会影响当前标签页。此外, per-tab 缩放更改导航时重置,导航标签页时始终以 per-origin 缩放比例加载网页。

方法

get

chrome.tabs.get(integer tabId, function callback)

获得指定标签页的有关详情。

参数
integer tabId
function callback

callback 参数应该是一个如下形式的函数:

function( Tab tab) {...};
Tab tab

getCurrent

chrome.tabs.getCurrent(function callback)

获得当前调用脚本所在的标签页,如果在非标签页环境下调用则可能返回 undefined(例如,后台页面或弹出视图)。

参数
function callback

callback 参数应该是一个如下形式的函数:

function( Tab tab) {...};
Tab (可选)
tab

connect

runtime.Port chrome.tabs.connect(integer tabId, object connectInfo)

连接到指定标签页中的内容脚本,这样当前应用在指定标签页中运行的每一个内容脚本都会产生 runtime.onConnect 事件。有关更多详情,请参见内容脚本的消息传递

参数
integer tabId
object (可选)
connectInfo
string (可选)
name

将传递给 onConnect 事件,用于监听连接事件的内容脚本。

sendRequest

chrome.tabs.sendRequest(integer tabId, any request, function responseCallback)

从 Chrome 33 开始弃用请使用 runtime.sendMessage

向指定标签页中的内容脚本发送一个消息,当发回响应时执行一个可选的回调函数。当前应用在指定标签页中的每一个内容脚本都会收到 extension.onRequest 事件。

参数
integer tabId
any request
function (可选)
responseCallback

如果您指定了 responseCallback 参数,它应该是一个如下形式的函数:

function(any response) {...};
any response

请求处理程序发出的 JSON 响应对象。如果连接到指定标签页的过程中发生错误,将不传递参数调用回调函数,并将 runtime.lastError 设置为错误消息。

sendMessage

chrome.tabs.sendMessage(integer tabId, any message, function responseCallback)

从 Chrome 20 开始支持。

向指定标签页中的内容脚本发送一个消息,当发回响应时执行一个可选的回调函数。当前应用在指定标签页中的每一个内容脚本都会收到 runtime.onMessage 事件。

参数
integer tabId
any message
function (可选)
responseCallback

如果您指定了 responseCallback 参数,它应该是一个如下形式的函数:

function(any response) {...};
any response

请求处理程序发出的 JSON 响应对象。如果连接到指定标签页的过程中发生错误,将不传递参数调用回调函数,并将 runtime.lastError 设置为错误消息。

getSelected

chrome.tabs.getSelected(integer windowId, function callback)

从 Chrome 33 开始弃用请使用 tabs.query {active: true}

获取指定窗口中选定的标签页。

参数
integer (可选)
windowId

默认为当前窗口

function callback

callback 参数应该是一个如下形式的函数:

function( Tab tab) {...};
Tab tab

getAllInWindow

chrome.tabs.getAllInWindow(integer windowId, function callback)

从 Chrome 33 开始弃用请使用 tabs.query {windowId: windowId}

获取指定窗口中所有标签页的详情。

参数
integer (可选)
windowId

默认为当前窗口

function callback

callback 参数应该是一个如下形式的函数:

function(array of Tab tabs) {...};
array of Tab tabs

create

chrome.tabs.create(object createProperties, function callback)

创建一个新标签页。

参数
object createProperties
integer (可选)
windowId

创建新标签页的窗口,默认为当前窗口

integer (可选)
index

标签页在窗口中的位置,提供的值如果超过0与窗口中标签页数目之间的范围,将会自动限定在这一范围。

string (可选)
url

标签页中一开始打开的 URL。完整的 URL 必须包括协议(即 "http://www.google.com",而不能是 "www.google.com"),相对 URL 相对于应用中的当前页面。默认为“打开新的标签页”页面。

boolean (可选)
active

从 Chrome 16 开始支持。

标签页是否应该成为窗口中的活动标签页,不影响窗口是否有焦点(参见 windows.update),默认为 true

boolean (可选)
selected

从 Chrome 33 开始弃用请使用 active

标签页是否为窗口中的选定标签页,默认为 true

boolean (可选)
pinned

从 Chrome 9 开始支持。

标签页是否应该固定,默认为 false

integer (可选)
openerTabId

从 Chrome 18 开始支持。

打开这一标签页的标签页标识符。如果指定的话,该标签页必须与新创建的标签页在同一个窗口中。

function (可选)
callback

如果您指定了 callback 参数,它应该是一个如下形式的函数:

function( Tab tab) {...};
Tab tab

有关新创建标签页的详情,会包含新标签页的标识符。

duplicate

chrome.tabs.duplicate(integer tabId, function callback)

从 Chrome 23 开始支持。

复制标签页。

参数
integer tabId

要复制的标签页的标识符。

function (可选)
callback

如果您指定了 callback 参数,它应该是一个如下形式的函数:

function( Tab tab) {...};
Tab (可选)
tab

有关已复制标签页的详情,如果没有请求 "tabs" 权限的话 tabs.Tab 对象不会包含 urltitlefavIconUrl

query

chrome.tabs.query(object queryInfo, function callback)

从 Chrome 16 开始支持。

获取具有指定属性的所有标签页,如果没有指定任何属性的话则获取所有标签页。

参数
object queryInfo
boolean (可选)
active

标签页在窗口中是否为活动标签页。

boolean (可选)
pinned

标签页是否固定。

boolean (可选)
highlighted

标签页是否高亮突出。

boolean (可选)
currentWindow

从 Chrome 19 开始支持。

标签页是否在当前窗口中。

boolean (可选)
lastFocusedWindow

从 Chrome 19 开始支持。

标签页是否在前一个具有焦点的窗口中。

enum of "loading", or "complete" (可选)
status

标签页是否已经加载完成。

string (可选)
title

匹配页面标题的表达式。

string (可选)
url

匹配标签页的 URL 表达式。注意:片段标识符不会匹配。

integer (可选)
windowId

父窗口标识符,或者为 windows.WINDOW_ID_CURRENT,表示当前窗口

enum of "normal", "popup", "panel", or "app" (可选)
windowType

标签页所在窗口的类型。

integer (可选)
index

从 Chrome 18 开始支持。

标签页在窗口中的位置。

function callback

callback 参数应该是一个如下形式的函数:

function(array of Tab result) {...};
array of Tab result

update

chrome.tabs.update(integer tabId, object updateProperties, function callback)

修改标签页属性,updateProperties 中未指定的属性保持不变。

参数
integer (可选)
tabId

默认为当前窗口的选定标签页。

object updateProperties
string (可选)
url

标签页打开的 URL。

boolean (可选)
active

从 Chrome 16 开始支持。

标签页是否为活动标签页,不影响窗口是否有焦点(参见 windows.update)。

boolean (可选)
highlighted

从 Chrome 16 开始支持。

从当前选定项目中添加或删除标签页。

boolean (可选)
selected

从 Chrome 33 开始弃用请使用 highlighted

标签页是否选中。

boolean (可选)
pinned

从 Chrome 9 开始支持。

标签页是否固定。

integer (可选)
openerTabId

从 Chrome 18 开始支持。

打开这一标签页的标签页标识符。如果指定的话,该标签页必须与新创建的标签页在同一个窗口中。

function (可选)
callback

如果您指定了 callback 参数,它应该是一个如下形式的函数:

function( Tab tab) {...};
Tab (可选)
tab

有关更新后的标签页详情,如果没有请求 "tabs" 权限的话 tabs.Tab 对象不包含 urltitlefavIconUrl

reload

chrome.tabs.reload(integer tabId, object reloadProperties, function callback)

从 Chrome 16 开始支持。

重新加载标签页。

参数
integer (可选)
tabId

要重新加载的标签页标识符,默认为当前窗口的选定标签页。

object (可选)
reloadProperties
boolean (可选)
bypassCache

是否跳过本地缓存,默认为 false,即使用本地缓存。

function (可选)
callback

如果您指定了 callback 参数,它应该是一个如下形式的函数:

function() {...};

remove

chrome.tabs.remove(integer or array of integer tabIds, function callback)

关闭一个或多个标签页。

参数
integer or array of integer tabIds

从 Chrome 16 开始支持。

要关闭的标签页或标签页列表。

function (可选)
callback

如果您指定了 callback 参数,它应该是一个如下形式的函数:

function() {...};

detectLanguage

chrome.tabs.detectLanguage(integer tabId, function callback)

检测某个标签页中内容的主要语言。

参数
integer (可选)
tabId

默认为当前窗口的活动标签页。

function callback

callback 参数应该是一个如下形式的函数:

function(string language) {...};
string language

ISO 语言代码,例如 enfr。有关该方法支持的所有语言的完整列表,请参见 kLanguageInfoTable,将检查第二列到第四列并返回第一个非 NULL 值(除了简体中文返回 zh-CN),未知语言将返回 und

captureVisibleTab

chrome.tabs.captureVisibleTab(integer windowId, types.ImageDetails options, function callback)

捕捉指定窗口中当前活动标签页的可见区域,您必须拥有 "<all_urls>" 或当前活动标签页的 "activeTab" 权限才能使用该方法。

参数
integer (可选)
windowId

目标窗口,默认为当前窗口

types.ImageDetails (可选)
options
function callback

callback 参数应该是一个如下形式的函数:

function(string dataUrl) {...};
string dataUrl

包含捕捉到的标签页可视区域图像的数据URL,可以将一个 HTML 图像元素的 “src” 属性设为该参数的值来显示图像。

executeScript

chrome.tabs.executeScript(integer tabId, tabs.InjectDetails details, function callback)

在页面中插入 JavaScript 代码。有关更多详情,请参节内容脚本文档中以编程方式插入部分。

参数
integer (可选)
tabId

运行脚本的标签页标识符,默认为当前窗口的活动标签页。

tabs.InjectDetails details

需要运行的脚本详情。

function (可选)
callback

在所有 JavaScript 代码执行完后调用。

如果您指定了 callback 参数,它应该是一个如下形式的函数:

function(array of any result) {...};
array of any (可选)
result

在插入的每一个框架中脚本的执行结果。

insertCSS

chrome.tabs.insertCSS(integer tabId, tabs.InjectDetails details, function callback)

向一个页面中插入CSS。有关更多详情,请参节内容脚本文档中以编程方式插入部分。

参数
integer (可选)
tabId

要插入CSS的标签页标识符,默认为当前窗口的活动标签页。

tabs.InjectDetails details

要插入的CSS文本详情。

function (可选)
callback

当所有CSS都已经被插入后调用。

如果您指定了 callback 参数,它应该是一个如下形式的函数:

function() {...};

事件

onCreated

当标签页创建时产生。注意,当该事件发生时标签页的 URL 可能还没有设置,但是您可以处理 onUpdated 事件,在设置 URL 时收到通知。

addListener

chrome.tabs.onCreated.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数:

function( Tab tab) {...};
Tab tab

有关已创建标签页的详情。

onUpdated

当标签页更新时产生。

addListener

chrome.tabs.onUpdated.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数:

function(integer tabId, object changeInfo, Tab tab) {...};
integer tabId
object changeInfo

列出更新的标签页改变的状态。

string (可选)
status

标签页的状态,可以为 loading(正在加载)或 complete(完成)。

string (可选)
url

标签页的 URL(如果已更改的话)。

boolean (可选)
pinned

从 Chrome 9 开始支持。

标签页新的固定状态。

string (可选)
favIconUrl

从 Chrome 27 开始支持。

标签页新的收藏夹图标 URL。

Tab tab

给出更新后的标签页状态。

onActiveChanged

从 Chrome 33 开始弃用请使用 tabs.onActivated

窗口中的选定标签页更改时产生。注意,该事件产生时标签页的 URL 可能还没有设置,但是您可以监听 onUpdated 事件,当 URL 设置时收到通知。

addListener

chrome.tabs.onActiveChanged.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数:

function(integer tabId, object selectInfo) {...};
integer tabId

变成活动标签页的标签页标识符。

object selectInfo
integer windowId

选定标签页更改的窗口标识符。

onActivated

从 Chrome 18 开始支持。

当窗口中的当前标签页更改时产生。注意,当该事件发生时标签页的 URL 可能还没有设置,但是您可以处理 onUpdated 事件,在设置 URL 时收到通知。

addListener

chrome.tabs.onActivated.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数:

function(object activeInfo) {...};
object activeInfo
integer tabId

现在的活动标签页标识符。

integer windowId

活动标签页更改的窗口标识符。

onRemoved

当标签页关闭时产生。

addListener

chrome.tabs.onRemoved.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数:

function(integer tabId, object removeInfo) {...};
integer tabId
object removeInfo

从 Chrome 9 开始支持。

integer windowId

从 Chrome 25 开始支持。

包含已关闭标签页的窗口。

boolean isWindowClosing

当标签页因为窗口关闭而关闭时为 true。