chrome.bookmarks (original) (raw)

说明

使用 chrome.bookmarks API 可创建、整理和以其他方式操作书签。另请参阅替换网页，您可以使用该功能创建自定义书签管理器页面。

点击星形图标即可添加书签。

权限

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

书签树中的节点（书签或文件夹）。子节点在其父文件夹中按顺序排列。

属性

• 相应节点的子节点的有序列表。
• 相应节点创建的时间，以自纪元 (new Date(dateAdded)) 以来的毫秒数表示。
• dateGroupModified
  number 可选
  相应文件夹的内容上次更改的时间（以自纪元以来经过的毫秒数表示）。
• 相应节点上次打开的时间（以自纪元以来经过的毫秒数表示）。未针对文件夹设置。
• 如果存在，则表示浏览器添加的文件夹，用户或扩展程序无法修改。如果此节点未设置 unmodifiable 属性，则可以修改子节点。如果节点可由用户和扩展程序修改，则省略此属性（默认）。
  每种文件夹类型的节点数量可能为零、一个或多个。浏览器可能会添加或移除文件夹，但无法通过扩展程序 API 执行此操作。
• 节点的唯一标识符。ID 在当前个人资料中是唯一的，即使在浏览器重启后仍保持有效。
• 相应节点在其父文件夹中的从零开始的位置。
• 父文件夹的 id。根节点可省略。
• 相应节点是否已由浏览器与用户的远程账号存储空间同步。这可用于区分同一 FolderType 的账号级版本和仅限本地版本。现有节点上此属性的值可能会发生变化，例如，因用户操作而发生变化。
  注意：此属性反映了节点是否已保存到浏览器的内置账号提供程序。即使此值为 false，节点也可能通过第三方进行同步。
  对于受管节点（unmodifiable 设置为 true 的节点），此属性将始终为 false。
• 为节点显示的文本。
• 指明相应节点不可修改的原因。managed 值表示相应节点是由系统管理员或受监督用户的监护人配置的。如果节点可由用户和扩展程序修改，则省略此属性（默认）。
• 用户点击书签时导航到的网址。对于文件夹，此属性会被省略。

BookmarkTreeNodeUnmodifiable

指明相应节点不可修改的原因。值 managed 表示相应节点由系统管理员配置。如果节点可由用户和扩展程序修改，则省略此属性（默认）。

CreateDetails

传递给 create() 函数的对象。

枚举

“bookmarks-bar”
内容显示在浏览器窗口顶部的文件夹。

“其他”
在所有平台的完整书签列表中显示的书签。

“移动设备”
用户移动设备上通常可用的书签，但可通过扩展程序或在书签管理器中修改。

“受管理”
如果受监督用户的系统管理员或监护人已配置书签，则可能会显示此顶级文件夹。

属性

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

书签写入操作不再受 Chrome 限制。

MAX_WRITE_OPERATIONS_PER_HOUR

书签写入操作不再受 Chrome 限制。

方法

create()

chrome.bookmarks.create(
  bookmark: CreateDetails,
): Promise<BookmarkTreeNode>

在指定的 parentId 下创建书签或文件夹。如果网址为 NULL 或缺失，则为文件夹。

参数

返回

• Promise<BookmarkTreeNode>

get()

chrome.bookmarks.get(
  idOrIdList: string | [string, ...string[]],
): Promise<BookmarkTreeNode[]>

检索指定的 BookmarkTreeNode。

参数

• idOrIdList
  字符串 | [字符串, ...字符串 []]
  单个字符串值 ID 或字符串值 ID 数组

返回

• Promise<BookmarkTreeNode[]>

getChildren()

chrome.bookmarks.getChildren(
  id: string,
): Promise<BookmarkTreeNode[]>

检索指定 BookmarkTreeNode ID 的子级。

参数

返回

• Promise<BookmarkTreeNode[]>

getRecent()

chrome.bookmarks.getRecent(
  numberOfItems: number,
): Promise<BookmarkTreeNode[]>

检索最近添加的书签。

返回

• Promise<BookmarkTreeNode[]>

getSubTree()

chrome.bookmarks.getSubTree(
  id: string,
): Promise<BookmarkTreeNode[]>

检索书签层次结构的一部分，从指定节点开始。

返回

• Promise<BookmarkTreeNode[]>

getTree()

chrome.bookmarks.getTree(): Promise<BookmarkTreeNode[]>

检索整个书签层次结构。

返回

• Promise<BookmarkTreeNode[]>

move()

chrome.bookmarks.move(
  id: string,
  destination: object,
): Promise<BookmarkTreeNode>

将指定的 BookmarkTreeNode 移动到提供的位置。

参数

返回

• Promise<BookmarkTreeNode>

remove()

chrome.bookmarks.remove(
  id: string,
): Promise

移除书签或空书签文件夹。

参数

返回

removeTree()

chrome.bookmarks.removeTree(
  id: string,
): Promise

以递归方式移除书签文件夹。

参数

返回

search()

chrome.bookmarks.search(
  query: string | object,
): Promise<BookmarkTreeNode[]>

搜索与给定查询匹配的 BookmarkTreeNodes。使用对象指定的查询会生成与所有指定属性匹配的 BookmarkTreeNodes。

参数

• 一个字符串（包含与书签网址和标题匹配的字词和带引号的短语）或一个对象。如果为对象，则可以指定属性 query、url 和 title，系统将生成与所有指定属性匹配的书签。
  • 一个字符串，包含要与书签网址和标题进行匹配的字词和带引号的短语。
  • 书签的标题；完全匹配。
  • 书签的网址；完全匹配。请注意，文件夹没有网址。

返回

• Promise<BookmarkTreeNode[]>

update()

chrome.bookmarks.update(
  id: string,
  changes: object,
): Promise<BookmarkTreeNode>

更新书签或文件夹的属性。仅指定要更改的属性；未指定的属性将保持不变。注意：目前仅支持“title”和“url”。

参数

返回

• Promise<BookmarkTreeNode>

事件

onChanged

chrome.bookmarks.onChanged.addListener(
  callback: function,
)

在书签或文件夹发生更改时触发。注意：目前，只有标题和网址更改会触发此操作。

参数

• callback 参数如下所示：
  (id: string, changeInfo: object) => void

onChildrenReordered

chrome.bookmarks.onChildrenReordered.addListener(
  callback: function,
)

当文件夹的子项因在界面中排序而更改顺序时触发。不会因调用 move() 而调用。

参数

• callback 参数如下所示：
  (id: string, reorderInfo: object) => void

onCreated

chrome.bookmarks.onCreated.addListener(
  callback: function,
)

在创建书签或文件夹时触发。

参数

• callback 参数如下所示：
  (id: string, bookmark: BookmarkTreeNode) => void

onImportBegan

chrome.bookmarks.onImportBegan.addListener(
  callback: function,
)

在开始书签导入会话时触发。在 onImportEnded 触发之前，开销大的观测器应忽略 onCreated 更新。观察者仍应立即处理其他通知。

参数

• callback 参数如下所示：
  () => void

onImportEnded

chrome.bookmarks.onImportEnded.addListener(
  callback: function,
)

在书签导入会话结束时触发。

参数

• callback 参数如下所示：
  () => void

onMoved

chrome.bookmarks.onMoved.addListener(
  callback: function,
)

当书签或文件夹被移至其他父级文件夹时触发。

参数

• callback 参数如下所示：
  (id: string, moveInfo: object) => void

onRemoved

chrome.bookmarks.onRemoved.addListener(
  callback: function,
)

在移除书签或文件夹时触发。以递归方式移除文件夹时，系统会针对该文件夹触发一次通知，而不会针对其内容触发通知。

参数

• callback 参数如下所示：
  (id: string, removeInfo: object) => void