# 书签

本章节主要介绍书签组件的自定义方法，由于书签组件基于 tree 组件开发，在开始前，请先了解 tree 组件的用法以及相关API文档 (opens new window)。

# 书签组件结构

这一节介绍书签相关组件的模板结构，涉及侧边栏面板组件、书签右键菜单组件以及书签树节点组件。

# 书签面板

在我们内置的布局模板中，<bookmark-v2:sidebar-panel></bookmark-v2:sidebar-panel> 就是指左侧边栏书签面板，它实际上相当于下面的复杂模板：

<sidebar-panel 
    name="sidebar-bookmark-v2"
    class="fv__ui-sidebar-bookmark-v2"
    @tooltip
    tooltip-placement="right"
    tooltip-title="sidebar.bookmark.tooltip"
    title="sidebar.bookmark.title"
    icon-class="fv__icon-sidebar-bookmark"
    @lazy-content="active"
>
    <bookmark-v2:bookmark-tree></bookmark-v2:bookmark-tree>
</sidebar-panel>

在应用中，复杂模板可以替换内置的精简模板，并修改其属性：

# 书签右键菜单

在内置布局模板中，<bookmark-v2:bookmark-contextmenu @lazy></bookmark-v2:bookmark-contextmenu> 这个标签就是指书签右键菜单，它相当于下面的模板：

<contextmenu name="fv--bookmark-contextmenu-v2">
    <bookmark-v2:add-bookmark name="fv--bookmark-contextmenu-item-add"></bookmark-v2:add-bookmark>
    <contextmenu-separator @bookmark-v2:hide-if-no-bookmark></contextmenu-separator>
    <bookmark-v2:goto-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-goto"></bookmark-v2:goto-bookmark>
    <contextmenu-separator @bookmark-v2:hide-if-no-bookmark></contextmenu-separator>
    <bookmark-v2:cut-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-cut"></bookmark-v2:cut-bookmark>
    <bookmark-v2:paste-under-selected-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-paste-under"></bookmark-v2:paste-under-selected-bookmark>
    <bookmark-v2:paste-after-selected-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-paste-after"></bookmark-v2:paste-after-selected-bookmark>
    <bookmark-v2:delete-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-delete"></bookmark-v2:delete-bookmark>
    <bookmark-v2:set-destination @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-set-destination"></bookmark-v2:set-destination>
    <bookmark-v2:rename-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-rename"></bookmark-v2:rename-bookmark>
</contextmenu>

模板中，针对菜单项，我们使用了一个 @bookmark-v2:hide-if-no-bookmark 指令，这个指令的作用是：当文档没有书签时，右键书签面板，我们需要隐藏一些菜单项，只留下 <bookmark-v2:add-bookmark> 一个组件。

根据这个模板，我们只要定义一个 name 为 fv--bookmark-contextmenu-v2 的右键菜单，替换内置的书签右键菜单，就可以实现覆盖内置书签右键菜单的效果，下面是示例：

<html>
    <div id="pdf-ui"></div>
    <template id="custom-contextmenu-template">
        <contextmenu name="fv--bookmark-contextmenu-v2">
            <bookmark-v2:add-bookmark name="fv--bookmark-contextmenu-item-add"></bookmark-v2:add-bookmark>
            <contextmenu-separator @bookmark-v2:hide-if-no-bookmark></contextmenu-separator>
            <bookmark-v2:goto-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-goto"></bookmark-v2:goto-bookmark>
            <contextmenu-separator @bookmark-v2:hide-if-no-bookmark></contextmenu-separator>
            <bookmark-v2:cut-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-cut"></bookmark-v2:cut-bookmark>
            <bookmark-v2:paste-under-selected-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-paste-under"></bookmark-v2:paste-under-selected-bookmark>
            <bookmark-v2:paste-after-selected-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-paste-after"></bookmark-v2:paste-after-selected-bookmark>
            <bookmark-v2:delete-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-delete"></bookmark-v2:delete-bookmark>
            <bookmark-v2:set-destination @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-set-destination"></bookmark-v2:set-destination>
            <bookmark-v2:rename-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-rename"></bookmark-v2:rename-bookmark>
        </contextmenu>
    </template>
</html>
<style>
    html{
        overflow:hidden;
    }
    body {
        height: 100vh;
    }
    #pdf-ui {
        position: relative;
        top: 50px;
    }
</style>
<script>
    const customBookmarkContextmenuTemplate = document.getElementById('custom-contextmenu-template').innerHTML;
    const CustomAppearance = UIExtension.appearances.adaptive.extend({
        getDefaultFragments() {
            return [{
                target: 'fv--bookmark-contextmenu-v2',
                action: UIExtension.UIConsts.FRAGMENT_ACTION.REPLACE,
                template: customBookmarkContextmenuTemplate
            }];
        }
    });
    const libPath = window.top.location.origin + '/lib';
    const pdfui = new UIExtension.PDFUI({
            viewerOptions: {
                libPath: libPath,
                jr: {
                    licenseSN: licenseSN,
                    licenseKey: licenseKey
                }
            },
            renderTo: '#pdf-ui',
            appearance: CustomAppearance,
            addons: []
    });
</script>

{
    "iframeOptions": {
        "style": "height: 500px"
    }
}

当然，除了整体替换以外，你也可以单独删除或增加菜单项：

<html>
    <div id="pdf-ui"></div>
    <template id="custom-contextmenu-template">
        <contextmenu name="fv--bookmark-contextmenu-v2">
            <bookmark-v2:add-bookmark name="fv--bookmark-contextmenu-item-add"></bookmark-v2:add-bookmark>
            <contextmenu-separator @bookmark-v2:hide-if-no-bookmark></contextmenu-separator>
            <bookmark-v2:goto-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-goto"></bookmark-v2:goto-bookmark>
            <contextmenu-separator @bookmark-v2:hide-if-no-bookmark></contextmenu-separator>
            <bookmark-v2:cut-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-cut"></bookmark-v2:cut-bookmark>
            <bookmark-v2:paste-under-selected-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-paste-under"></bookmark-v2:paste-under-selected-bookmark>
            <bookmark-v2:paste-after-selected-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-paste-after"></bookmark-v2:paste-after-selected-bookmark>
            <bookmark-v2:delete-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-delete"></bookmark-v2:delete-bookmark>
            <bookmark-v2:set-destination @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-set-destination"></bookmark-v2:set-destination>
            <bookmark-v2:rename-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-rename"></bookmark-v2:rename-bookmark>
        </contextmenu>
    </template>
</html>
<style>
    html{
        overflow:hidden;
    }
    body {
        height: 100vh;
    }
    #pdf-ui {
        position: relative;
        top: 50px;
    }
</style>
<script>
    const customBookmarkContextmenuTemplate = document.getElementById('custom-contextmenu-template').innerHTML;
    
    class CustomContextMenuItemComponent extends UIExtension.SeniorComponentFactory.createSuperClass({
        template: `
            <contextmenu-item @on.click="$component.handleClick()">Custom Bookmark Contextmenu Item</contextmenu-item>
        `
    }) {
        static getName() {
            return 'custom-bookmark-contextmenu-item';
        }
        handleClick() {
            const contextmenu = this.parent;
            const target = contextmenu.getCurrentTarget();
            if(target instanceof UIExtension.components.widgets.TreeNodeComponent) {
                alert('Click on bookmark item: ' + target.title);
            }
        }
    }
    
    const customModule = UIExtension.modular.module('custom', []);
    customModule.registerComponent(CustomContextMenuItemComponent);
    
    const CustomAppearance = UIExtension.appearances.adaptive.extend({
        getDefaultFragments() {
            return [{
                target: '@bookmark-v2:rename-bookmark',
                action: UIExtension.UIConsts.FRAGMENT_ACTION.REMOVE
        }, {
            target: 'fv--bookmark-contextmenu-v2',
            action: UIExtension.UIConsts.FRAGMENT_ACTION.APPEND,
            template: `<custom:custom-bookmark-contextmenu-item></custom:custom-bookmark-contextmenu-item>`
        }];
        }
    });
    const libPath = window.top.location.origin + '/lib';
    const pdfui = new UIExtension.PDFUI({
            viewerOptions: {
                libPath: libPath,
                jr: {
                    licenseSN: licenseSN,
                    licenseKey: licenseKey
                }
            },
            renderTo: '#pdf-ui',
            appearance: CustomAppearance,
            addons: []
    });
</script>

{
    "iframeOptions": {
        "style": "height: 500px"
    }
}

# 书签右键菜单项

添加书签菜单项：
- 精简模板： <bookmark-v2:add-bookmark name="fv--bookmark-contextmenu-item-add"></bookmark-v2:add-bookmark>
- 完整模板：<contextmenu-item @controller="AddBookmarkController">contextmenu.bookmark.add</contextmenu-item>
跳转功能菜单项：
- 精简模板：<bookmark-v2:goto-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-goto"></bookmark-v2:goto-bookmark>
- 完整模板：<contextmenu-item @controller="GotoBookmarkController" @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-goto">contextmenu.bookmark.goTo</contextmenu-item>
剪切功能菜单项：
- 精简模板：<bookmark-v2:cut-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-cut"></bookmark-v2:cut-bookmark>
- 完整模板：<contextmenu-item @controller="CutBookmarkController" @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-cut">contextmenu.bookmark.cut</contextmenu-item>
粘贴书签到所选书签下面功能菜单项：
- 精简模板：<bookmark-v2:paste-under-selected-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-paste-under"></bookmark-v2:paste-under-selected-bookmark>
- 完整模板：<contextmenu-item @controller="PasteUnderSelectedBookmarkController as ctrl" @show="ctrl.pasteAvailable" @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-paste-under">contextmenu.bookmark.pasteUnder</contextmenu-item>
粘贴书签到所选书签后面功能菜单项：
- 精简模板：<bookmark-v2:paste-after-selected-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-paste-after"></bookmark-v2:paste-after-selected-bookmark>
- 完整模板：<contextmenu-item @controller="PasteAfterSelectedBookmarkController as ctrl" @show="ctrl.pasteAvailable" @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-paste-after">contextmenu.bookmark.pasteAfter</contextmenu-item>
删除书签功能菜单项：
- 精简模板：<bookmark-v2:delete-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-delete"></bookmark-v2:delete-bookmark>
- 完整模板：<contextmenu-item @controller="DeleteBookmarkController" @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-delete">contextmenu.bookmark.delete</contextmenu-item>
设置书签目标位置菜单项：
- 精简模板：<bookmark-v2:set-destination @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-set-destination"></bookmark-v2:set-destination>
- 完整模板：<contextmenu-item @controller="SetDestinationBookmarkController" @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-set-destination">contextmenu.bookmark.destination</contextmenu-item>
重命名书签菜单项：
- 精简模板：<bookmark-v2:rename-bookmark @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-rename"></bookmark-v2:rename-bookmark>
- 完整模板：<contextmenu-item @controller="RenameBookmarkController" @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-rename">contextmenu.bookmark.rename</contextmenu-item>

以上就是SDK内置支持的各个书签右键菜单项，应用层可以复用这些菜单项的@controller实现并替换内置菜单项来实现自定义菜单项功能。示例：

<html>
    <div id="pdf-ui"></div>
</html>
<style>
    html{
        overflow:hidden;
    }
    body {
        height: 100vh;
    }
    #pdf-ui {
        position: relative;
        top: 50px;
    }
</style>
<script>
    
    class CustomContextMenuItemComponent extends UIExtension.SeniorComponentFactory.createSuperClass({
        template: `
            <contextmenu-item @controller="bookmark-v2:RenameBookmarkController" @bookmark-v2:hide-if-no-bookmark name="fv--bookmark-contextmenu-item-rename" @on.click="$component.handleClick()">contextmenu.bookmark.rename</contextmenu-item>
        `
    }) {
        static getName() {
            return 'custom-bookmark-contextmenu-item';
        }
        handleClick() {
            const contextmenu = this.parent;
            const target = contextmenu.getCurrentTarget();
            if(target instanceof UIExtension.components.widgets.TreeNodeComponent) {
                console.log('Rename bookmark item: ' + target.title);
            }
        }
    }
    
    const customModule = UIExtension.modular.module('custom', []);
    customModule.registerComponent(CustomContextMenuItemComponent);
    
    const CustomAppearance = UIExtension.appearances.adaptive.extend({
        getDefaultFragments() {
            return [{
                target: '@bookmark-v2:rename-bookmark',
                action: UIExtension.UIConsts.FRAGMENT_ACTION.REPLACE,
                template: `<custom:custom-bookmark-contextmenu-item></custom:custom-bookmark-contextmenu-item>`
            }];
        }
    });
    const libPath = window.top.location.origin + '/lib';
    const pdfui = new UIExtension.PDFUI({
            viewerOptions: {
                libPath: libPath,
                jr: {
                    licenseSN: licenseSN,
                    licenseKey: licenseKey
                }
            },
            renderTo: '#pdf-ui',
            appearance: CustomAppearance,
            addons: []
    });
</script>

{
    "iframeOptions": {
        "style": "height: 500px"
    }
}

# 书签树节点

书签树节点也就是 TreeNodeComponent (opens new window)。它和PDF文档的书签数据同步，跟随书签数据的创建和删除移动被创建和销毁。所以要自定义书签树节点，就需要通过事件来实现。TreeComponent (opens new window) 组件开放了这两个事件：

create-tree-node 事件，在创建树节点时触发，可以用于修改树节点外观以及注册树节点上的事件等
destroy-tree-node 事件，在树节点被销毁时触发，可以用于释放一些数据，避免内存泄露

下面是一个示例，展示了如何将树节点的文本内容替换为链接：

# 书签 Service API

基于 PDFViewCtrl 层和 UIExtension 层的不同，我们将书签的API分为两个部分，并提供了两个 Service 实例：

BookmarkDataService (opens new window): PDFViewCtrl 层的书签数据服务，当你的应用是基于 PDFViewCtrl 开发时，只能使用这个服务提供的API进行扩展
BookmarkUIService (opens new window): UIExtension 层基于BookmarkDataService封装的接口，封装了部分BookmarkDataService的接口，用于支持 UI 层的视图与数据同步以及支持 undo-redo 功能。 UIExtension 层也可以使用 BookmarkDataService, 但不包括在 BookmarkUIService 封装过的接口。具体细节请参考API 手册 (opens new window)。

# Example 1

通过 BookmarkDataService 获取和打印一级书签的简单示例：

# Example 2

通过 BookmarkUIService 创建和删除书签的简单示例：

<html>
    <div id="pdf-ui"></div>
    <template id="custom-toolbar-template">
         <div class="custom-toolbar" @var.toolbar="$component">
            <xbutton @on.click="toolbar.addBookmark()">Create</xbutton>
            <xbutton @on.click="toolbar.deleteSelectedBookmark()">Delete</xbutton>
        </div>
    </template>
</html>
<style>
    html{
        overflow:hidden;
    }
    body {
        height: 100vh;
        
    }
    #pdf-ui {
        position: relative;
        top: 50px;
    }
    .custom-toolbar {
        display: flex;
        gap: 10px;
        border-bottom: 1px solid #f0f0f0;
        padding: 5px 0;
    }
</style>
<script>
    const customBookmarkContextmenuTemplate = document.getElementById('custom-toolbar-template').innerHTML;
    
    class CustomBookmarkToolbarComponent extends UIExtension.SeniorComponentFactory.createSuperClass({
        template: customBookmarkContextmenuTemplate
    }) {
        static getName() {
            return 'custom-bookmark-toolbar';
        }
        addBookmark() {
            const service = this.getPDFUI().getBookmarkUIService();
            const text = prompt("Create new bookmark", "Untitled");
            service.addBookmark({
                title: text,
                relationship: PDF.bookmark.BookmarkRelationship.LAST_CHILD
            })
        }
        deleteSelectedBookmark() {
            const service = this.getPDFUI().getBookmarkUIService();
            const bookmarkId = service.getCurrentActiveBookmarkId();
            if(bookmarkId === undefined) {
                alert('You did not select a bookmark');
                return;
            }
            const confirmed = confirm('Are you sure you want to delete this bookmark? ')
            if(confirmed) {
                service.deleteBookmark(bookmarkId)
            }
        }
    }
    
    const customModule = UIExtension.modular.module('custom', []);
    customModule.registerComponent(CustomBookmarkToolbarComponent);
    
    const CustomAppearance = UIExtension.appearances.adaptive.extend({
        getDefaultFragments() {
            return [{
                target: 'sidebar-bookmark-v2',
                action: UIExtension.UIConsts.FRAGMENT_ACTION.PREPEND,
                template: `<custom:custom-bookmark-toolbar></custom:custom-bookmark-toolbar>`
            }];
        }
    });
    const libPath = window.top.location.origin + '/lib';
    const pdfui = new UIExtension.PDFUI({
            viewerOptions: {
                libPath: libPath,
                jr: {
                    licenseSN: licenseSN,
                    licenseKey: licenseKey
                }
            },
            renderTo: '#pdf-ui',
            appearance: CustomAppearance,
            addons: []
    });
</script>

{
    "iframeOptions": {
        "style": "height: 500px"
    }
}