说明
使用 chrome.bookmarks
API 创建、整理书签以及以其他方式操纵书签。另请参阅替换网页,您可以使用该网页创建自定义“书签管理器”页面。
![点击星标即可添加书签](https://developer.chrome.google.cn/static/docs/extensions/reference/api/images/bookmarks.png?authuser=6&hl=da)
权限
bookmarks
您必须在扩展程序清单中声明“书签”权限,才能使用 bookmarks API。 例如:
{
"name": "My extension",
...
"permissions": [
"bookmarks"
],
...
}
概念和用法
对象和属性
书签以树状组织结构,树中的每个节点都是书签或文件夹(有时称为组)。树中的每个节点都由一个 bookmarks.BookmarkTreeNode 对象表示。
BookmarkTreeNode
属性在整个 chrome.bookmarks
API 中使用。例如,当您调用 bookmarks.create 时,您将传入新节点的父节点 (parentId
) 以及该节点的 index
、title
和 url
属性(可选)。如需了解节点可以具有的属性,请参阅 bookmarks.BookmarkTreeNode。
示例
以下代码会创建一个标题为“扩展程序书签”的文件夹。create()
的第一个参数指定新文件夹的属性。第二个参数定义在创建文件夹后要执行的函数。
chrome.bookmarks.create(
{'parentId': bookmarkBar.id, 'title': 'Extension bookmarks'},
function(newFolder) {
console.log("added folder: " + newFolder.title);
},
);
下一个代码段会创建一个书签,指向扩展程序的开发者文档。由于如果创建书签失败不会产生任何不良后果,因此此代码无需定义回调函数。
chrome.bookmarks.create({
'parentId': extensionsFolderId,
'title': 'Extensions doc',
'url': 'https://developer.chrome.com/docs/extensions',
});
若要试用此 API,请从 chrome-extension-samples 代码库安装 bookmarks API 示例。
类型
BookmarkTreeNode
书签树中的节点(书签或文件夹)。子节点在其父文件夹中按顺序排列。
属性
-
孩子
BookmarkTreeNode[] 可选
此节点的子节点的有序列表。
-
dateAdded
数字可选
此节点的创建时间,以自纪元 (
new Date(dateAdded)
) 起计的毫秒数表示。 -
dateGroupModified
数字可选
此文件夹内容的上次更改时间(以毫秒为单位,从 Epoch 起算)。
-
dateLastUsed
数字可选
Chrome 114 及更高版本此节点上次打开的时间(以毫秒为单位,从 Epoch 起算)。未针对文件夹进行设置。
-
id
string
节点的唯一标识符。ID 在当前个人资料中是唯一的,即使在浏览器重新启动后仍然有效。
-
索引
数字可选
此节点在其父文件夹中的位置(从 0 开始)。
-
parentId
字符串(可选)
父级文件夹的
id
。对于根节点,此字段省略。 -
title
string
为节点显示的文本。
-
不可修改
可选
表示此节点不可修改的原因。
managed
值表示此节点由系统管理员或受监督用户的保管人配置。如果用户和扩展程序可以修改节点,则省略(默认)。 -
网址
字符串(可选)
用户点击书签后会前往的网址。文件夹可省略此项。
BookmarkTreeNodeUnmodifiable
表示此节点不可修改的原因。managed
值表示此节点由系统管理员配置。如果用户和扩展程序可以修改节点,则省略(默认)。
值
CreateDetails
传递给 create() 函数的对象。
属性
-
索引
数字可选
-
parentId
字符串(可选)
默认设置为“其他书签”文件夹。
-
title
字符串(可选)
-
网址
字符串(可选)
属性
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
书签写入操作不再受 Chrome 限制。
值
100 万
MAX_WRITE_OPERATIONS_PER_HOUR
书签写入操作不再受 Chrome 限制。
值
100 万
方法
create()
chrome.bookmarks.create(
bookmark: CreateDetails,
callback?: function,
)
在指定 parentId 下创建书签或文件夹。如果网址为 NULL 或缺失,则将是一个文件夹。
参数
-
添加书签
-
callback
函数(可选)
callback
参数如下所示:(result: BookmarkTreeNode) => void
返回
-
Promise<BookmarkTreeNode>
Chrome 90 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
get()
chrome.bookmarks.get(
idOrIdList: string | [string, ...string[]],
callback?: function,
)
检索指定的 bookmarkTreeNode。
参数
-
idOrIdList
字符串 | [字符串, ...字符串 []]
单个字符串值 ID,或字符串值 ID 数组
-
callback
函数(可选)
callback
参数如下所示:(results: BookmarkTreeNode[]) => void
-
结果
-
返回
-
Promise<BookmarkTreeNode[]>
Chrome 90 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getChildren()
chrome.bookmarks.getChildren(
id: string,
callback?: function,
)
检索指定 bookmarkTreeNode ID 的子项。
参数
-
id
string
-
callback
函数(可选)
callback
参数如下所示:(results: BookmarkTreeNode[]) => void
-
结果
-
返回
-
Promise<BookmarkTreeNode[]>
Chrome 90 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getRecent()
chrome.bookmarks.getRecent(
numberOfItems: number,
callback?: function,
)
检索最近添加的书签。
参数
-
numberOfItems
number
要返回的最大项目数。
-
callback
函数(可选)
callback
参数如下所示:(results: BookmarkTreeNode[]) => void
-
结果
-
返回
-
Promise<BookmarkTreeNode[]>
Chrome 90 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getSubTree()
chrome.bookmarks.getSubTree(
id: string,
callback?: function,
)
检索书签层次结构的一部分,从指定节点开始。
参数
-
id
string
要检索的子树根的 ID。
-
callback
函数(可选)
callback
参数如下所示:(results: BookmarkTreeNode[]) => void
-
结果
-
返回
-
Promise<BookmarkTreeNode[]>
Chrome 90 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getTree()
chrome.bookmarks.getTree(
callback?: function,
)
检索整个书签层次结构。
参数
-
callback
函数(可选)
callback
参数如下所示:(results: BookmarkTreeNode[]) => void
-
结果
-
返回
-
Promise<BookmarkTreeNode[]>
Chrome 90 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
move()
chrome.bookmarks.move(
id: string,
destination: object,
callback?: function,
)
将指定的 bookmarkTreeNode 移至指定位置。
参数
-
id
string
-
目标账号
对象
-
索引
数字可选
-
parentId
字符串(可选)
-
-
callback
函数(可选)
callback
参数如下所示:(result: BookmarkTreeNode) => void
返回
-
Promise<BookmarkTreeNode>
Chrome 90 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
remove()
chrome.bookmarks.remove(
id: string,
callback?: function,
)
移除书签或空的书签文件夹。
参数
-
id
string
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 90 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
removeTree()
chrome.bookmarks.removeTree(
id: string,
callback?: function,
)
以递归方式移除书签文件夹。
参数
-
id
string
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 90 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
search()
chrome.bookmarks.search(
query: string | object,
callback?: function,
)
搜索与指定查询匹配的 bookmarkTreeNodes。使用对象指定的查询会生成与所有指定属性匹配的 bookmarkTreeNodes。
参数
-
个查询
字符串 | 对象
与书签网址和标题进行匹配的一串字词和带英文引号的短语,或者是一个对象。如果是对象,则可以指定
query
、url
和title
属性,系统会生成与所有指定属性匹配的书签。-
个查询
字符串(可选)
与书签网址和标题进行匹配的一串字词和带英文引号的短语。
-
title
字符串(可选)
书签的标题(逐字匹配)。
-
网址
字符串(可选)
书签的网址;逐字匹配。请注意,文件夹没有网址。
-
-
callback
函数(可选)
callback
参数如下所示:(results: BookmarkTreeNode[]) => void
-
结果
-
返回
-
Promise<BookmarkTreeNode[]>
Chrome 90 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
update()
chrome.bookmarks.update(
id: string,
changes: object,
callback?: function,
)
更新书签或文件夹的属性。请仅指定您要更改的属性;未指定的属性将保持不变。注意:目前仅支持“title”和“url”。
参数
-
id
string
-
更改
对象
-
title
字符串(可选)
-
网址
字符串(可选)
-
-
callback
函数(可选)
callback
参数如下所示:(result: BookmarkTreeNode) => void
返回
-
Promise<BookmarkTreeNode>
Chrome 90 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
活动
onChanged
chrome.bookmarks.onChanged.addListener(
callback: function,
)
在书签或文件夹发生更改时触发。注意:目前,只有标题和网址更改才会触发此事件。
参数
-
callback
功能
callback
参数如下所示:(id: string, changeInfo: object) => void
-
id
string
-
changeInfo
对象
-
title
string
-
网址
字符串(可选)
-
-
onChildrenReordered
chrome.bookmarks.onChildrenReordered.addListener(
callback: function,
)
文件夹的子级因在界面中排序的顺序而更改其顺序时触发。不会因 move() 而调用。
参数
-
callback
功能
callback
参数如下所示:(id: string, reorderInfo: object) => void
-
id
string
-
reorderInfo
对象
-
childIds
字符串[]
-
-
onCreated
chrome.bookmarks.onCreated.addListener(
callback: function,
)
创建书签或文件夹时触发。
参数
-
callback
功能
callback
参数如下所示:(id: string, bookmark: BookmarkTreeNode) => void
-
id
string
-
添加书签
-
onImportBegan
chrome.bookmarks.onImportBegan.addListener(
callback: function,
)
开始书签导入会话时触发。开销大的观察器应忽略 onCreated 更新,直到触发 onImportEnded。观察者仍应立即处理其他通知。
参数
-
callback
功能
callback
参数如下所示:() => void
onImportEnded
chrome.bookmarks.onImportEnded.addListener(
callback: function,
)
在书签导入会话结束时触发。
参数
-
callback
功能
callback
参数如下所示:() => void
onMoved
chrome.bookmarks.onMoved.addListener(
callback: function,
)
当书签或文件夹移动到其他父级文件夹时触发。
参数
-
callback
功能
callback
参数如下所示:(id: string, moveInfo: object) => void
-
id
string
-
moveInfo
对象
-
索引
number
-
oldIndex
number
-
oldParentId
string
-
parentId
string
-
-
onRemoved
chrome.bookmarks.onRemoved.addListener(
callback: function,
)
移除书签或文件夹时触发。以递归方式移除文件夹时,会针对该文件夹触发一条通知,但不会针对其内容触发一条通知。
参数
-
callback
功能
callback
参数如下所示:(id: string, removeInfo: object) => void
-
id
string
-
removeInfo
对象
-
索引
number
-
Chrome 48 及更高版本
-
parentId
string
-
-