chrome.bookmarks

说明

使用 chrome.bookmarks API 创建、整理以及以其他方式操纵书签。另请参阅覆盖网页（可用于创建自定义“书签管理器”页面）。

<ph type="x-smartling-placeholder">
</ph> 点击星形图标可添加书签
点击星标即可添加书签。

权限

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

    编号（选填）

    此节点的创建时间，以从公元纪年 (new Date(dateAdded)) 开始计算的毫秒数表示。

  • dateGroupModified

    编号（选填）

    此文件夹的内容上次更改的时间（以毫秒为单位，从 Epoch 起算）。

  • dateLastUsed

    编号（选填）

    Chrome 114 及更高版本

    此节点的上次打开时间，以从公元纪年开始计算的毫秒数表示。未设置文件夹。

  • id

    字符串

    节点的唯一标识符。ID 在当前配置文件中是唯一的，即使在浏览器重新启动后也仍然有效。

  • 索引

    编号（选填）

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

  • parentId

    字符串（可选）

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

  • 标题

    字符串

    为节点显示的文本。

  • 不可修改

    "managed"
     可选

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

  • 网址

    字符串（可选）

    当用户点击书签时导航到的网址。对于文件夹，可以省略。

BookmarkTreeNodeUnmodifiable

Chrome 44 及更高版本

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

值

"managed"

CreateDetails

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

属性

  • 索引

    编号（选填）

  • parentId

    字符串（可选）

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

  • 标题

    字符串（可选）

  • 网址

    字符串（可选）

属性

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

<ph type="x-smartling-placeholder"></ph> 已弃用

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

值

100 万

MAX_WRITE_OPERATIONS_PER_HOUR

<ph type="x-smartling-placeholder"></ph> 已弃用

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

值

100 万

方法

create()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bookmarks.create(
  bookmark: CreateDetails,
  callback?: function,
)

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

参数

返回

  • Promise&lt;BookmarkTreeNode&gt;

    Chrome 90 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

get()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bookmarks.get(
  idOrIdList: string | [string, ...string[]],
  callback?: function,
)

检索指定的 bookmarkTreeNode。

参数

  • idOrIdList

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

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (results: BookmarkTreeNode[]) => void

返回

  • Promise&lt;BookmarkTreeNode[]&gt;

    Chrome 90 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getChildren()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bookmarks.getChildren(
  id: string,
  callback?: function,
)

检索指定 bookmarkTreeNode ID 的子级。

参数

返回

  • Promise&lt;BookmarkTreeNode[]&gt;

    Chrome 90 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getRecent()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bookmarks.getRecent(
  numberOfItems: number,
  callback?: function,
)

检索最近添加的书签。

参数

  • numberOfItems

    number

    需要返回的最大项数。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (results: BookmarkTreeNode[]) => void

返回

  • Promise&lt;BookmarkTreeNode[]&gt;

    Chrome 90 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getSubTree()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bookmarks.getSubTree(
  id: string,
  callback?: function,
)

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

参数

  • id

    字符串

    要检索的子树的根的 ID。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (results: BookmarkTreeNode[]) => void

返回

  • Promise&lt;BookmarkTreeNode[]&gt;

    Chrome 90 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getTree()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bookmarks.getTree(
  callback?: function,
)

检索整个书签层次结构。

参数

返回

  • Promise&lt;BookmarkTreeNode[]&gt;

    Chrome 90 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

move()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bookmarks.move(
  id: string,
  destination: object,
  callback?: function,
)

将指定的 bookmarkTreeNode 移至提供的位置。

参数

  • id

    字符串

  • 目标账号

    对象

    • 索引

      编号（选填）

    • parentId

      字符串（可选）

  • callback

    函数（可选）

    callback 参数如下所示： 

    (result: BookmarkTreeNode) => void

返回

  • Promise&lt;BookmarkTreeNode&gt;

    Chrome 90 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

remove()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bookmarks.remove(
  id: string,
  callback?: function,
)

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

参数

  • id

    字符串

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 90 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

removeTree()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bookmarks.removeTree(
  id: string,
  callback?: function,
)

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

参数

  • id

    字符串

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 90 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bookmarks.search(
  query: string | object,
  callback?: function,
)

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

参数

  • 查询

    string |对象

    可以是与书签网址和标题匹配的字词字符串和带引号的词组，也可以是对象。如果是对象，则可以指定 query、url 和 title 属性，这样会生成与所有指定属性匹配的书签。

    • 查询

      字符串（可选）

      与书签网址和标题匹配的字词字符串和带引号的词组。

    • 标题

      字符串（可选）

      书签的标题；匹配逐字匹配。

    • 网址

      字符串（可选）

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (results: BookmarkTreeNode[]) => void

返回

  • Promise&lt;BookmarkTreeNode[]&gt;

    Chrome 90 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

update()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bookmarks.update(
  id: string,
  changes: object,
  callback?: function,
)

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

参数

  • id

    字符串

  • 更改

    对象

    • 标题

      字符串（可选）

    • 网址

      字符串（可选）

  • callback

    函数（可选）

    callback 参数如下所示： 

    (result: BookmarkTreeNode) => void

返回

  • Promise&lt;BookmarkTreeNode&gt;

    Chrome 90 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

事件

onChanged

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

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

    • id

      字符串

    • changeInfo

      对象

      • 标题

        字符串

      • 网址

        字符串（可选）

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

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

参数

  • 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

      对象

      • 索引

        number

      • oldIndex

        number

      • oldParentId

        字符串

      • parentId

        字符串

onRemoved

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

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

    • id

      字符串

    • removeInfo

      对象

      • 索引

        number

      • Chrome 48 及更高版本
      • parentId

        字符串