使用书签 API

书签允许用户收集和整理网页列表，以便他们能够轻松地返回到其收藏夹。使用书签 API，您的扩展可以像用户一样操作书签。

权限

要使用书签 API，您需要在扩展的 manifest.json 文件中请求“书签”权限。

json
"permissions": [
  "bookmarks"
],

功能

书签 API 允许您的扩展执行用户可以使用书签执行的操作，并包含以下功能：

示例演练

为了了解如何使用书签 API，让我们看看 bookmark-it 示例。此示例添加了一个工具栏图标 (browserAction)，单击该图标可以添加或删除当前页面到书签中。如果页面以其他方式被添加书签（或从书签中删除），则图标会更新以显示页面书签状态。

此视频展示了扩展的实际操作

manifest.json

该 manifest.json 描述了扩展

json
{
  "manifest_version": 2,
  "name": "Bookmark it!",
  "version": "1.1",
  "description": "A simple bookmark button",
  "homepage_url": "https://github.com/mdn/webextensions-examples/tree/main/bookmark-it",

定义了用于表示扩展的图标，这些图标将在附加组件管理器等地方使用。

json
  "icons": {
    "48": "icons/bookmark-it.png",
    "96": "icons/[email protected]"
  },

请求权限。“书签” 用于启用书签 API。“标签” 用于读取和使用活动标签的 URL 和标题以创建或查找页面的书签。需要使用标签 API 访问这些详细信息，这意味着您不太可能在没有标签 API 的情况下使用书签 API。

json
  "permissions": [
    "bookmarks",
    "tabs"
  ],

设置基本工具栏按钮详细信息。页面书签状态已知后，大多数按钮功能将在代码中设置。

json
  "browser_action": {
    "default_icon": "icons/star-empty-38.png",
    "default_title": "Bookmark it!"
  },

定义了将添加和删除页面的书签并设置工具栏按钮特性的后台脚本。

json
  "background": {
    "scripts": ["background.js"]
  }

}

background.js

与任何后台脚本一样，background.js 在扩展启动后立即运行。最初，脚本调用 updateActiveTab()，该函数首先使用 tabs.query 获取当前标签的 标签 对象，并将该对象传递给 updateTab()，使用以下代码：

js
let gettingActiveTab = browser.tabs.query({
  active: true,
  currentWindow: true,
});
gettingActiveTab.then(updateTab);

updateTab() 首先将活动标签的 URL 传递给 isSupportedProtocol()

js
  function updateTab(tabs) {
    if (tabs[0]) {
      currentTab = tabs[0];
      if (isSupportedProtocol(currentTab.url)) {

isSupportedProtocol() 确定活动标签中显示的 URL 是否可以添加书签。为了从标签的 URL 中提取协议，扩展利用了 HTMLAnchorElement，将标签的 URL 添加到 <a> 元素中，然后使用 protocol 属性获取协议。

js
function isSupportedProtocol(urlString) {
  let supportedProtocols = ["https:", "http:", "file:"];
  let url = document.createElement("a");
  url.href = urlString;
  return supportedProtocols.includes(url.protocol);
}

如果协议是书签支持的协议，则扩展会确定标签的 URL 是否已经被添加书签，如果是，则调用 updateIcon()

js
      let searching = browser.bookmarks.search({url: currentTab.url});
      searching.then((bookmarks) => {
        currentBookmark = bookmarks[0];
        updateIcon();

updateIcon() 设置工具栏按钮的图标和标题，具体取决于 URL 是否被添加书签。

js
function updateIcon() {
  browser.browserAction.setIcon({
    path: currentBookmark
      ? {
          19: "icons/star-filled-19.png",
          38: "icons/star-filled-38.png",
        }
      : {
          19: "icons/star-empty-19.png",
          38: "icons/star-empty-38.png",
        },
    tabId: currentTab.id,
  });
  browser.browserAction.setTitle({
    // Screen readers can see the title
    title: currentBookmark ? "Unbookmark it!" : "Bookmark it!",
    tabId: currentTab.id,
  });
}

工具栏按钮初始化后，扩展开始监听工具栏按钮的点击事件，当事件发生时调用 toggleBookmark()。

js
browser.browserAction.onClicked.addListener(toggleBookmark);

toggleBookmark() 使用 updateTabs() 执行的搜索结果（该搜索结果查找 URL 是否存在于书签中）来确定是删除还是添加当前 URL 的书签。

js
function toggleBookmark() {
  if (currentBookmark) {
    browser.bookmarks.remove(currentBookmark.id);
  } else {
    browser.bookmarks.create({ title: currentTab.title, url: currentTab.url });
  }
}

为了更新工具栏图标，扩展监听书签的创建或删除事件。这种方法的优点是可以同时捕获扩展执行的书签更新和用户在扩展之外执行的任何更新。

js
// listen for bookmarks being created
browser.bookmarks.onCreated.addListener(updateActiveTab);

// listen for bookmarks being removed
browser.bookmarks.onRemoved.addListener(updateActiveTab);

最后，扩展监听活动标签 URL 的更改，或用户切换到另一个标签或窗口。这些操作可能会更改查看的 URL，从而更改扩展工具栏图标的状态。

js
// listen to tab URL changes
browser.tabs.onUpdated.addListener(updateActiveTab);

// listen to tab switching
browser.tabs.onActivated.addListener(updateActiveTab);

// listen for window switching
browser.windows.onFocusChanged.addListener(updateActiveTab);

了解更多

如果您想了解更多信息，请查看 书签 API 参考.