Bookmarks enable users to collect and organize lists of web pages, so they can easily get back to their favorites. Using the Bookmarks API, your extensions can manipulate bookmarks in much the same way users can.
To make use of the Bookmarks API, you need to ask for the
"bookmarks"
permission in your extension’s manifest.json file:
"permissions": [
"bookmarks"
],
The Bookmarks API lets your extension do the things users can do with bookmarks and includes functions for:
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
).
To gain an understanding of how to work with the Bookmarks API let’s take a look at the
bookmark-it
example. This example adds a toolbar icon (
browserAction
) which, when clicked, adds or removes the current page from bookmarks. If the page is bookmarked (or removed from bookmarks) in some other way, the icon is updated to show the state of the page’s bookmarking.
This video shows the extension in action:
manifest.json describes the extension:
{
"manifest_version": 2,
"name": "Bookmark it!",
"version": "1.1",
"description": "A simple bookmark button",
"homepage_url": "https://github.com/mdn/webextensions-examples/tree/master/bookmark-it",
Defines the icons that’ll be used to represent the extension, in places such as the add-on manager.
"icons": {
"48": "icons/bookmark-it.png",
"96": "icons/bookmark-it@2x.png"
},
Requests permissions.
"bookmarks"
is requested to enable use of the Bookmarks API.
"tabs"
is requested so that the active tab’s URL and title can be read and used to create or find the page’s bookmark. The need for the Tabs API to access these details means that you’re unlikely to use the Bookmark API without the Tabs API.
"permissions": [
"bookmarks",
"tabs"
],
Sets up the basic toolbar button details. Most of the button’s features will be set up in code after the page’s bookmark status is known.
"browser_action": {
"default_icon": "icons/star-empty-38.png",
"default_title": "Bookmark it!"
},
Defines the background script that’ll add and remove the page’s bookmark and set the characteristics of the toolbar button.
"background": {
"scripts": ["background.js"]
}
}
As with any background script,
background.js
is run as soon as the extension is started. Initially the script calls
updateActiveTab()
that starts by obtaining the
Tabs
object for the current tab, using
tabs.query
, and passing the object to
updatetab()
with this code:
var gettingActiveTab = browser.tabs.query({active: true, currentWindow: true});
gettingActiveTab.then(updateTab);
updatetab()
first passes the active tab’s URL to
isSupportedProtocol()
:
function updateTab(tabs) {
if (tabs[0]) {
currentTab = tabs[0];
if (isSupportedProtocol(currentTab.url)) {
isSupportedProtocol()
determines if the URL displayed in the active tab is one that can be bookmarked. To extract the protocol from the tab’s URL, the extension takes advantage of the
HTMLAnchorElement
by adding the tab’s URL to an
<a>
element and then getting the protocol using the
协议
特性。
function isSupportedProtocol(urlString) {
var supportedProtocols = ["https:", "http:", "file:"];
var url = document.createElement('a');
url.href = urlString;
return supportedProtocols.indexOf(url.protocol) != -1;
}
If the protocol is one supported by bookmarks, the extension determines if the tab’s URL is already bookmarked and if it is, calls
updateIcon()
:
var searching = browser.bookmarks.search({url: currentTab.url});
searching.then((bookmarks) => {
currentBookmark = bookmarks[0];
updateIcon();
updateIcon()
sets the toolbar button’s icon and title, depending on whether the URL is bookmarked or not.
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
});
}
With the toolbar button initialized, the extension starts listening for a click on the toolbar button, calling
toggleBookmark()
when that happens.
browser.browserAction.onClicked.addListener(toggleBookmark);
toggleBookmark()
uses the result from the search made by
updateTabs()
, which looks for the presence of the URL in a bookmark, to determine whether to remove or add a bookmark for the current URL.
function toggleBookmark() {
if (currentBookmark) {
browser.bookmarks.remove(currentBookmark.id);
} else {
browser.bookmarks.create({title: currentTab.title, url: currentTab.url});
}
}
To update the toolbar icon, the extension listens for the creation or removal of bookmarks. This approach has the benefit of capturing both the bookmark update made by the extension and any update made by the user outside the extension.
// listen for bookmarks being created
browser.bookmarks.onCreated.addListener(updateActiveTab);
// listen for bookmarks being removed
browser.bookmarks.onRemoved.addListener(updateActiveTab);
Finally, the extension listens for a change to the active tab’s URL, or the user switching to another tab or window. These actions could change the viewed URL and therefore the status of the extension’s toolbar icon.
// 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);
If you want to learn more, check out the Bookmarks API reference .
最后修改： , 由 MDN 贡献者