注释配置器

概述

注释配置器 AnnotComponentConfig 是 福昕 PDF SDK (Web) 版 中用于控制注释组件（Annot Component）交互行为的核心配置对象。通过在运行时动态更新配置，开发者可以灵活控制用户对注释的移动、旋转、缩放等操作能力。

说明：这里的配置主要控制界面交互能力（能否拖动、缩放等），与文档权限（只读、禁止注释等）属于不同层面，需结合权限 API 一并设计。

核心组成

1. AnnotComponentConfig API

AnnotComponentConfig 定义了注释组件可用的配置字段，接口形态如下：

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

2. CustomOptionsUpdater 类 （自定义配置更新器）

CustomOptionsUpdater 用于在运行时动态更新上述配置，是配合 updateGetAnnotComponentConfig 等入口使用的核心类。

配置项说明

moveable

• 类型：boolean
• 默认值：
  • 区域高亮（Area Highlight）：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 }; // 线、箭头、折线、多边形、云线等支持这两项
                case "text":
                case "fileattachment":
                    return { moveable: false }; // 文本注释与附件注释通常仅配置 moveable
            }
            return {}; // 返回空对象表示沿用各类型默认配置
        },
    },
});

2. 运行时动态更新

通过 CustomOptionsUpdater 在运行时覆盖或调整配置：

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

// 动态更新 getAnnotComponentConfig 回调
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（文本框、标注）	✅	❌	✅	✅	❌	❌
freetext（打字机）	✅	❌	❌	❌	❌	❌
text	✅	❌	❌	❌	❌	❌
fileattachment	✅	❌	❌	❌	❌	❌
textmarks	❌	❌	❌	❌	❌	❌

TextMarks（含下划线、文本高亮、删除线、波浪线等，不含 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. 配置优先级：运行时通过 updateGetAnnotComponentConfig 设置的逻辑会覆盖初始化阶段 customs.getAnnotComponentConfig 中的结果（以最后一次注册的回调为准，注意避免多次覆盖丢失分支）。
2. 跨页移动：当 moveDirection 不为 'all' 时，注释不能跨页拖动。
3. 性能：回调会在注释交互路径上频繁触发，请保持逻辑轻量，避免在其中做重计算或远程同步。
4. 类型兼容：不同注释类型支持的字段不同，返回对象中不支持的字段可能被忽略；请对照上表与 API 文档确认。
5. 与权限的区别：本组配置是交互开关，不能替代 PDF 文档权限或 SDK 权限模型；只读文档等场景仍需使用权限相关 API。

版本信息

• 首次提供：9.1.0
• 新增 moveDirection：11.0.0
• 兼容性：福昕 PDF SDK (Web) 版 9.1.0 及以上