Chrome 扩展开发 API实战：Cookies（一）

1. 引言

本文为您提供 chrome.cookies API 的全面指南，包括其功能、使用方法以及详细示例。无论您是初学者还是经验丰富的开发者，这篇文章都能帮助您高效管理和操作 Chrome 扩展中的 cookies。

2. 权限声明

在 manifest.json 文件中声明所需的权限，以正常使用 chrome.cookies API。例如：

{
  "permissions": [
    "cookies",
    "<all_urls>"
  ]
}

• 权限说明：
  • cookies：允许扩展访问和操作浏览器中的 cookies。
  • <all_urls>：为扩展提供对所有 URL 的操作权限，确保 API 功能正常。
• 注意事项：
  1. chrome.cookies API 仅适用于扩展进程，不能直接在网页脚本中使用。
  2. 使用 chrome.cookies.set 时，确保 cookie 的 URL 与扩展的权限范围一致。

3. chrome.cookies.get

3.1 方法功能

检索与指定属性匹配的 cookies。常见使用场景包括验证用户是否已登录，检查会话有效性等。

3.2 使用方法

chrome.cookies.get({ url: "https://example.com", name: "session_id" }, function(cookie) {
  if (cookie) {
    console.log("Cookie found:", cookie); // Log the cookie if found
  } else {
    console.log("No cookie found."); // Log a message if no cookie is found
  }
});

3.3 参数详解

• details：一个对象，包含查询 cookies 的条件。
  • url (string)：必须。cookie 所属页面的 URL。
  • name (string)：可选。cookie 的名称。
• callback：一个函数，接收返回的 cookie 对象。

3.4 实际样例

• 示例代码：

chrome.cookies.get({ url: "https://example.com", name: "session_id" }, function(cookie) {
  if (!cookie) {
    alert("Session expired. Please log in again.");
  }
});

3.5 注意事项

1. 参数 url 是必需的，确保与 cookie 所属页面完全匹配。
2. 如果未找到匹配的 cookie，回调函数接收 null。

4. chrome.cookies.getAll

4.1 方法功能

检索与指定条件匹配的所有 cookies。常用于批量操作，比如显示用户所有偏好设置，或调试扩展的 cookie 行为。

4.2 使用方法

chrome.cookies.getAll({ domain: "example.com" }, function(cookies) {
  console.log("Found cookies:", cookies);
});

4.3 参数详解

• details：一个对象，包含查询条件。
  • url (string)：可选。限定匹配 cookies 的 URL。
  • domain (string)：可选。限定匹配 cookies 的域。
• callback：一个函数，接收返回的 cookie 数组。

4.4 实际样例

• 示例代码：

chrome.cookies.getAll({ domain: "example.com" }, function(cookies) {
  cookies.forEach(cookie => {
    console.log(`${cookie.name}: ${cookie.value}`);
  });
});

4.5 注意事项

1. 返回的数组可能为空，表示未找到符合条件的 cookies。
2. 查询条件支持多字段组合。

5. chrome.cookies.set

5.1 方法功能

为指定的 URL 设置 cookies。此方法常用于保存用户偏好，例如选择的主题颜色或语言。

5.2 使用方法

chrome.cookies.set({
  url: "https://example.com",
  name: "theme",
  value: "dark_mode"
}, function(cookie) {
  console.log("Cookie set:", cookie);
});

5.3 参数详解

• details：一个对象，包含需要设置的 cookie 信息。
  • url (string)：必须。目标 cookie 的 URL。
  • name (string)：可选。cookie 的名称。
  • value (string)：可选。cookie 的值。
• callback：一个函数，接收新创建的 cookie 对象。

5.4 实际样例

• 示例代码：

chrome.cookies.set({
  url: "https://example.com",
  name: "user_id",
  value: "12345"
}, function(cookie) {
  console.log("User ID saved.");
});

5.5 注意事项

1. 确保 url 与扩展权限范围一致。
2. 如果设置失败，回调函数不会接收到返回值。

6. chrome.cookies.remove

6.1 方法功能

删除指定的 cookie。这对安全相关操作尤为重要，例如用户登出时清除会话数据。

6.2 使用方法

chrome.cookies.remove({
  url: "https://example.com",
  name: "session_id"
}, function(details) {
  console.log("Cookie removed:", details);
});

6.3 参数详解

• details：一个对象，指定要删除的 cookie。
  • url (string)：必须。cookie 所属的 URL。
  • name (string)：必须。cookie 的名称。

6.4 实际样例

• 示例代码：

chrome.cookies.remove({
  url: "https://example.com",
  name: "user_id"
}, function() {
  console.log("User logged out.");
});

6.5 注意事项

1. 删除操作不会影响硬盘上的缓存文件。
2. 操作完成后，返回一个表示结果的对象。

7. chrome.cookies.onChanged

7.1 方法功能

监听 cookie 的更改事件。适用于实时响应用户行为，例如动态更新 UI 或同步多设备设置。

7.2 使用方法

chrome.cookies.onChanged.addListener(function(changeInfo) {
  if (changeInfo.removed) {
    console.log("Cookie removed:", changeInfo.cookie);
  } else {
    console.log("Cookie added/updated:", changeInfo.cookie);
  }
});

7.3 参数详解

• callback：接收事件详情的函数。
  • 包含 removed（布尔值）和 cookie（对象）。

7.4 实际样例

• 示例代码：

chrome.cookies.onChanged.addListener(function(changeInfo) {
  if (!changeInfo.removed) {
    alert("Preferences updated.");
  }
});

7.5 注意事项

1. 此事件仅通知更改，具体信息需从回调中提取。
2. 监听器可能频繁触发，需优化性能。

4. 注意事项

1. 权限声明：确保在扩展的 manifest.json 文件中声明所需权限。
2. chrome.cookies API 仅适用于扩展进程，不能直接在网页脚本中使用。
3. 使用 chrome.cookies.set 时，确保 cookie 的 URL 与扩展的权限范围一致。

5. 总结

本文档详细介绍了 chrome.cookies API 的功能和实际使用场景，并通过带有英文注释的示例代码帮助开发者更好地理解其功能。在下一篇文章中，我们将探讨如何结合 chrome.storage API 实现高级数据管理功能。