chrome.bookmarks

描述：	使用 `chrome.bookmarks` API 创建、组织或通过其他方式操纵书签，另外请参见替代页面，通过它您可以创建一个自定义的书签管理器页面。
可用版本：	从 Chrome 5 开始支持。
权限：	"bookmarks"

清单文件

您必须在扩展程序的清单文件中声明 "bookmarks" 权限才能使用书签 API。例如：

      {
        "name": "我的扩展程序",
        ...
        "permissions": [
          "bookmarks"
        ],
        ...
      }

对象和属性

书签以树的形式组织，树中每一个节点为一个书签或者文件夹（有时称为组），每一个节点使用 bookmarks.BookmarkTreeNode 对象来表示。

BookmarkTreeNode 的各种属性在 chrome.bookmarks API 中经常使用。例如，当您调用 bookmarks.create 时，您传递新节点所属的父节点（parentId），并且可选地传递节点的索引号（index）、标题（title）和 url 属性。有关一个节点可以包含的属性，请参见 bookmarks.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
属性
MAX_WRITE_OPERATIONS_PER_HOUR
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
方法
get − `chrome.bookmarks.get(string or array of string idOrIdList, function callback)`
getChildren − `chrome.bookmarks.getChildren(string id, function callback)`
getRecent − `chrome.bookmarks.getRecent(integer numberOfItems, function callback)`
getTree − `chrome.bookmarks.getTree(function callback)`
getSubTree − `chrome.bookmarks.getSubTree(string id, function callback)`
search − `chrome.bookmarks.search(string or object query, function callback)`
create − `chrome.bookmarks.create(object bookmark, function callback)`
move − `chrome.bookmarks.move(string id, object destination, function callback)`
update − `chrome.bookmarks.update(string id, object changes, function callback)`
remove − `chrome.bookmarks.remove(string id, function callback)`
removeTree − `chrome.bookmarks.removeTree(string id, function callback)`
事件
onCreated
onRemoved
onChanged
onMoved
onChildrenReordered
onImportBegan
onImportEnded

类型

BookmarkTreeNode

代表书签树中的一个节点（书签或文件夹），子节点在它们的父文件夹中按顺序排列。

属性
string	id	节点的唯一标识符。唯一标识符在当前用户配置文件中保证唯一，并且在浏览器重新启动后仍然有效。
string	（可选） parentId	父节点的标识符（`id`）。根节点没有此属性。
integer	（可选） index	该节点在父文件夹中的位置（从 0 开始）。
string	（可选） url	当用户单击书签时打开的URL。文件夹没有此属性。
string	title	该节点显示的文字。
double	（可选） dateAdded	该节点创建的时间，表示为自 1970 年 1 月 1 日午夜至今所经过的毫秒数（`new Date(dateAdded)`）。
double	（可选） dateGroupModified	该文件夹内容的上一次修改时间，表示为自 1970 年 1 月 1 日午夜至今所经过的毫秒数。
enum of `"managed"`	（可选） unmodifiable	从 Chrome 37 开始支持。警告：目前为 Beta 分支。了解更多内容表示该节点不可修改的原因，"`managed`" 表示该节点由系统管理员配置。如果该节点可以由用户和扩展程序修改（默认）则省略。
array of BookmarkTreeNode	（可选） children	该节点的所有子节点（已排序）。

属性

`1,000,000`	`chrome.bookmarks.MAX_WRITE_OPERATIONS_PER_HOUR`	从 Chrome 38 开始弃用。Chrome 浏览器不再限制书签写入操作。
`1,000,000`	`chrome.bookmarks.MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE`	从 Chrome 38 开始弃用。Chrome 浏览器不再限制书签写入操作。

方法

get


              chrome.bookmarks.get(string or array of string idOrIdList, function callback)

获得指定的书签树节点。

参数

string or array of string

idOrIdList

一个字符串或多个字符串组成的数组，指定节点的标识符。

function

callback

callback 参数应该是一个如下形式的函数：

function(array of BookmarkTreeNode results) {...};

array of BookmarkTreeNode

results

getChildren


              chrome.bookmarks.getChildren(string id, function callback)

获取指定书签树节点的所有子节点。

参数

string id

function

callback

callback 参数应该是一个如下形式的函数：

function(array of BookmarkTreeNode results) {...};

array of BookmarkTreeNode

results

getRecent


              chrome.bookmarks.getRecent(integer numberOfItems, function callback)

获取最近添加的几个书签。

参数

integer

numberOfItems

期望返回的最大书签数目。

function

callback

callback 参数应该是一个如下形式的函数：

function(array of BookmarkTreeNode results) {...};

array of BookmarkTreeNode

results

getTree


              chrome.bookmarks.getTree(function callback)

获取整个书签树。

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(array of BookmarkTreeNode results) {...};

array of BookmarkTreeNode

results

getSubTree


              chrome.bookmarks.getSubTree(string id, function callback)

从 Chrome 14 开始支持。

获取从指定节点开始的部分书签树。

参数

string

要获得的子树的根节点唯一标识符。

function

callback

callback 参数应该是一个如下形式的函数：

function(array of BookmarkTreeNode results) {...};

array of BookmarkTreeNode

results

search


              chrome.bookmarks.search(string or object query, function callback)

搜索书签树节点，找出匹配的结果。如果以对象方式指定查询，得到的 BookmarkTreeNodes 匹配所有指定的属性。

参数

string or object

query

可以指定字符串，包含单词和加上引号的短语，用于匹配书签 URL 和标题。也可以指定对象，其中可以指定 query、url 和 title 属性，返回匹配所有指定属性的书签。

function

callback

callback 参数应该是一个如下形式的函数：

function(array of BookmarkTreeNode results) {...};

array of BookmarkTreeNode

results

create


              chrome.bookmarks.create(object bookmark, function callback)

在指定的上一级文件夹下创建新的书签或文件夹。如果 url 为 null 或者省略，则创建文件夹。

参数

object

bookmark

string	（可选） parentId	默认为“其他书签”文件夹。
integer	（可选） index
string	（可选） title
string	（可选） url

function

（可选）
callback

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function( BookmarkTreeNode result) {...};

BookmarkTreeNode

result

move


              chrome.bookmarks.move(string id, object destination, function callback)

将指定的书签树节点移到指定位置。

参数

string id

object

destination

string	（可选） parentId
integer	（可选） index

function

（可选）
callback

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function( BookmarkTreeNode result) {...};

BookmarkTreeNode

result

update


              chrome.bookmarks.update(string id, object changes, function callback)

更新书签或文件夹的属性。只需要指定您需要更改的属性，未指定的属性不会更改。注意：目前只支持“title”和“url”属性。

参数

string id

object

changes

string	（可选） title
string	（可选） url

function

（可选）
callback

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function( BookmarkTreeNode result) {...};

BookmarkTreeNode

result

remove


              chrome.bookmarks.remove(string id, function callback)

删除书签或者空文件夹。

参数
string	id
function	（可选） callback	如果您指定了 callback 参数，它应该是一个如下形式的函数： `function() {...};`

removeTree


              chrome.bookmarks.removeTree(string id, function callback)

删除整个书签文件夹。

参数
string	id
function	（可选） callback	如果您指定了 callback 参数，它应该是一个如下形式的函数： `function() {...};`

事件

onCreated

当书签或文件夹创建时产生。

addListener


                    chrome.bookmarks.onCreated.addListener(function callback)

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(string id, BookmarkTreeNode bookmark) {...};

string	id
BookmarkTreeNode	bookmark

onRemoved

当删除书签或文件夹时产生。当删除整个文件夹（包括其中所有内容）时，仅为该文件夹发送通知，不为其中任何内容发送通知。

addListener


                    chrome.bookmarks.onRemoved.addListener(function callback)

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(string id, object removeInfo) {...};

string

object

removeInfo

string	parentId
integer	index

onChanged

一个书签或文件夹更改时发生。注意：目前只有标题和URL更改时会触发这一事件。

addListener


                    chrome.bookmarks.onChanged.addListener(function callback)

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(string id, object changeInfo) {...};

string

object

changeInfo

string	title
string	（可选） url

onMoved

当书签或文件夹移动到另一个父文件夹中时产生。

addListener


                    chrome.bookmarks.onMoved.addListener(function callback)

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(string id, object moveInfo) {...};

string

object

moveInfo

string	parentId
integer	index
string	oldParentId
integer	oldIndex

onChildrenReordered

文件夹中的子节点在用户界面中调整顺序时产生。调用 move() 不会触发该事件。

addListener


                    chrome.bookmarks.onChildrenReordered.addListener(function callback)

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(string id, object reorderInfo) {...};

string

object

reorderInfo

array of string

childIds

onImportBegan

开始导入书签时产生。复杂的事件处理函数在这一事件产生后不应该再处理 onCreated 事件，直到 onImportEnded 事件产生，在此过程中其他事件仍然应该立即处理。

addListener


                    chrome.bookmarks.onImportBegan.addListener(function callback)

参数
function	callback	callback 参数应该是一个如下形式的函数： `function() {...};`

onImportEnded

书签导入结束时产生。

addListener


                    chrome.bookmarks.onImportEnded.addListener(function callback)

参数
function	callback	callback 参数应该是一个如下形式的函数： `function() {...};`

示例扩展程序

My Bookmarks – A browser action with a popup dump of all bookmarks, including search, add, edit and delete.
Event Page Example – Demonstrates usage and features of the event page
Chrome Sounds – Enjoy a more magical and immersive experience when browsing the web using the power of sound.
Managed Bookmarks – Adds bookmarks configured by your system administrator to Chrome.