Arbeiten mit der Bookmarks API

Um die Bookmarks API zu nutzen, müssen Sie die Berechtigung "bookmarks" in der Datei manifest.json Ihrer Erweiterung anfordern:

"permissions": [
  "bookmarks"
],

Die Bookmarks API ermöglicht es Ihrer Erweiterung, die Dinge mit Lesezeichen zu tun, die Benutzer auch tun können, und umfasst Funktionen für:

• Grundlegende Manipulation von Lesezeichen, einschließlich:

  • Hinzufügen (bookmarks.create).
  • Abrufen (bookmarks.get).
  • Aktualisieren (bookmarks.update).
  • Verschieben (bookmarks.move).
  • Löschen (bookmarks.remove).
  • Suchen (bookmarks.search).

• Erhalten einer Liste von kürzlich hinzugefügten Lesezeichen (bookmarks.getRecent).

• Manipulation des Lesezeichen-Ordnerbaums, um:

  • Bauminformationen abzurufen (bookmarks.getTree, bookmarks.getChildren und bookmarks.getSubTree).
  • Äste hinzuzufügen (bookmarks.create).
  • Knoten zu löschen (bookmarks.removeTree).
  • Knoten zu verschieben (bookmarks.move).

• Überwachen von Ereignissen bei Lesezeichen (oder Lesezeichenordnern), die:

  • Hinzufügen (bookmarks.onCreated).
  • Änderungen (bookmarks.onChanged).
  • Verschieben (bookmarks.onMoved).
  • Umordnen (bookmarks.onChildrenReordered).
  • Löschen (bookmarks.onRemoved).

• Überwachen von Lesezeichenimporten, die genutzt werden können, um andere Lesezeichenverarbeitungen während eines laufenden Imports auszusetzen:

  • Import gestartet (bookmarks.onImportBegan).
  • Import abgeschlossen (bookmarks.onImportEnded).

Um zu verstehen, wie man mit der Bookmarks API arbeitet, betrachten wir das Beispiel bookmark-it. Dieses Beispiel fügt ein Symbol in der Werkzeugleiste hinzu (browserAction), das beim Klicken die aktuelle Seite zu den Lesezeichen hinzufügt oder daraus entfernt. Wenn die Seite auf andere Weise zu den Lesezeichen hinzugefügt oder daraus entfernt wird, wird das Symbol aktualisiert, um den Status des Lesezeichens der Seite anzuzeigen.

Dieses Video zeigt die Erweiterung in Aktion:

Die manifest.json beschreibt die Erweiterung:

{
  "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",

Definiert die Symbole, die verwendet werden, um die Erweiterung darzustellen, beispielsweise im Add-on-Manager.

  "icons": {
    "48": "icons/bookmark-it.png",
    "96": "icons/bookmark-it@2x.png"
  },

Fordert Berechtigungen an. "bookmarks" wird angefordert, um die Nutzung der Bookmarks API zu ermöglichen. "tabs" wird angefordert, damit die URL und der Titel des aktiven Tabs gelesen und zur Erstellung oder Suche des Lesezeichens der Seite verwendet werden können. Da zur Nutzung dieser Details die Tabs API benötigt wird, werden Sie die Bookmark API wahrscheinlich nicht ohne die Tabs API nutzen.

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

Legt die grundlegenden Details für die Schaltfläche in der Werkzeugleiste fest. Die meisten Funktionen der Schaltfläche werden im Code eingerichtet, nachdem der Lesezeichenstatus der Seite bekannt ist.

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

Definiert das Hintergrundskript, das das Lesezeichen der Seite hinzufügt oder entfernt und die Merkmale der Schaltfläche in der Werkzeugleiste festlegt.

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

}

Wie bei jedem Hintergrundskript wird background.js ausgeführt, sobald die Erweiterung gestartet wird. Anfangs ruft das Skript updateActiveTab() auf, das beginnt, indem es das Tabs-Objekt für den aktuellen Tab mit tabs.query abruft und das Objekt mit folgendem Code an updateTab() übergibt:

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

updateTab() übergibt zuerst die URL des aktiven Tabs an isSupportedProtocol():

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

isSupportedProtocol() bestimmt, ob die in der aktiven Registerkarte angezeigte URL eine ist, die in einem Lesezeichen gespeichert werden kann. Um das Protokoll von der URL der Registerkarte zu extrahieren, nutzt die Erweiterung das HTMLAnchorElement, indem sie die URL der Registerkarte zu einem <a>-Element hinzufügt und dann das Protokoll über die protocol-Eigenschaft abfragt.

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

Wenn das Protokoll eines ist, das von Lesezeichen unterstützt wird, überprüft die Erweiterung, ob die URL des Tabs bereits in einem Lesezeichen gespeichert ist, und wenn ja, ruft sie updateIcon() auf:

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

updateIcon() setzt das Symbol und den Titel der Schaltfläche in der Werkzeugleiste, abhängig davon, ob die URL in einem Lesezeichen enthalten ist oder nicht.

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,
  });
}

Nach der Initialisierung der Schaltfläche in der Werkzeugleiste beginnt die Erweiterung, auf einen Klick auf die Schaltfläche zu hören, und ruft bei diesem Ereignis toggleBookmark() auf.

browser.browserAction.onClicked.addListener(toggleBookmark);

toggleBookmark() verwendet das Ergebnis der Suche, die von updateTabs() durchgeführt wurde, um festzustellen, ob ein Lesezeichen für die aktuelle URL entfernt oder hinzugefügt werden soll.

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

Um das Symbol in der Werkzeugleiste zu aktualisieren, hört die Erweiterung auf die Erstellung oder Entfernung von Lesezeichen. Dieser Ansatz hat den Vorteil, sowohl die von der Erweiterung vorgenommene Lesezeichenaktualisierung als auch jede vom Benutzer außerhalb der Erweiterung vorgenommene Aktualisierung zu erfassen.

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

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

Schließlich hört die Erweiterung auf eine Änderung der URL des aktiven Tabs oder darauf, dass der Benutzer zu einem anderen Tab oder Fenster wechselt. Diese Aktionen könnten die angezeigte URL ändern und deshalb den Status des Symbols in der Werkzeugleiste der Erweiterung beeinflussen.

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

Wenn Sie mehr erfahren möchten, werfen Sie einen Blick auf die Bookmarks API-Referenz.