chrome.bookmarks
- Description
Use the
chrome.bookmarks
API to create, organize, and otherwise manipulate bookmarks. Also see Override Pages, which you can use to create a custom Bookmark Manager page. - Permissions
bookmarks
Manifest #
You must declare the "bookmarks" permission in the extension manifest to use the bookmarks API. For example:
{
"name": "My extension",
...
"permissions": [
"bookmarks"
],
...
}
Objects and properties #
Bookmarks are organized in a tree, where each node in the tree is either a bookmark or a folder (sometimes called a group). Each node in the tree is represented by a bookmarks.BookmarkTreeNode object.
BookmarkTreeNode
properties are used throughout the chrome.bookmarks
API. For example, when you call bookmarks.create, you pass in the new node's parent (parentId
), and, optionally, the node's index
, title
, and url
properties. See bookmarks.BookmarkTreeNode for information about the properties a node can have.
Note: You cannot use this API to add or remove entries in the root folder. You also cannot rename, move, or remove the special "Bookmarks Bar" and "Other Bookmarks" folders.
Examples #
The following code creates a folder with the title "Extension bookmarks". The first argument to create()
specifies properties for the new folder. The second argument defines a function to be executed after the folder is created.
chrome.bookmarks.create(
{'parentId': bookmarkBar.id, 'title': 'Extension bookmarks'},
function(newFolder) {
console.log("added folder: " + newFolder.title);
},
);
The next snippet creates a bookmark pointing to the developer documentation for extensions. Since nothing bad will happen if creating the bookmark fails, this code doesn't bother to define a callback function.
chrome.bookmarks.create({
'parentId': extensionsFolderId,
'title': 'Extensions doc',
'url': 'http://code.google.com/chrome/extensions',
});
For an example of using this API, see the basic bookmarks sample. For other examples and for help in viewing the source code, see Samples.
Summary
- Types
- Properties
- Methods
chrome.bookmarks.create(bookmark: CreateDetails, callback: function)
chrome.bookmarks.get(idOrIdList: string | string[], callback: function)
chrome.bookmarks.getChildren(id: string, callback: function)
chrome.bookmarks.getRecent(numberOfItems: number, callback: function)
chrome.bookmarks.getSubTree(id: string, callback: function)
chrome.bookmarks.getTree(callback: function)
chrome.bookmarks.move(id: string, destination: object, callback: function)
chrome.bookmarks.remove(id: string, callback: function)
chrome.bookmarks.removeTree(id: string, callback: function)
chrome.bookmarks.search(query: string | object, callback: function)
chrome.bookmarks.update(id: string, changes: object, callback: function)
- Events
Types
BookmarkTreeNode
A node (either a bookmark or a folder) in the bookmark tree. Child nodes are ordered within their parent folder.
Properties
- childrenBookmarkTreeNode[] optional
An ordered list of children of this node.
- dateAddednumber optional
When this node was created, in milliseconds since the epoch (
new Date(dateAdded)
). - dateGroupModifiednumber optional
When the contents of this folder last changed, in milliseconds since the epoch.
- idstring
The unique identifier for the node. IDs are unique within the current profile, and they remain valid even after the browser is restarted.
- indexnumber optional
The 0-based position of this node within its parent folder.
- parentIdstring optional
The
id
of the parent folder. Omitted for the root node. - titlestring
The text displayed for the node.
- unmodifiableBookmarkTreeNodeUnmodifiable optional
Indicates the reason why this node is unmodifiable. The managed value indicates that this node was configured by the system administrator or by the custodian of a supervised user. Omitted if the node can be modified by the user and the extension (default).
- urlstring optional
The URL navigated to when a user clicks the bookmark. Omitted for folders.
CreateDetails
Object passed to the create() function.
Properties
- indexnumber optional
- parentIdstring optional
Defaults to the Other Bookmarks folder.
- titlestring optional
- urlstring optional
BookmarkTreeNodeUnmodifiable
Indicates the reason why this node is unmodifiable. The managed value indicates that this node was configured by the system administrator. Omitted if the node can be modified by the user and the extension (default).
Enum
"managed"
Properties
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
Deprecated. Bookmark write operations are no longer limited by Chrome.
Value
MAX_WRITE_OPERATIONS_PER_HOUR
Deprecated. Bookmark write operations are no longer limited by Chrome.
Value
Methods
create
chrome.bookmarks.create(bookmark: CreateDetails, callback: function)
Creates a bookmark or folder under the specified parentId. If url is NULL or missing, it will be a folder.
Parameters
- bookmark
- callbackfunction
The callback parameter should be a function that looks like this:
(result: BookmarkTreeNode) => {...}
- result
get
chrome.bookmarks.get(idOrIdList: string | string[], callback: function)
Retrieves the specified BookmarkTreeNode(s).
Parameters
- idOrIdListstring | string[]
A single string-valued id, or an array of string-valued ids
- callbackfunction
The callback parameter should be a function that looks like this:
(results: BookmarkTreeNode[]) => {...}
- results
getChildren
chrome.bookmarks.getChildren(id: string, callback: function)
Retrieves the children of the specified BookmarkTreeNode id.
Parameters
- idstring
- callbackfunction
The callback parameter should be a function that looks like this:
(results: BookmarkTreeNode[]) => {...}
- results
getRecent
chrome.bookmarks.getRecent(numberOfItems: number, callback: function)
Retrieves the recently added bookmarks.
Parameters
- numberOfItemsnumber
The maximum number of items to return.
- callbackfunction
The callback parameter should be a function that looks like this:
(results: BookmarkTreeNode[]) => {...}
- results
getSubTree
chrome.bookmarks.getSubTree(id: string, callback: function)
Retrieves part of the Bookmarks hierarchy, starting at the specified node.
Parameters
- idstring
The ID of the root of the subtree to retrieve.
- callbackfunction
The callback parameter should be a function that looks like this:
(results: BookmarkTreeNode[]) => {...}
- results
getTree
chrome.bookmarks.getTree(callback: function)
Retrieves the entire Bookmarks hierarchy.
Parameters
- callbackfunction
The callback parameter should be a function that looks like this:
(results: BookmarkTreeNode[]) => {...}
- results
move
chrome.bookmarks.move(id: string, destination: object, callback: function)
Moves the specified BookmarkTreeNode to the provided location.
Parameters
- idstring
- destinationobject
- indexnumber optional
- parentIdstring optional
- callbackfunction
The callback parameter should be a function that looks like this:
(result: BookmarkTreeNode) => {...}
- result
remove
chrome.bookmarks.remove(id: string, callback: function)
Removes a bookmark or an empty bookmark folder.
Parameters
- idstring
- callbackfunction
The callback parameter should be a function that looks like this:
() => {...}
removeTree
chrome.bookmarks.removeTree(id: string, callback: function)
Recursively removes a bookmark folder.
Parameters
- idstring
- callbackfunction
The callback parameter should be a function that looks like this:
() => {...}
search
chrome.bookmarks.search(query: string | object, callback: function)
Searches for BookmarkTreeNodes matching the given query. Queries specified with an object produce BookmarkTreeNodes matching all specified properties.
Parameters
- querystring | object
Either a string of words and quoted phrases that are matched against bookmark URLs and titles, or an object. If an object, the properties
query
,url
, andtitle
may be specified and bookmarks matching all specified properties will be produced. - callbackfunction
The callback parameter should be a function that looks like this:
(results: BookmarkTreeNode[]) => {...}
- results
update
chrome.bookmarks.update(id: string, changes: object, callback: function)
Updates the properties of a bookmark or folder. Specify only the properties that you want to change; unspecified properties will be left unchanged. Note: Currently, only 'title' and 'url' are supported.
Parameters
- idstring
- changesobject
- titlestring optional
- urlstring optional
- callbackfunction
The callback parameter should be a function that looks like this:
(result: BookmarkTreeNode) => {...}
- result
Events
onChanged
chrome.bookmarks.onChanged.addListener(listener: function)
Fired when a bookmark or folder changes. Note: Currently, only title and url changes trigger this.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(id: string, changeInfo: object) => {...}
- idstring
- changeInfoobject
- titlestring
- urlstring optional
onChildrenReordered
chrome.bookmarks.onChildrenReordered.addListener(listener: function)
Fired when the children of a folder have changed their order due to the order being sorted in the UI. This is not called as a result of a move().
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(id: string, reorderInfo: object) => {...}
- idstring
- reorderInfoobject
- childIdsstring[]
onCreated
chrome.bookmarks.onCreated.addListener(listener: function)
Fired when a bookmark or folder is created.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(id: string, bookmark: BookmarkTreeNode) => {...}
- idstring
- bookmark
onImportBegan
chrome.bookmarks.onImportBegan.addListener(listener: function)
Fired when a bookmark import session is begun. Expensive observers should ignore onCreated updates until onImportEnded is fired. Observers should still handle other notifications immediately.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
() => {...}
onImportEnded
chrome.bookmarks.onImportEnded.addListener(listener: function)
Fired when a bookmark import session is ended.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
() => {...}
onMoved
chrome.bookmarks.onMoved.addListener(listener: function)
Fired when a bookmark or folder is moved to a different parent folder.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(id: string, moveInfo: object) => {...}
- idstring
- moveInfoobject
- indexnumber
- oldIndexnumber
- oldParentIdstring
- parentIdstring
onRemoved
chrome.bookmarks.onRemoved.addListener(listener: function)
Fired when a bookmark or folder is removed. When a folder is removed recursively, a single notification is fired for the folder, and none for its contents.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(id: string, removeInfo: object) => {...}
- idstring
- removeInfoobject
- indexnumber
- node
- parentIdstring