Cookies
要使用cookies API, 你必须在你的清单中声明"cookies"权限,以及任何你希望cookie可以访问的主机权限。例如:
{
"name": "My extension",
...
"permissions": [
"cookies",
"*://*.google.com"
],
...
}
常用方法及事件
get
获取一个cookie的信息。如果对于给定的URL有多个cookie存在,将返回对应于最长路径的cookie。对于路径长度相同的cookies,将返回最早创建的cookie。
chrome.cookies.get(object details, function callback)
- details ( object对象 )
用于识别所收到的cookie的详细信息。-
- url ( string字符串 )
与所收到的cookie关联的URL。这个参数可以是一个完整的URL,这时候所有跟随在URL上的数据(比如查询字符串)将被忽略。如果清单文件中没有设置这个URL对应的主机权限,那么这个API调用会失败。
- url ( string字符串 )
-
- name ( string字符串 )
收到的cookie名字。
- name ( string字符串 )
-
- storeId ( optional string可选,字符串 )
cookie的存储id,用于从中检索cookie。默认情况下,当前执行上下文的cookie存储将被使用。
- storeId ( optional string可选,字符串 )
-
- callback ( function 函数 )
//回调
function(Cookie cookie) {
...}; //包含cookie的详细信息。如果没找到cookie,该参数为null。
getAll
从一个cookie存储获取与给定信息匹配的所有cookies。所获取cookies将按照最长路径优先排序。当多个cookies有相同长度路径,最早创建的cookie在前面。
chrome.cookies.getAll(object details, function callback)
- details ( object )
对cookies进行筛选的信息。-
- url ( optional string可选,字符串 )
限定只查找与给定URL匹配的cookies。
- url ( optional string可选,字符串 )
-
- name ( optional string可选,字符串 )
根据名称过滤cookies。
- name ( optional string可选,字符串 )
-
- domain ( optional string可选,字符串 )
限定只查找与给定域名或者子域名匹配的cookies。
- domain ( optional string可选,字符串 )
-
- path ( optional string可选,字符串 )
限定只查找与给定路径完全一致的cookies。
- path ( optional string可选,字符串 )
-
- secure ( optional boolean可选,Boolean类型 )
根据cookie的Secure属性进行筛选。
- secure ( optional boolean可选,Boolean类型 )
-
- session ( optional boolean可选,Boolean类型 )
根据cookie的生命周期是会话的还是持久的进行过滤。
- session ( optional boolean可选,Boolean类型 )
-
- storeId ( optional string可选,字符串 )
cookie的存储id,用于从中检索cookie。默认情况下,当前执行上下文的cookie存储将被使用。
- storeId ( optional string可选,字符串 )
-
- callback ( function )
//回调
function(array of Cookie cookies) {
...}; //所有与给定cookie信息匹配、存在并未过期的cookie列表。
getAllCookieStores
chrome.cookies.getAllCookieStores(function callback)
//回调
function(array of CookieStore cookieStores) {
...};
remove
根据名称删除cookie。
chrome.cookies.remove(object details)
- details ( object )
用于鉴定待删除cookie的信息。-
- url ( string )
与所收到的cookie关联的URL。如果清单文件中没有设置这个URL对应的主机权限,那么这个API调用会失败。
- url ( string )
-
- name ( string )
待删除cookie的名称。
- name ( string )
-
- storeId ( optional string )
cookie的存储id,用于从中检索cookie。默认情况下,当前执行上下文的cookie存储将被使用。
- storeId ( optional string )
-
set
chrome.cookies.set(object details)
用给定数据设置一个cookie。如果相同的cookie存在,它们可能会被覆盖。
- details ( object )
待设置cookie的详细信息。-
- url ( string )
与待设置cookie相关的URL。该值影响所创建cookie的默认域名与路径值。如果清单文件中没有设置这个URL对应的主机权限,那么这个API调用会失败。
- url ( string )
-
- name ( optional string )
cookie名称,默认为空值。
- name ( optional string )
-
- value ( optional string )
cookie的值,默认为空值。
- value ( optional string )
-
- domain ( optional string )
cookie的域名。如果未指定,则该cookie是host-only cookie。
- domain ( optional string )
-
- path ( optional string )
cookie的路径。默认是url参数的路径部分。
- path ( optional string )
-
- secure ( optional boolean )
是否cookie标记为保密。默认为false。
- secure ( optional boolean )
-
- httpOnly ( optional boolean )
是否cookie被标记为HttpOnly。默认为false。
- httpOnly ( optional boolean )
-
- expirationDate ( optional number )
cookie的过期时间,用从UNIX epoch开始计的秒数表示。如果未指定,该cookie是一个会话cookie。
- expirationDate ( optional number )
-
- storeId ( optional string )
用于保存该cookie的存储id。默认情况下,当前执行上下文的cookie存储将被使用。
- storeId ( optional string )
-
onChanged
chrome.cookies.onChanged.addListener(function(object changeInfo) {
...});
当一个cookie被设置或者删除时候触发。
事件
Event 是一个对象,当你关注的一些事情发生时通知你。 以下是一个使用 chrome.tabs.onCreated event 的例子,每当一个新标签创建时,event对象会得到通知:
chrome.tabs.onCreated.addListener(function(tab) {
appendToLog('tabs.onCreated --'
+ ' window: ' + tab.windowId
+ ' tab: ' + tab.id
+ ' index: ' + tab.index
+ ' url: ' + tab.url);
});
如示例所示,使用 addListener() 方法注册通知。 addListener() 方法的参数总是一个函数,是你定义来处理事件的函数, 但该函数的参数取决于你的事件处理。 查看 chrome.tabs.onCreated 的文档, 你可以看到该函数有一个参数:一个 Tab 对象,包含新创建的标签的信息。
你可以调用任何 Event 对象的以下方法:
void addListener(function callback(...))
void removeListener(function callback(...))
bool hasListener(function callback(...))
浏览历史
chorme.history 模块被用于和浏览器所访问的页面记录交互。你可以添加、删除、查询浏览器的历史记录。如果您想覆写历史页面,请查看覆写特定页。
声明
您必须在扩展Manifest文件中声明“history”权限,以便使用history API。如下所示:
{
"name": "My extension",
...
"permissions": [
"history"
],
...
}
过渡类型
History API用一种过渡类型来描述浏览器是如何访问的特定的URL。例如:如果URL是在用户访问页面时,点击链接跳转访问的,此时的过渡类型为“link”。
如下的列表详细定义了各种过渡类型。
API说明:chrome.history
$('#history').click((e) => {
let obj = chrome.history
let str = '<br />'
for (let key in obj) {
str += key + ":" + obj[key] + '<br />'
}
$('#content').html(str)
});
通过代码可以看到 chrome.history
中包括以下内容:
方法
search
chrome.history.search(object query, function callback)
搜索访问历史中,匹配条件的页面最后一次访问的数据。
- query ( object )
-
- text ( string )
在访问历史中查询的文本。若想获取所有页面的信息,把此参数设置为空。
- text ( string )
-
- startTime ( optional double )
限制结果访问日期至此日期之后,以纪元开始的毫秒数表示。
- startTime ( optional double )
-
- endTime ( optional double )
限制结果访问日期至此日期以前,以纪元开始的毫秒数表示。
- endTime ( optional double )
-
- maxResults ( optional integer )
所获取结果的最大数目。默认值为100。
- maxResults ( optional integer )
-
- callback ( function )
Callback
回调函数 callback 应当如下定义:function(array of HistoryItem results) {...};
getVisits
chrome.history.getVisits(object details, function callback)
获取访问特定URL的所有信息。
- details ( object )
-
- url ( string )
需要获取访问信息的URL。URL必须与调用 history.search 返回值的格式一致。
- url ( string )
-
- callback ( function ),回调函数应如下定义:
function(array of VisitItem results) {...};
addUrl
chrome.history.addUrl(object details, function callback)
在当前历史记录中添加一条过渡类型为“link”的URL。
- details ( object )
-
- url ( string )
要添加的URL。
- url ( string )
-
- callback ( optional function ),
function() {...};
deleteUrl
chrome.history.deleteUrl(object details, function callback)
删除指定URL的所有历史记录。
- details ( object )
-
- url ( string )
要删除的URL。
- url ( string )
-
- callback ( optional function ),
function() {...};
deleteRange
chrome.history.deleteRange(object range, function callback)
删除特定日期范围内的所有历史记录条目。页面本身只会在所有访问均在所设定日期的范围内才会被删除。
- range ( object )
-
- startTime ( double )
删除范围的开始时间,以纪元开始的毫秒数表示。
- startTime ( double )
-
- endTime ( double )
删除范围的结束时间,以纪元开始的毫秒数表示。
- endTime ( double )
-
- callback ( function ),
function() {...};
deleteAll
chrome.history.deleteAll(function callback)
删除历史记录中的所有条目。
- callback ( function ),
function() {...};
事件
HistoryItem
封装历史查询结果的对象。
HistoryItem 的属性:
- id ( string )
条目的唯一标识符。 - url ( optional string )
用户所访问的URL。 - title ( optional string )
历史页面的标题。 - lastVisitTime ( optional double )
页面最后一次被载入的时间,以纪元开始的毫秒数表示。 - visitCount ( optional integer )
用户访问此页面的次数。 - typedCount ( optional integer )
用户通过地址栏输入访问此页面的次数。
onVisited
chrome.history.onVisited.addListener(function(HistoryItem result) {
...});
当URL被访问时,此事件被触发。并提供相应URL的 HistoryItem 数据。
onVisitRemoved
chrome.history.onVisitRemoved.addListener(function(object removed) {
...});
当一条或多条URL从历史服务中删除,此事件触发。当所有访问被移除后,此条URL从历史记录中被移除。