# AnnotationAuthorityManager

在正式介绍如何使用这个工具类 AnnotationAuthorityManager之前,我们先来了解一下注释权限类型及设置方式。

# 注释权限类型

注释的权限类型有以下三种:

  1. PDF注释权限:PDF文档本身对注释的操作限制, 可以通过User_Permissions (opens new window) (全局)或者 Annot_Flags (opens new window) (单个annotation) 来进行设置。对PDF注释权限的设置,会写入到文档,从而改变文档。

  2. 视图注释权限:视图层对注释的操作限制。对视图注释权限的设置只影响应用层,不会写入到文档,也不会改变文档。

  3. 交互注释权限:对PDF注释权限和视图注释权限取交集,即为交互注释权限。在加载PDF文档后,用户对注释的操作限制。

# 注释权限的设置方式

Foxit PDF SDK for Web提供了以下 4 种方式来设置注释权限,具体如下:

  1. 通过 PDFViewer构造器设置视图注释权限,比如options.customs.getDocPermissions=(doc:PDFDoc)=>-1 (opens new window)options.customs.getAnnotPermissions=(annot:Annot)=>Promise.resolve() (opens new window)

  2. 通过AnnotationAuthorityManager工具类实时动态设置视图注释权限setAnnotPermissionCallback (opens new window)

  3. 通过PDFDoc::setPasswordAndPermission (opens new window)全局设置PDF注释权限。

  4. 通过Annot:setFlags (opens new window)设置PDF注释权限。

# AnnotationAuthorityManager的使用

您可以通过设置PDF注释权限或者视图注释权限来更新交互注释权限。在某些场景中,您可能并不想对原始文档进行修改,而只是想在应用层控制用户对annotation的操作权限。那么,您可以使用AnnotationAuthorityManager工具类来实时设置annotation的视图注释权限,然后更新交互注释权限即可实现。

Note: 当应用层对annotation交互注释权限更新时,Web SDK内部会将应用层设置的视图注释权限与PDF注释权限进行取交集,来确定用户可以对annotation操作的最终交互权限。

# 交互注释权限更新时机

以下示例代码将演示用户如何被动或主动的更新交互注释权限。

  1. 被动更新交互注释权限

在文档打开之前,用户可以通过setAnnotPermissionCallback (opens new window)options.customs.getDocPermissions=(doc:PDFDoc)=>-1 (opens new window)options.customs.getAnnotPermissions=(annot:Annot)=>Promise.resolve() (opens new window)先设置权限。在文档打开后,SDK>> 会自动更新交互注释权限,用户无需另外设置。

Note: 这里"被动更新"是指SDK在打开文档后会自动完成交互注释权限的校验与更新,无需用户主动去调用接口来更新。

    // 在打开文档之前,设置视图注释权限方式有以下两种:

    // 第一种方法:构建PDFViewer对象时,根据annotation的信息设置视图注释权限
    const pdfui = new PDFUI({
        viewerOptions: {
            customs:{
                // 设置视图注释权限 
                getAnnotPermissions:function(annot){
                    const ANNOTATION_PERMISSION = UIExtension.PDFViewCtrl.constants.ANNOTATION_PERMISSION
                    // 设置为拥有所有的视图注释权限 
                    return Promise.resolve([ANNOTATION_PERMISSION.fully]);
                }
            }
        }
    })

    // 第二种方法:通过AnnotationAuthorityManager管理器,设置视图注释权限
    const pdfViewer = await pdfui.getPDFViewer();
    // 获取AnnotationAuthorityManager管理器
    const annotAuthMgr = pdfViewer.getAnnotAuthorityManager();
    // 设置视图注释权限
    annotAuthMgr.setAnnotPermissionCallback(function(annot) {
        // 设置为没有任何操作权限
        return Promise.resolve([]); 
    })

    // 打开PDF文档时,SDK会读取设置的视图注释权限,然后自动更新交互注释权限
    pdfui.openPDFByHttpRangeRequest('http:xxx');
  1. 主动更新交互权限

在文档打开之后,用户可以动态设置权限,再通过updateAll() (opens new window)update() (opens new window)来主动更新交互注释权限。

    // 打开PDF文档
    pdfui.openPDFByHttpRangeRequest('http:xxx');
    
    // 通过AnnotationAuthorityManager管理器,设置视图注释权限
    const pdfViewer = await pdfui.getPDFViewer();
    // 获取AnnotationAuthorityManager管理器
    const annotAuthMgr = pdfViewer.getAnnotAuthorityManager();
    // 设置视图注释权限 
    annotAuthMgr.setAnnotPermissionCallback(function(annot) {
        // 设置为所有的annotation没有任何操作权限
        return Promise.resolve([]);
    })

    // 需要手动更新所有annotation的交互注释权限,否则设置的视图注释权限无法立即生效
    await annotAuthMgr.updateAll();

在实际项目中,用户可以通过PDFViewer.getCurrentPDFDoc (opens new window)获取当前的文档对象,来校验当前的文档对象是否已打开, 如果值为null,则表示文档未打开。

# 视图注释权限使用场景

实际场景可能需要设置不同的视图注释权限,目前主要有以下四种类型。下面的示例是直接基于一个创建好的 AnnotationAuthorityManager 实例进行。

  1. 无权限

        // 设置视图注释权限 
        annotAuthMgr.setAnnotPermissionCallback(function(annot) {
            // 设置为所有的annotation没有任何操作权限
            return Promise.resolve([]);
        })
    
  2. 组合权限

        const ANNOTATION_PERMISSION = UIExtension.PDFViewCtrl.constants.ANNOTATION_PERMISSION
        // 设置视图注释权限  
        annotAuthMgr.setAnnotPermissionCallback(function(annot) {
            //设置所有的annotation的权限为:可修改属性与行为,可删除/移动/旋转/缩放
            return Promise.resolve([ANNOTATION_PERMISSION.adjustable,ANNOTATION_PERMISSION.deletable,ANNOTATION_PERMISSION.modifiable]);
        })
    
  3. 所有权限

        const ANNOTATION_PERMISSION = UIExtension.PDFViewCtrl.constants.ANNOTATION_PERMISSION
        // 设置视图注释权限 
        annotAuthMgr.setAnnotPermissionCallback(function(annot) {
            // 设置为拥有所有的视图注释权限
            return Promise.resolve([ANNOTATION_PERMISSION.fully]);
        })
    
  4. 可忽略权限

        // 设置视图注释权限 
        annotAuthMgr.setAnnotPermissionCallback(function(annot) {
            //设置所有的annotation的权限为:忽略所有权限限制
            return null;
        })
    

# 交互注释权限的使用场景

# 示例1:设置Annotation的视图权限,不允许删除指定的annotation

    const pdfViewer = await pdfui.getPDFViewer();
    // 获取AnnotationAuthorityManager管理器
    const annotAuthMgr = pdfViewer.getAnnotAuthorityManager();
    // 获取指定页面的指定附件类型annotationRender
    const fileAnnotRender = pdfViewer.getAnnotRender(0,'name');
    // 获取指定页面的指定附件类型annotation
    const fileAnnot = fileAnnotRender.getAnnot();
    const ANNOTATION_PERMISSION = PDFViewCtrl.constants.ANNOTATION_PERMISSION
    // 设置视图注释权限
    annotAuthMgr.setAnnotPermissionCallback(function(annot) {
        // 设置指定的fileAnnot没有删除权限
        if(annot.getObjectNumber()=== fileAnnot.getObjectNumber()){
            return Promise.resolve(Object.keys(ANNOTATION_PERMISSION).filter(per=>per!==ANNOTATION_PERMISSION.deletable && per!==ANNOTATION_PERMISSION.fully));
        }
    })

    // 更新指定annotation的交互注释权限
    await annotAuthMgr.update(fileAnnot);

以上代码执行后,用户就无法删除指定name的annotation。 无删除权限

# 示例2:设置Annotation的视图注释权限,允许编辑 callout 内容

    const pdfViewer = await pdfui.getPDFViewer();
    //获取AnnotationAuthorityManager管理器
    const annotAuthMgr = pdfViewer.getAnnotAuthorityManager();
    const ANNOTATION_PERMISSION = PDFViewCtrl.constants.ANNOTATION_PERMISSION
    // 设置视图注释权限
    annotAuthMgr.setAnnotPermissionCallback(function(annot) {
        // 设置callout类型的annotation具有编辑权限
        if(annot.getIntent()=== 'FreeTextCallout'){
            return Promise.resolve([ANNOTATION_PERMISSION.editable]);
        }
    })

    // 更新所有annotation的交互注释权限
    await annotAuthMgr.updateAll();

以上代码执行后,用户就可以编辑FreeText对象为callout的annotation。 有权限

# 示例3: 自定义组件上校验PDF注释权限和视图注释权限

以下代码片段将演示在新增一个自定义的组件后如何校验注释权限。

    var pdfui = new PDFUI({
        // 自定义新增一个删除annotation的组件
        fragments: [{
            target: 'hand-tool',
            template: '<xbutton class="fv__ui-toolbar-show-text-button" name="cus-delete-button">button behind of hand-tool</xbutton>',
            action: UIExtension.UIConsts.FRAGMENT_ACTION.AFTER,
            config: [{
                target: 'cus-delete-button',
                callback: PDFViewCtrl.shared.createClass({
                    mounted: function() {
                        this.permissionHandler();
                    },
                    permissionHandler(){
                        const Events = UIExtension.UIEvents;
                        let permissionHandler = async ()=>{
                            const docRender = await pdfui.getPDFDocRender()
                            // 获取PDF注释权限
                            const userPermission = docRender.getUserPermission().getValue();
                            const {AnnotForm} = UIExtension.PDFViewCtrl.Consts.PDFDocPermission;
                            this.hasAnnotForm = (userPermission & AnnotForm) === AnnotForm;
                            // 是否禁用此组件
                            this.component[this.hasAnnotForm?'enable':'disable']();
                        }
                        this.addDestroyHook(
                            pdfui.addViewerEventListener(Events.openFileSuccess,permissionHandler)
                            pdfui.addViewerEventListener(Events.permissionChanged,permissionHandler)
                            pdfui.addViewerEventListener(Events.activeAnnotation,async annotRender=>{
                                // 获取激活的annotation
                                const annot = annotRender.getAnnot();
                                const pdfViewer = await pdfui.getPDFViewer();
                                // 获取AnnotationAuthorityManager管理器
                                const annotAuthMgr = pdfViewer.getAnnotAuthorityManager();
                                // 获取指定annotation的视图注释权限
                                const annotPermission = await annotAuthMgr.getPermission(annot);
                                // 是否可以删除annot
                                const isDeleteAble = annotPermission.isDeletable();
                                // 是否禁用此组件
                                this.component[isDeleteAble&&this.hasAnnotForm?'enable':'disable']();
                            })
                        );
                    }
                }, UIExtension.Controller)
            }]
        }]
    });

# 视图注释权限的限制

目前视图注释权限的限制范围:

  1. Redaction Apply 功能不支持设置交互权限.
  2. 目前 AnnotationAuthorityManager 不支持 Form Widget.