使用書籤 API - Mozilla | MDN

Permissions

要使用書籤 API，您需要在擴充套件程式的 manifest.json 檔案中請求 "bookmarks" 許可權。

json

"permissions": [
  "bookmarks"
],

功能

書籤 API 允許您的擴充套件程式執行使用者可以使用書籤執行的操作，幷包含用於以下功能的函式：

基本書籤項操作，提供：
- 新增（bookmarks.create）。
- 檢索（bookmarks.get）。
- 更新（bookmarks.update）。
- 移動（bookmarks.move）。
- 刪除（bookmarks.remove）。
- 搜尋（bookmarks.search）。
獲取最近新增的書籤列表（bookmarks.getRecent）。
書籤資料夾樹操作，用於：
- 獲取樹資訊（bookmarks.getTree、bookmarks.getChildren 和 bookmarks.getSubTree）。
- 新增分支（bookmarks.create）。
- 刪除節點（bookmarks.removeTree）。
- 移動節點（bookmarks.move）。
監聽書籤（或書籤樹資料夾）事件，這些事件包括：
- 新增（bookmarks.onCreated）。
- 更改（bookmarks.onChanged）。
- 移動（bookmarks.onMoved）。
- 重新排序（bookmarks.onChildrenReordered）。
- 刪除（bookmarks.onRemoved）。
監聽書籤匯入，這可以用於在匯入過程中暫停其他書籤處理。
- 匯入開始（bookmarks.onImportBegan）。
- 匯入結束（bookmarks.onImportEnded）。

示例詳解

為了更好地理解如何使用書籤 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/bookmark-it@2x.png"
  },

請求許可權。請求 "bookmarks" 以啟用書籤 API 的使用。請求 "tabs" 以便讀取活動標籤頁的 URL 和標題，並用於建立或查詢頁面的書籤。訪問這些詳細資訊需要 Tabs API，這意味著您不太可能在不使用 Tabs API 的情況下使用 Bookmark 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 獲取當前標籤頁的 Tabs 物件，然後使用以下程式碼將該物件傳遞給 updateTab()。

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

updateTab() 首先將活動標籤頁的 URL 傳遞給 isSupportedProtocol()。如果協議受書籤支援，則擴充套件程式會確定標籤頁的 URL 是否已被收藏，如果已收藏，則呼叫 updateIcon()。

function updateTab(tabs) {
  if (tabs[0]) {
    currentTab = tabs[0];
    if (isSupportedProtocol(currentTab.url)) {
      let searching = browser.bookmarks.search({ url: currentTab.url });
      searching.then((bookmarks) => {
        currentBookmark = bookmarks[0];
        updateIcon();
      });
    } else {
      console.log(`Bookmark it! does not support the '${currentTab.url}' URL.`);
    }
  }
}

isSupportedProtocol() 確定活動標籤頁中顯示的 URL 是否可以被收藏。為了從標籤頁的 URL 中提取協議，擴充套件程式利用了 HTMLAnchorElement，透過將標籤頁的 URL 新增到一個 <a> 元素中，然後使用 protocol 屬性獲取協議。

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

updateIcon() 根據 URL 是否被收藏來設定工具欄按鈕的圖示和標題。

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()。

browser.browserAction.onClicked.addListener(toggleBookmark);

toggleBookmark() 使用 updateTabs() 進行的搜尋結果（該搜尋查詢 URL 是否存在於書籤中）來確定是刪除還是添加當前 URL 的書籤。

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

為了更新工具欄圖示，擴充套件程式會監聽書籤的建立或刪除。這種方法的好處在於可以捕獲擴充套件程式所做的書籤更新以及使用者在擴充套件程式外部所做的任何更新。

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

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

最後，擴充套件程式會監聽活動標籤頁 URL 的更改，或者使用者切換到其他標籤頁或視窗。這些操作可能會更改 URL，從而改變擴充套件程式工具欄圖示的狀態。

// 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);