AnnotComponentConfig 动态配置指南

概述

AnnotComponentConfig 是 Foxit PDF SDK for Web 中用于控制注释组件操作功能的核心配置接口。通过动态更新配置，开发者可以在运行时灵活控制用户对注释功能的使用权限，例如移动、旋转、调整大小等操作。

核心组件

1. AnnotComponentConfig 接口

AnnotComponentConfig 定义了注释组件的所有可用配置属性，具体如下：

export interface AnnotComponentConfig {
    moveable: boolean; // 是否允许移动
    rotatable: boolean; // 是否允许旋转
    resizable: boolean; // 是否允许调整大小
    enableDiagonally: boolean; // 是否允许对角线调整大小
    moveDirection: string; // 移动方向限制
}

2. CustomOptionsUpdater 类

CustomOptionsUpdater 是用于动态更新配置的核心类，提供了运行时修改注释操作功能的能力。

配置属性详解

moveable（可移动性）

• 类型：boolean
• 默认值：
  • 区域高亮注释：false
  • 其他注释类型：true
• 支持的注释类型：stamp，circle，ink，link，square，screen，redact，Area highlight，widget
• 功能：控制注释是否可以被用户移动

rotatable（可旋转性）

• 类型：boolean
• 默认值：true
• 支持的注释类型：stamp
• 功能：控制注释是否可以被用户旋转

resizable（可调整大小）

• 类型：boolean
• 默认值：true
• 支持的注释类型：stamp，circle，ink，link，square，screen，redact，Area highlight，widget
• 功能：控制注释是否可以被用户调整大小

enableDiagonally（对角线调整大小）

• 类型：boolean
• 默认值：true
• 支持的注释类型：ink，link，square，screen，redact，Area highlight，widget
• 功能：当 resizable 为 true 时，控制是否允许对角线调整大小

enableFrame（四边调整大小）

• 类型：boolean
• 默认值：false
• 支持的注释类型：stamp
• 功能：控制注释是否可以从上、下、左、右四个方向调整大小

moveDirection（移动方向）

• 类型：string
• 默认值：'All'
• 支持的注释类型：stamp，circle，ink，link，square，screen，redact，Area highlight，widget
• 可选值：
  • 'horizontal' - 仅允许水平移动
  • 'vertical' - 仅允许垂直移动
  • 'all' - 允许所有方向移动
• 注意: 如果 moveDirection 不是 'all'，则注释无法跨页面移动

使用方法

1. 初始化时配置

创建 PDFViewer 实例时，可以通过 customs.getAnnotComponentConfig 回调函数设置初始配置：

const pdfViewer = new PDFViewer({
    customs: {
        getAnnotComponentConfig: function (annotComponent, props) {
            const annot = annotComponent.getModel();
            const annotType = annot.getType();

            // 根据注释类型返回不同的配置
            switch (annotType) {
                case "square":
                    return { moveable: false, resizable: true };
                case "highlight":
                    if (annot.isArea()) {
                        return { moveable: false };
                    }
                    break;
                case "freetext":
                    return { moveable: false, resizable: false };
                case "strikeout":
                    return { adjustable: false }; // 文本标记注释只支持 adjustable 配置
                case "line":
                    return { moveable: false, resizable: false }; // line，arrow，polyline，polygon，cloud 支持这两个配置
                case "text":
                case "fileattachment":
                    return { moveable: false }; // text 和 file attachment 注释只支持 moveable 配置
            }
            return {}; // 返回空对象表示使用默认配置
        },
    },
});

2. 动态更新配置

使用 CustomOptionsUpdater 可以在运行时动态更新配置：

// 获取配置更新器
const updater = pdfViewer.getCustomOptionsUpdater();

// 动态更新配置
updater.updateGetAnnotComponentConfig(function (annotComponent, props) {
    const annot = annotComponent.getModel();
    const annotType = annot.getType();

    // 根据业务逻辑动态返回配置
    if (annotType === "square") {
        return {
            moveable: false,
            resizable: true,
            enableDiagonally: false,
        };
    } else if (annotType === "highlight" && annot.isArea()) {
        return {
            moveable: false,
            moveDirection: "horizontal", // 只允许水平移动
        };
    }

    return {};
});

各注释类型支持情况一览

注释类型	可移动性 (moveable)	可旋转性 (rotatable)	可调整大小 (resizable)	支持对角线调整大小(enableDiagonally)	支持四边调整大小 (enableFrame)	支持移动方向(moveDirection)
stamp	✅	✅	✅	❌	✅	✅
circle	✅	❌	✅	✅	❌	✅
ink	✅	❌	✅	✅	❌	✅
link	✅	❌	✅	✅	❌	✅
square	✅	❌	✅	✅	❌	✅
screen	✅	❌	✅	✅	❌	✅
redact	✅	❌	✅	✅	❌	✅
Area highlight	✅	❌	✅	✅	❌	✅
widget	✅	❌	✅	✅	❌	✅
freetext(textbox,callout)	✅	❌	✅	✅	❌	❌
freetext(typewriter)	✅	❌	❌	❌	❌	❌
text	✅	❌	❌	❌	❌	❌
fileattachment	✅	❌	❌	❌	❌	❌
textmarks	❌	❌	❌	❌	❌	❌

textmarks (包括 underline，text highlight，strikeout，squiggly，不包括 caret)，仅支持 adjustable 配置。

实际应用场景

说明：以下代码示例中的 getCurrentUserRole 和 getUserPermissions 均为示例占位函数，请根据实际业务逻辑替换为您自己的实现。

1. 文档审阅模式

// 在审阅模式下，禁用用户对注释的修改功能
updater.updateGetAnnotComponentConfig(function (annotComponent, props) {
    const annot = annotComponent.getModel();
    const userRole = getCurrentUserRole(); // 获取当前用户角色

    if (userRole === "reviewer") {
        return {
            moveable: false,
            resizable: false,
            rotatable: false,
        };
    }

    return {};
});

2. 特定注释类型功能控制

// 控制特定类型注释的操作功能
updater.updateGetAnnotComponentConfig(function (annotComponent, props) {
    const annot = annotComponent.getModel();
    const annotType = annot.getType();

    // 禁用所有 link 注释的移动功能
    if (annotType === "link") {
        return { moveable: false };
    }

    // 限制 stamp 注释只能水平移动
    if (annotType === "stamp") {
        return { moveDirection: "horizontal" };
    }

    return {};
});

3. 基于用户权限控制

// 根据用户权限动态控制注释操作功能
updater.updateGetAnnotComponentConfig(function (annotComponent, props) {
    const annot = annotComponent.getModel();
    const userPermissions = getUserPermissions();

    if (!userPermissions.canEditAnnotations) {
        return {
            moveable: false,
            resizable: false,
            rotatable: false,
        };
    }

    if (!userPermissions.canMoveAnnotations) {
        return { moveable: false };
    }

    return {};
});

注意事项

1. 配置优先级：动态更新的配置会覆盖初始化时的配置。
2. 跨页面移动：当 moveDirection 不是 'all' 时，注释无法跨页面移动。
3. 性能考虑：频繁更新配置可能影响性能，建议仅在必要时进行更新。
4. 类型兼容性：不同注释类型支持的配置项不同，需要根据具体类型返回相应的配置。
5. 功能性质：这些配置属于功能开关，主要用于启用/禁用 UI 交互层面的功能，而非基于权限的访问控制。

版本信息

• 引入版本：9.1.0
• moveDirection 支持：11.0.0
• 兼容性：支持 Foxit PDF SDK for Web 9.1.0 及以上版本