browser.bookmarks

说明

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

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

权限

bookmarks

必须在扩展程序清单中声明“bookmarks”权限，才能使用 Bookmarks API。例如：

{
  "name": "My extension",
  ...
  "permissions": [
    "bookmarks"
  ],
  ...
}

概念和用法

对象和属性

书签以树状结构进行整理，树中的每个节点都是书签或文件夹（有时称为“组”）。树中的每个节点都由一个 bookmarks.BookmarkTreeNode 对象表示。

BookmarkTreeNode 属性在整个 browser.bookmarks API 中使用。例如，当您调用 bookmarks.create 时，您需要传入新节点的父级 (parentId)，并可选择传入节点的 index、title 和 url 属性。如需了解节点可以具有的属性，请参阅 bookmarks.BookmarkTreeNode。

注意：您无法使用此 API 在根文件夹中添加或移除条目。您也无法重命名、移动或移除特殊的“书签栏”和“其他书签”文件夹。

示例

以下代码会创建一个标题为“Extension bookmarks”的文件夹。create() 的第一个参数指定新文件夹的属性。第二个参数定义了在创建文件夹后要执行的函数。

browser.bookmarks.create(
  {'parentId': bookmarkBar.id, 'title': 'Extension bookmarks'},
  function(newFolder) {
    console.log("added folder: " + newFolder.title);
  },
);

下一个代码段会创建一个指向扩展程序开发者文档的书签。由于创建书签失败不会造成任何不良后果，因此这段代码无需定义回调函数。

browser.bookmarks.create({
  'parentId': extensionsFolderId,
  'title': 'Extensions doc',
  'url': 'https://developer.chrome.com/docs/extensions',
});

如需试用此 API，请从 chrome-extension-samples 代码库中安装 Bookmarks API 示例。

类型

BookmarkTreeNode

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

属性

• 孩子

  BookmarkTreeNode[] 可选

  此节点的子节点的有序列表。

• dateAdded

  number 可选

  此节点的创建时间（以毫秒为单位，从纪元 new Date(dateAdded) 算起）。

• dateGroupModified

  number 可选

  此文件夹的内容上次更改的时间（从纪元开始计算，以毫秒为单位）。

• dateLastUsed

  number 可选

  Chrome 114 及更高版本 browser.*（自 Chrome 148 起）

  此节点上次打开的时间（以自纪元以来的毫秒数表示）。未针对文件夹进行设置。

• folderType

  FolderType 可选

  Chrome 134 及更高版本 browser.*（自 Chrome 148 起）

  如果存在，则表示这是由浏览器添加的文件夹，用户或扩展程序无法修改。如果此节点未设置 unmodifiable 属性，则可以修改子节点。如果节点可由用户和扩展程序修改（默认），则省略。

  每种文件夹类型可能有零个、一个或多个节点。文件夹可以由浏览器添加或移除，但不能通过扩展程序 API 添加或移除。

• id

  字符串

  节点的唯一标识符。这些 ID 在当前个人资料中是唯一的，即使在浏览器重启后也仍然有效。

• 索引

  number 可选

  此节点在其父文件夹中的位置（从 0 开始）。

• parentId

  字符串 可选

  父级文件夹的 id。根节点省略。

• 正在同步

  布尔值

  Chrome 134 及更高版本 browser.*（自 Chrome 148 起）

  此节点是否由浏览器与用户的远程账号存储空间同步。这可用于区分同一 FolderType 的账号版本和仅限本地版本。此属性的值可能会因现有节点而发生变化，例如因用户操作而发生变化。

  注意：这反映了节点是否已保存到浏览器的内置账号提供方。即使此值为 false，节点也可能通过第三方进行同步。

  对于代管式节点（unmodifiable 设置为 true 的节点），此属性始终为 false。

• title

  字符串

  为节点显示的文本。

• 不可修改

  "managed"
   可选

  指明此节点不可修改的原因。managed 值表示此节点是由系统管理员或受监督用户的监护人配置的。如果节点可由用户和扩展程序修改（默认），则省略。

• 网址

  字符串 可选

  用户点击书签后会转到的网址。文件夹省略。

BookmarkTreeNodeUnmodifiable

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

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

值

"managed"

CreateDetails

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

属性

• 索引

  number 可选

• parentId

  字符串 可选

  默认保存到“其他书签”文件夹。

• title

  字符串 可选

• 网址

  字符串 可选

FolderType

Chrome 134 及更高版本 browser.*（自 Chrome 148 起）

指明文件夹的类型。

枚举

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

“其他”
在所有平台上，这些书签都会显示在完整书签列表中。

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

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

属性

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

已弃用

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

值

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

已弃用

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

值

1000000

ROOT_NODE_ID

Chrome 145 及更高版本 browser.*（自 Chrome 148 起）

与根级节点关联的 id。

值

"0"

方法

create()

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

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

参数

• 书签

  CreateDetails

返回

• Promise<BookmarkTreeNode>

  Chrome 90 及更高版本 browser.*（自 Chrome 148 起）

get()

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

检索指定的 BookmarkTreeNode。

参数

• idOrIdList

  string | [string, …string[]]

  单个字符串值 ID 或字符串值 ID 数组

返回

• <Promise<BookmarkTreeNode[]>

  Chrome 90 及更高版本 browser.*（自 Chrome 148 起）

getChildren()

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

检索指定 BookmarkTreeNode ID 的子节点。

参数

• id

  字符串

返回

• <Promise<BookmarkTreeNode[]>

  Chrome 90 及更高版本 browser.*（自 Chrome 148 起）

getRecent()

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

检索最近添加的书签。

参数

• numberOfItems

  数值

  需要返回的最大项数。

返回

• <Promise<BookmarkTreeNode[]>

  Chrome 90 及更高版本 browser.*（自 Chrome 148 起）

getSubTree()

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

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

参数

• id

  字符串

  要检索的子树的根 ID。

返回

• <Promise<BookmarkTreeNode[]>

  Chrome 90 及更高版本 browser.*（自 Chrome 148 起）

getTree()

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

检索整个书签层次结构。

返回

• <Promise<BookmarkTreeNode[]>

  Chrome 90 及更高版本 browser.*（自 Chrome 148 起）

move()

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

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

参数

• id

  字符串

• 目标账号

  对象

  • 索引

    number 可选

  • parentId

    字符串 可选

返回

• Promise<BookmarkTreeNode>

  Chrome 90 及更高版本 browser.*（自 Chrome 148 起）

remove()

browser.bookmarks.remove(
  id: string,
): Promise<void>

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

参数

• id

  字符串

返回

• 承诺<void>

  Chrome 90 及更高版本 browser.*（自 Chrome 148 起）

removeTree()

browser.bookmarks.removeTree(
  id: string,
): Promise<void>

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

参数

• id

  字符串

返回

• 承诺<void>

  Chrome 90 及更高版本 browser.*（自 Chrome 148 起）

search()

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

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

参数

• 查询

  字符串 | 对象

  一个由字词和带引号的词组组成的字符串（用于与书签网址和标题进行匹配），或一个对象。如果是一个对象，则可以指定 query、url 和 title 属性，系统会生成与所有指定属性匹配的书签。

  • 查询

    字符串 可选

    与书签网址和标题匹配的一串字词和带引号的短语。

  • title

    字符串 可选

    书签的标题；逐字匹配。

  • 网址

    字符串 可选

    书签的网址；逐字匹配。请注意，文件夹没有网址。

返回

• <Promise<BookmarkTreeNode[]>

  Chrome 90 及更高版本 browser.*（自 Chrome 148 起）

update()

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

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

参数

• id

  字符串

• 更改

  对象

  • title

    字符串 可选

  • 网址

    字符串 可选

返回

• Promise<BookmarkTreeNode>

  Chrome 90 及更高版本 browser.*（自 Chrome 148 起）

事件

onChanged

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

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

参数

• callback

  函数

  callback 参数如下所示：

  (id: string, changeInfo: object) => void

  • id

    字符串

  • changeInfo

    对象

    • title

      字符串

    • 网址

      字符串 可选

onChildrenReordered

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

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

参数

• callback

  函数

  callback 参数如下所示：

  (id: string, reorderInfo: object) => void

  • id

    字符串

  • reorderInfo

    对象

    • childIds

      字符串[]

onCreated

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

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

参数

• callback

  函数

  callback 参数如下所示：

  (id: string, bookmark: BookmarkTreeNode) => void

  • id

    字符串

  • 书签

    BookmarkTreeNode

onImportBegan

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

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

参数

• callback

  函数

  callback 参数如下所示：

  () => void

onImportEnded

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

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

参数

• callback

  函数

  callback 参数如下所示：

  () => void

onMoved

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

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

参数

• callback

  函数

  callback 参数如下所示：

  (id: string, moveInfo: object) => void

  • id

    字符串

  • moveInfo

    对象

    • 索引

      数值

    • oldIndex

      数值

    • oldParentId

      字符串

    • parentId

      字符串

onRemoved

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

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

参数

• callback

  函数

  callback 参数如下所示：

  (id: string, removeInfo: object) => void

  • id

    字符串

  • removeInfo

    对象

    • 索引

      数值

    • 节点

      BookmarkTreeNode

      Chrome 48+ browser.*（自 Chrome 148 起）
    • parentId

      字符串