# # 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 及以上版本