Arbeiten mit der Bookmarks-API

Um die Bookmarks-API nutzen zu können, müssen Sie in der manifest.json-Datei Ihrer Erweiterung um die Berechtigung "bookmarks" bitten:

"permissions": [
  "bookmarks"
],

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

• Grundlegende Manipulation von Lesezeicheneinträgen, einschließlich:

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

• Abrufen einer Liste kürzlich hinzugefügter Lesezeichen (bookmarks.getRecent).

• Manipulation der Lesezeichenordnerstruktur, um:

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

• Überwachen von Lesezeichen- (oder Lesezeichenbaumordner-)Ereignissen, die:

  • Hinzufügen (bookmarks.onCreated).
  • Ändern (bookmarks.onChanged).
  • Verschieben (bookmarks.onMoved).
  • Neu anordnen (bookmarks.onChildrenReordered).
  • Löschen (bookmarks.onRemoved).

• Überwachen von Lesezeichenimporten, die verwendet werden können, um andere Lesezeichenverarbeitungen auszusetzen, während ein Import im Gange ist:

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

Um zu verstehen, wie man mit der Bookmarks-API arbeitet, werfen Sie einen Blick auf das bookmark-it Beispiel. Dieses Beispiel fügt ein Symbol zur Symbolleiste 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 der Seitenmarkierung 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 in Bereichen wie dem Add-on-Manager darzustellen.

  "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 verwendet werden können, um das Lesezeichen der Seite zu erstellen oder zu finden. Die Notwendigkeit der Tabs-API, um auf diese Details zuzugreifen, bedeutet, dass Sie die Bookmark-API wahrscheinlich nicht ohne die Tabs-API verwenden werden.

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

Richtet die grundlegenden Details der Symbolleistenschaltfläche ein. 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 und entfernt und die Eigenschaften der Symbolleistenschaltfläche festlegt.

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

}

Wie bei jedem Hintergrundskript wird background.js ausgeführt, sobald die Erweiterung gestartet wird. Zu Beginn ruft das Skript updateActiveTab() auf, das mit dem Abrufen des Tabs-Objekts für den aktuellen Tab beginnt, indem tabs.query verwendet wird, und das Objekt an updateTab() mit folgendem Code ü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 URL, die im aktiven Tab angezeigt wird, eine ist, die als Lesezeichen gespeichert werden kann. Um das Protokoll aus der URL des Tabs zu extrahieren, nutzt die Erweiterung das HTMLAnchorElement, indem sie die URL des Tabs zu einem <a>-Element hinzufügt und dann das Protokoll über die protocol-Eigenschaft abruft.

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, bestimmt die Erweiterung, ob die URL des Tabs bereits als Lesezeichen gespeichert ist und ruft, falls dies der Fall ist, updateIcon() auf:

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

updateIcon() setzt das Symbol der Symbolleistenschaltfläche und den Titel, je nachdem, ob die URL als Lesezeichen gespeichert 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,
  });
}

Sobald die Symbolleistenschaltfläche initialisiert ist, beginnt die Erweiterung, auf einen Klick auf die Symbolleistenschaltfläche zu hören und toggleBookmark() zu rufen, wenn dies passiert.

browser.browserAction.onClicked.addListener(toggleBookmark);

toggleBookmark() verwendet das Ergebnis der Suche, die durch updateTabs() gemacht wird, um das Vorhandensein der URL in einem Lesezeichen zu bestimmen, 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 der Symbolleiste zu aktualisieren, hört die Erweiterung auf das Erstellen oder Entfernen von Lesezeichen. Dieser Ansatz hat den Vorteil, dass sowohl die Lesezeichenaktualisierung erfasst wird, die durch die Erweiterung vorgenommen wird, als auch jede Aktualisierung, die vom Benutzer außerhalb der Erweiterung vorgenommen wird.

// 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 daher den Status des Symbols der Symbolleiste 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, schauen Sie sich das Bookmarks API Referenz an.