说明
使用 chrome.bookmarks
API 创建、整理以及以其他方式操纵书签。另请参阅覆盖网页(可用于创建自定义“书签管理器”页面)。
![点击星形图标可添加书签](https://developer.chrome.google.cn/static/docs/extensions/reference/api/images/bookmarks.png?authuser=7&hl=bg)
权限
bookmarks
{
"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 及更高版本此节点的上次打开时间,以从公元纪年开始计算的毫秒数表示。未设置文件夹。
-
id
字符串
节点的唯一标识符。ID 在当前配置文件中是唯一的,即使在浏览器重新启动后也仍然有效。
-
索引
编号(选填)
此节点在其父文件夹中从 0 开始的位置。
-
parentId
字符串(可选)
父级文件夹的
id
。根节点的省略项。 -
标题
字符串
为节点显示的文本。
-
不可修改
"managed"
可选指示此节点不可修改的原因。
managed
值表示此节点是由系统管理员或受监管用户的监护人配置的。如果节点可以由用户和扩展程序修改,则省略(默认)。 -
网址
字符串(可选)
当用户点击书签时导航到的网址。对于文件夹,可以省略。
BookmarkTreeNodeUnmodifiable
指示此节点不可修改的原因。managed
值表示此节点由系统管理员配置。如果节点可以由用户和扩展程序修改,则省略(默认)。
值
"managed"
CreateDetails
传递给 create() 函数的对象。
属性
-
索引
编号(选填)
-
parentId
字符串(可选)
默认为“其他书签”文件夹。
-
标题
字符串(可选)
-
网址
字符串(可选)
属性
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
书签写入操作不再受 Chrome 的限制。
值
100 万
MAX_WRITE_OPERATIONS_PER_HOUR
书签写入操作不再受 Chrome 的限制。
值
100 万
方法
create()
chrome.bookmarks.create(
bookmark: CreateDetails,
callback?: function,
)
在指定 parentId 下创建书签或文件夹。如果 url 为 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
string |[字符串, ...字符串 []]
单个字符串值 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
字符串
-
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
字符串
要检索的子树的根的 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
字符串
-
目标账号
对象
-
索引
编号(选填)
-
parentId
字符串(可选)
-
-
callback
函数(可选)
callback
参数如下所示:(result: BookmarkTreeNode) => void
返回
-
Promise<BookmarkTreeNode>
Chrome 90 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
remove()
chrome.bookmarks.remove(
id: string,
callback?: function,
)
移除书签或空的书签文件夹。
参数
-
id
字符串
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
承诺<void>
Chrome 90 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
removeTree()
chrome.bookmarks.removeTree(
id: string,
callback?: function,
)
以递归方式移除书签文件夹。
参数
-
id
字符串
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
承诺<void>
Chrome 90 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
search()
chrome.bookmarks.search(
query: string | object,
callback?: function,
)
搜索与指定查询匹配的 bookmarkTreeNodes。使用对象指定的查询会生成与所有指定属性匹配的 bookmarkTreeNode 。
参数
-
查询
string |对象
可以是与书签网址和标题匹配的字词字符串和带引号的词组,也可以是对象。如果是对象,则可以指定
query
、url
和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' [title]和“url”。
参数
-
id
字符串
-
更改
对象
-
标题
字符串(可选)
-
网址
字符串(可选)
-
-
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
字符串
-
changeInfo
对象
-
标题
字符串
-
网址
字符串(可选)
-
-
onChildrenReordered
chrome.bookmarks.onChildrenReordered.addListener(
callback: function,
)
当文件夹的子级因界面中的排序顺序而更改其顺序时触发。不会因为 move() 而调用此方法。
参数
-
callback
函数
callback
参数如下所示:(id: string, reorderInfo: object) => void
-
id
字符串
-
reorderInfo
对象
-
childIds
字符串[]
-
-
onCreated
chrome.bookmarks.onCreated.addListener(
callback: function,
)
在创建书签或文件夹时触发。
参数
-
callback
函数
callback
参数如下所示:(id: string, bookmark: BookmarkTreeNode) => void
-
id
字符串
-
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
字符串
-
moveInfo
对象
-
索引
number
-
oldIndex
number
-
oldParentId
字符串
-
parentId
字符串
-
-
onRemoved
chrome.bookmarks.onRemoved.addListener(
callback: function,
)
移除书签或文件夹时触发。以递归方式移除某个文件夹时,系统会针对该文件夹仅触发一条通知,而不会对其内容触发任何通知。
参数
-
callback
函数
callback
参数如下所示:(id: string, removeInfo: object) => void
-
id
字符串
-
removeInfo
对象
-
索引
number
-
Chrome 48 及更高版本
-
parentId
字符串
-
-