chrome.bookmarks
| 描述： |
使用 chrome.bookmarks API 创建、组织以及通过其他方式操纵书签。您也可以参见替代页面，通过它您可以创建一个自定义的书签管理器页面。
|
| 可用版本： |
从 Chrome 5 开始稳定支持。
|
| 权限： |
"bookmarks"
|
清单文件
您必须在扩展程序的清单文件中声明
"bookmarks" 权限才能使用书签 API。例如：
{
"name": "我的扩展程序",
...
"permissions": [
"bookmarks"
],
...
}
对象和属性
书签以树的形式组织，树中每一个节点为一个书签或者文件夹（有时称为组），每一个节点使用 BookmarkTreeNode 对象来表示。
BookmarkTreeNode 的各种属性在 chrome.bookmarks
API 中经常使用。例如，当您调用 create
时，您传递新节点所属的父节点（parentId），并且可选地传递节点的
索引号（index）、标题（title）和
url 属性。有关一个节点可以包含的属性，请参见
BookmarkTreeNode。
注意：您不可以使用这一 API 在根文件夹中添加或删除项目，您也不能重命名、移动或删除特殊的“书签栏”和“其他书签”文件夹。
例子
以下代码创建一个标题为“扩展程序书签”的文件夹，create()
的第一个参数指定新文件夹的属性，第二个参数定义文件夹创建后执行的函数。
chrome.bookmarks.create({'parentId': bookmarkBar.id,
'title': '扩展程序书签'},
function(newFolder) {
console.log("已添加文件夹：" + newFolder.title);
});
下一个片段创建一个指向扩展程序开发者文档的书签。既然创建书签失败不会造成什么问题，下列代码省去了定义回调函数的麻烦。
chrome.bookmarks.create({'parentId': extensionsFolderId,
'title': '扩展程序文档',
'url': 'https://developer.chrome.com/extensions'});
有关使用这一 API 的一个例子，请参见基本的书签示例。有关其他例子以及查看源代码的帮助，请参见示例。
类型
BookmarkTreeNode
代表书签树中的一个节点（书签或文件夹），子节点在它们的父文件夹中按顺序排列。
-
id
(
string
)
-
节点的唯一标识符。唯一标识符在当前用户配置文件中保证唯一，并且在浏览器重新启动后仍然有效。
-
parentId
(
optional
string
)
-
父节点的标识符（
id）。根节点没有此属性。
-
index
(
optional
integer
)
-
该节点在父文件夹中的位置（从 0 开始）。
-
url
(
optional
string
)
-
当用户单击书签时打开的URL。文件夹没有此属性。
-
title
(
string
)
-
该节点显示的文字。
-
dateAdded
(
optional
double
)
-
该节点创建的时间，表示为自 1970 年 1 月 1 日午夜至今所经过的毫秒数（
new Date(dateAdded)）。
-
dateGroupModified
(
optional
double
)
-
该文件夹内容的上一次修改时间，表示为自 1970 年 1 月 1 日午夜至今所经过的毫秒数。
属性
MAX_WRITE_OPERATIONS_PER_HOUR
chrome.bookmarks.MAX_WRITE_OPERATIONS_PER_HOUR
MAX_WRITE_OPERATIONS_PER_HOUR ( 100 )
每小时可以执行的移动（move）、更新（update）、创建（create）或删除（remove）操作的最大数目，超过这一限制的更新将会失败。
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
chrome.bookmarks.MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE ( 2 )
在连续的 10 分钟内每分钟可以执行的移动（move）、更新（update）、创建（create）或删除（remove）操作的最大数目，超过这一限制的更新将会失败。
方法
get
chrome.bookmarks.get(string or array of string idOrIdList, function callback)
获得指定的书签树节点。
参数
-
idOrIdList
(
string or
array of string
)
-
一个字符串或多个字符串组成的数组，指定节点的标识符。
callback 参数应该指定一个如下形式的函数：
function(array of BookmarkTreeNode results) {...};
getChildren
chrome.bookmarks.getChildren(string id, function callback)
获取指定书签树节点的所有子节点。
参数
callback 参数应该指定一个如下形式的函数：
function(array of BookmarkTreeNode results) {...};
getRecent
chrome.bookmarks.getRecent(integer numberOfItems, function callback)
获取最近添加的几个书签。
参数
-
numberOfItems
(
integer
)
-
期望返回的最大书签数目。
callback 参数应该指定一个如下形式的函数：
function(array of BookmarkTreeNode results) {...};
getTree
chrome.bookmarks.getTree(function callback)
获取整个书签树。
参数
callback 参数应该指定一个如下形式的函数：
function(array of BookmarkTreeNode results) {...};
getSubTree
chrome.bookmarks.getSubTree(string id, function callback)
获取从指定节点开始的部分书签树。
参数
-
id
(
string
)
-
要获得的子树的根节点唯一标识符。
callback 参数应该指定一个如下形式的函数：
function(array of BookmarkTreeNode results) {...};
search
chrome.bookmarks.search(string or object query, function callback)
搜索书签树节点，找出匹配的结果。如果以对象方式指定查询，得到的 BookmarkTreeNodes 匹配所有指定的属性。
参数
-
query
(
string or
object
)
-
callback 参数应该指定一个如下形式的函数：
function(array of BookmarkTreeNode results) {...};
create
chrome.bookmarks.create(object bookmark, function callback)
在指定的上一级文件夹下创建新的书签或文件夹。如果 url 为 null 或者省略，则创建文件夹。
参数
-
bookmark
(
object
)
-
-
属性
-
parentId
(
optional
string
)
-
默认为“其他书签”文件夹。
-
index
(
optional
integer
)
-
-
title
(
optional
string
)
-
-
callback
(
optional
function
)
-
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function(BookmarkTreeNode result) {...};
move
chrome.bookmarks.move(string id, object destination, function callback)
将指定的书签树节点移到指定位置。
参数
-
destination
(
object
)
-
-
属性
-
parentId
(
optional
string
)
-
-
index
(
optional
integer
)
-
-
callback
(
optional
function
)
-
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function(BookmarkTreeNode result) {...};
update
chrome.bookmarks.update(string id, object changes, function callback)
更新书签或文件夹的属性。只需要指定您需要更改的属性，未指定的属性不会更改。注意：目前只支持“title”和“url”属性。
参数
-
changes
(
object
)
-
-
属性
-
title
(
optional
string
)
-
-
callback
(
optional
function
)
-
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function(BookmarkTreeNode result) {...};
remove
chrome.bookmarks.remove(string id, function callback)
删除书签或者空文件夹。
参数
-
callback
(
optional
function
)
-
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function() {...};
removeTree
chrome.bookmarks.removeTree(string id, function callback)
删除整个书签文件夹。
参数
-
callback
(
optional
function
)
-
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function() {...};
事件
onCreated
当书签或文件夹创建时产生。
addListener
chrome.bookmarks.onCreated.addListener(function callback)
参数
callback 参数应该指定一个如下形式的函数：
function(string id, BookmarkTreeNode bookmark) {...};
onRemoved
当删除书签或文件夹时产生。当删除整个文件夹（包括其中所有内容）时，仅为该文件夹发送通知，不为其中任何内容发送通知。
addListener
chrome.bookmarks.onRemoved.addListener(function callback)
参数
callback 参数应该指定一个如下形式的函数：
function(string id, object removeInfo) {...};
onChanged
一个书签或文件夹更改时发生。注意：目前只有标题和URL更改时会触发这一事件。
addListener
chrome.bookmarks.onChanged.addListener(function callback)
参数
callback 参数应该指定一个如下形式的函数：
function(string id, object changeInfo) {...};
onMoved
当书签或文件夹移动到另一个父文件夹中时产生。
addListener
chrome.bookmarks.onMoved.addListener(function callback)
参数
callback 参数应该指定一个如下形式的函数：
function(string id, object moveInfo) {...};
onChildrenReordered
文件夹中的子节点在用户界面中调整顺序时产生。调用 move() 不会触发该事件。
addListener
chrome.bookmarks.onChildrenReordered.addListener(function callback)
参数
callback 参数应该指定一个如下形式的函数：
function(string id, object reorderInfo) {...};
-
reorderInfo
(
object
)
-
-
属性
-
childIds
(
array of string
)
-
onImportBegan
开始导入书签时产生。复杂的事件处理函数在这一事件产生后不应该再处理 onCreate 事件，直到 onImportEnded 事件产生，在此过程中其他事件仍然应该立即处理。
addListener
chrome.bookmarks.onImportBegan.addListener(function callback)
参数
callback 参数应该指定一个如下形式的函数：
function() {...};
onImportEnded
书签导入结束时产生。
addListener
chrome.bookmarks.onImportEnded.addListener(function callback)
参数
callback 参数应该指定一个如下形式的函数：
function() {...};
chrome