# 书签 API 升级指南
本文档旨在帮助开发者更新旧版本书签 API 到最新版本。从 10.0.0 版本开始，我们重构了书签 API，重构后的 API 提供了更强的功能和性能提升。接下来，我们将介绍哪些旧的书签 API 将被废弃，以及如何将其替换为新的API。
# 确认当前使用的 API 版本
如果您的应用是基于 10.0.0 之前的版本开发，在升级到 10.0.0 之后的版本时，请注意在您的代码中查找相关的 API 调用，或者查看组件模板中是否使用了旧的书签组件。旧的API名称以及组件将在后面列出。
# 被废弃的API
下表列出了被删除的书签 API 以及替代方案：
下面是被废弃的书签 UIExtension 组件以及替代方案：
| 旧版组件 | 描述 | 替代组件 |
|---|---|---|
<bookmark-sidebar-panel> | 侧边栏书签面板组件 | <bookmark-v2:sidebar-panel> |
<bookmark-contextmenu> | 书签右键菜单组件 | <bookmark-v2:bookmark-contextmenu> |
当这些旧的组件被替换成新的组件后，原来注册的书签事件将不会被触发。这时候就需要替换这些事件的注册方式，后面将提供示例来说明。
如果您的应用需要自定义书签 UI，请参考自定义书签 UI。
# 应用示例
下面将通过示例来展示如何使用新的书签 API 替换旧版 API。以及对比重构前后两个版本的差异。
# 示例1 —— 监听书签节点添加事件
示例1中，我们展示了如何监听书签节点添加事件，并通过BookmarkDataService (opens new window)实例来修改书签节点的属性：
运行上面的示例并打开文档，然后添加书签面板新增书签，可以发现，新增的书签字体颜色被设置为红色，并且字形被设置为粗体和斜体。
9.* 及以前的版本，书签的事件通过一下方式注册事件：
pdfui.addViewerEventListener(PDFViewCtrl.ViewerEvents.bookmarkAdded, bookmark => {
// 这里操作 bookmark 对象
})
# 示例2 —— 获取书签树节点
在 9.* 及以前的版本中，由于书签是一次性加载到内存，并全部插入到 DOM 树中，所以当书签数量很多时，加载速度会很慢，甚至卡顿。重构以后，书签会根据用户能够看见的书签数量进行加载和渲染，所以加载速度会更快。并且，书签通过 TreeComponent (opens new window) 组件渲染, 为用户预留了一定的自定义空间。下面的示例展示了如何获取到书签树的节点，并修改节点的样式：
和旧版本不同的是，旧版书签的所有 DOM 节点在书签加载完成后就可以通过 querySelector 获取，而新版必须通过监听 create-tree-node 事件获取。
# 示例3 —— undo/redo 的支持
10.0.0 版本中提供了 BookmarkUIService (opens new window) 实例，该实例需要应用层基于 UIExtension 实现时才可用，它提供了和 BookmarkDataService (opens new window) 相同的API，但是支持了 undo/redo 操作。
该示例向书签右键菜单末尾插入自定义菜单项，点击该菜单项，可以将当前选中的书签设置为红色。并且可以通过 Ctrl+Z/Ctrl+Y 来撤销/重做这个操作。需要注意的是，要开启 undo/redo 功能，必须在初始化 PDFUI 时，将 addons 配置项添加上 libPath + '/uix-addons/undo-redo' 或者干脆配置 addons: libPath + '/uix-addons/allInOne.js' 加载所有插件。