浏览器交互：Cookies、事件、浏览历史

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调用会失败。
  • • name ( string字符串 )
      收到的cookie名字。
  • • storeId ( optional string可选，字符串 )
      cookie的存储id，用于从中检索cookie。默认情况下，当前执行上下文的cookie存储将被使用。
• 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。
  • • name ( optional string可选，字符串 )
      根据名称过滤cookies。
  • • domain ( optional string可选，字符串 )
      限定只查找与给定域名或者子域名匹配的cookies。
  • • path ( optional string可选，字符串 )
      限定只查找与给定路径完全一致的cookies。
  • • secure ( optional boolean可选，Boolean类型 )
      根据cookie的Secure属性进行筛选。
  • • session ( optional boolean可选，Boolean类型 )
      根据cookie的生命周期是会话的还是持久的进行过滤。
  • • storeId ( optional string可选，字符串 )
      cookie的存储id，用于从中检索cookie。默认情况下，当前执行上下文的cookie存储将被使用。
• 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调用会失败。
  • • name ( string )
      待删除cookie的名称。
  • • storeId ( optional string )
      cookie的存储id，用于从中检索cookie。默认情况下，当前执行上下文的cookie存储将被使用。

set

chrome.cookies.set(object details)

用给定数据设置一个cookie。如果相同的cookie存在，它们可能会被覆盖。

• details ( object )
  待设置cookie的详细信息。
  • • url ( string )
      与待设置cookie相关的URL。该值影响所创建cookie的默认域名与路径值。如果清单文件中没有设置这个URL对应的主机权限，那么这个API调用会失败。
  • • name ( optional string )
      cookie名称，默认为空值。
  • • value ( optional string )
      cookie的值，默认为空值。
  • • domain ( optional string )
      cookie的域名。如果未指定，则该cookie是host-only cookie。
  • • path ( optional string )
      cookie的路径。默认是url参数的路径部分。
  • • secure ( optional boolean )
      是否cookie标记为保密。默认为false。
  • • httpOnly ( optional boolean )
      是否cookie被标记为HttpOnly。默认为false。
  • • expirationDate ( optional number )
      cookie的过期时间，用从UNIX epoch开始计的秒数表示。如果未指定，该cookie是一个会话cookie。
  • • storeId ( optional string )
      用于保存该cookie的存储id。默认情况下，当前执行上下文的cookie存储将被使用。

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 = '
'
    for (let key in obj) {
        str += key + "：" + obj[key] + '
'
    }
    $('#content').html(str)
});

通过代码可以看到 chrome.history 中包括以下内容：

方法

search

chrome.history.search(object query, function callback)

搜索访问历史中，匹配条件的页面最后一次访问的数据。

• query ( object )
  • • text ( string )
      在访问历史中查询的文本。若想获取所有页面的信息，把此参数设置为空。
  • • startTime ( optional double )
      限制结果访问日期至此日期之后，以纪元开始的毫秒数表示。
  • • endTime ( optional double )
      限制结果访问日期至此日期以前，以纪元开始的毫秒数表示。
  • • maxResults ( optional integer )
      所获取结果的最大数目。默认值为100。
• 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 返回值的格式一致。
• callback ( function )，回调函数应如下定义：function(array of VisitItem results) {...};

addUrl

chrome.history.addUrl(object details, function callback)

在当前历史记录中添加一条过渡类型为“link”的URL。

• details ( object )
  • • url ( string )
      要添加的URL。
• callback ( optional function )，function() {...};

deleteUrl

chrome.history.deleteUrl(object details, function callback)

删除指定URL的所有历史记录。

• details ( object )
  • • url ( string )
      要删除的URL。
• callback ( optional function )，function() {...};

deleteRange

chrome.history.deleteRange(object range, function callback)

删除特定日期范围内的所有历史记录条目。页面本身只会在所有访问均在所设定日期的范围内才会被删除。

• range ( object )
  • • startTime ( 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从历史记录中被移除。