chrome.bookmarks

说明

使用 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

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

属性

  • 孩子

    BookmarkTreeNode[] 可选

    相应节点的子节点的有序列表。

  • dateAdded

    number 可选

    相应节点创建的时间，以自纪元 (new Date(dateAdded)) 以来的毫秒数表示。

  • dateGroupModified

    number 可选

    相应文件夹的内容上次更改的时间（以自纪元以来经过的毫秒数表示）。

  • dateLastUsed

    number 可选

    Chrome 114 及更高版本

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

  • folderType

    FolderType 可选

    Chrome 134 及更高版本

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

    每种文件夹类型的节点数量可能为零、一个或多个。浏览器可能会添加或移除文件夹，但无法通过扩展程序 API 执行此操作。

  • id

    字符串

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

  • 索引

    number 可选

    相应节点在其父文件夹中的从零开始的位置。

  • parentId

    字符串（选填）

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

  • 正在同步

    布尔值

    Chrome 134 及更高版本

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

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

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

  • title

    字符串

    为节点显示的文本。

  • 不可修改

    “受管理”
     可选

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

  • 网址

    字符串（选填）

    用户点击书签时导航到的网址。对于文件夹，此属性会被省略。

BookmarkTreeNodeUnmodifiable

Chrome 44 及更高版本

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

值

“受管”

CreateDetails

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

属性

  • 索引

    number 可选

  • parentId

    字符串（选填）

    默认为“其他书签”文件夹。

  • title

    字符串（选填）

  • 网址

    字符串（选填）

FolderType

Chrome 134 及更高版本

指示文件夹的类型。

枚举

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

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

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

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

属性

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

已弃用

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

值

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

已弃用

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

值

1000000

方法

create()

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

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

参数

返回

get()

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

检索指定的 BookmarkTreeNode。

参数

  • idOrIdList

    字符串 | [字符串, ...字符串 []]

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

返回

getChildren()

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

检索指定 BookmarkTreeNode ID 的子级。

参数

  • id

    字符串

返回

getRecent()

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

检索最近添加的书签。

参数

  • numberOfItems

    数值

    需要返回的最大项数。

返回

getSubTree()

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

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

参数

  • id

    字符串

    要检索的子树的根的 ID。

返回

getTree()

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

检索整个书签层次结构。

返回

move()

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

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

参数

  • id

    字符串

  • 目标账号

    对象

    • 索引

      number 可选

    • parentId

      字符串（选填）

返回

remove()

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

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

参数

  • id

    字符串

返回

  • Promise<void>

    Chrome 90 及更高版本

removeTree()

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

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

参数

  • id

    字符串

返回

  • Promise<void>

    Chrome 90 及更高版本 
chrome.bookmarks.search(
  query: string | object,
): Promise<BookmarkTreeNode[]>

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

参数

  • 查询

    字符串 | 对象

    一个字符串（包含与书签网址和标题匹配的字词和带引号的短语）或一个对象。如果为对象，则可以指定属性 query、url 和 title，系统将生成与所有指定属性匹配的书签。

    • 查询

      字符串（选填）

      一个字符串，包含要与书签网址和标题进行匹配的字词和带引号的短语。

    • title

      字符串（选填）

      书签的标题；完全匹配。

    • 网址

      字符串（选填）

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

返回

update()

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

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

参数

  • id

    字符串

  • 更改

    对象

    • title

      字符串（选填）

    • 网址

      字符串（选填）

返回

事件

onChanged

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

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

    • id

      字符串

    • changeInfo

      对象

      • title

        字符串

      • 网址

        字符串（选填）

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,
)

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

参数

onImportBegan

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

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

参数

  • 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

      对象

      • 索引

        数值

      • oldIndex

        数值

      • oldParentId

        字符串

      • parentId

        字符串

onRemoved

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

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

    • id

      字符串

    • removeInfo

      对象

      • 索引

        数值

      • Chrome 48 及更高版本
      • parentId

        字符串