PDF插件自定义批注相关接口

概述

本节介绍软航OFFICE文档控件PDF插件自定义批注相关接口，这些接口允许开发者在PDF文档中管理自定义批注，为PDF文档管理系统提供完整的批注控制能力。

注意： PDF插件提供了批注侧边栏来展现自定义批注信息，详见ShowSidebar方法介绍。

批注用户设置

SetAnnotateUser

语法：

javascript

SetAnnotateUser(AnnotateUser)

功能：
设置自定义批注人名称。

参数：

名称	必选/可选	数据类型	说明
AnnotateUser	必选	string	自定义批注人名称

返回值：
无返回值

说明：
可在OnDocumentOpened事件中设置自定义批注人名称，一般可设置为当前应用系统的用户名。如果不设置批注人名称，则默认为Administrator。自定义批注人不仅是用来标识批注的插入者信息，同时也是标识批注的所属权。批注人可以修改自己的批注内容以及设置该批注是否允许他人修改。文档中其他人的（未开放修改权限的）批注，只能查看不能修改。

使用示例：

javascript

// 基本用法
var plugInObj = OfficeControlObj.ActiveDocument;

// 设置批注人名称
plugInObj.SetAnnotateUser("张三");
console.log("批注人名称已设置为: 张三");

// 在文档打开事件中设置
<script type="text/javascript" language="javascript" for="TANGER_OCX" event="OnDocumentOpened(TANGER_OCX_str,TANGER_OCX_obj);">
    TANGER_OCX_obj.SetAnnotateUser("当前用户");
</script>

批注操作方法

AddAnnotate

语法：

javascript

AddAnnotate(text)

功能：
插入自定义批注。

参数：

名称	必选/可选	数据类型	说明
text	必选	string	自定义批注内容

返回值：
无返回值

说明：
执行本方法前，可以先在PDF文档中选中文字区域，即是批注所在位置。

使用示例：

javascript

// 基本用法
var plugInObj = OfficeControlObj.ActiveDocument;

// 插入批注
plugInObj.AddAnnotate("这是一个重要的批注");
console.log("批注已插入");

// 插入多个批注
var annotations = [
    "这是第一个批注",
    "这是第二个批注",
    "这是第三个批注"
];

for (var i = 0; i < annotations.length; i++) {
    plugInObj.AddAnnotate(annotations[i]);
    console.log("批注" + (i + 1) + "已插入");
}

GetAnnotateCount

语法：

javascript

GetAnnotateCount()

功能：
获取自定义批注个数。

返回值：
数值型

说明：
获取自定义批注个数。

使用示例：

javascript

// 基本用法
var plugInObj = OfficeControlObj.ActiveDocument;

// 获取批注个数
var annotateCount = plugInObj.GetAnnotateCount();
console.log("批注个数:", annotateCount);

// 遍历所有批注
for (var i = 0; i < annotateCount; i++) {
    var annotateObj = plugInObj.GetAnnotateObjFromIndex(i);
    if (annotateObj) {
        console.log("批注" + i + ":", annotateObj.AnnotData);
    }
}

GetAnnotateObjFromIndex

语法：

javascript

GetAnnotateObjFromIndex(Index)

功能：
根据索引获取自定义批注对象。

参数：

名称	必选/可选	数据类型	说明
Index	必选	long	自定义批注索引

返回值：
Object对象

说明：
返回的Object对象包含了自定义批注的相关信息，可以通过JS代码进行获取。

使用示例：

javascript

// 基本用法
var plugInObj = OfficeControlObj.ActiveDocument;

// 获取指定索引的批注对象
var annotateObj = plugInObj.GetAnnotateObjFromIndex(0);
if (annotateObj) {
    var annotData = annotateObj.AnnotData;        // 批注内容
    var annotTime = annotateObj.AnnotTime;        // 批注插入时间
    var userName = annotateObj.UserName;          // 批注人，即SetAnnotateUser方法设置的名称
    var pageNumber = annotateObj.PageNumber;      // 批注所在页码
    var annotX = annotateObj.X;                    // 批注所在X坐标位置
    var annotY = annotateObj.Y;                    // 批注所在Y坐标位置
    
    console.log("批注信息:");
    console.log("内容:", annotData);
    console.log("时间:", annotTime);
    console.log("用户:", userName);
    console.log("页码:", pageNumber);
    console.log("位置:", annotX, annotY);
}

// 获取所有批注对象
var annotateCount = plugInObj.GetAnnotateCount();
for (var i = 0; i < annotateCount; i++) {
    var annotateObj = plugInObj.GetAnnotateObjFromIndex(i);
    if (annotateObj) {
        console.log("批注" + i + ":", annotateObj.AnnotData);
    }
}

RemoveAnnotateByIndex

语法：

javascript

RemoveAnnotateByIndex(Index)

功能：
根据索引删除指定的自定义批注对象。

参数：

名称	必选/可选	数据类型	说明
Index	必选	long	自定义批注索引

返回值：
无返回值

说明：
根据索引删除指定的自定义批注对象。

使用示例：

javascript

// 基本用法
var plugInObj = OfficeControlObj.ActiveDocument;

// 删除指定索引的批注
plugInObj.RemoveAnnotateByIndex(0);
console.log("批注已删除");

// 删除所有批注
var annotateCount = plugInObj.GetAnnotateCount();
for (var i = annotateCount - 1; i >= 0; i--) {
    plugInObj.RemoveAnnotateByIndex(i);
    console.log("批注" + i + "已删除");
}

RemoveAllAnnotate

语法：

javascript

RemoveAllAnnotate()

功能：
删除所有自定义批注。

返回值：
无返回值

说明：
删除所有自定义批注。

使用示例：

javascript

// 基本用法
var plugInObj = OfficeControlObj.ActiveDocument;

// 删除所有批注
plugInObj.RemoveAllAnnotate();
console.log("所有批注已删除");

批注数据管理

GetCustomAnnotatesData

语法：

javascript

GetCustomAnnotatesData([bstrUserName])

功能：
获取PDF文档中自定义批注数据。

参数：

名称	必选/可选	数据类型	说明
bstrUserName	可选	string	自定义批注人名称

返回值：
自定义批注二进制数据流

说明：
参数bstrUserName：可选。如果不传则为当前文档所有用户的批注信息；如果有传值则为指定用户的批注信息。由于自定义批注并不属于PDF文档的一部分，所以自定义批注并不能像插入的图片那样随着PDF文档一起提交保存。因此，需要通过此方法提取出自定义批注的二进制数据到一个表单对象中，随文档控件的SaveToURL方法一并提交到服务器（也可以通过Ajax提交），单独存储到数据库独立字段中。在打开PDF文档时，再将存储的二进制数据赋给PutCustomAnnotatesData就可以加载到PDF文档中。

使用示例：

javascript

// 基本用法
var plugInObj = OfficeControlObj.ActiveDocument;

// 获取所有批注数据
var annotatesData = plugInObj.GetCustomAnnotatesData();
console.log("批注数据:", annotatesData);

// 获取指定用户的批注数据
var userAnnotatesData = plugInObj.GetCustomAnnotatesData("张三");
console.log("张三的批注数据:", userAnnotatesData);

// 提交时把批注数据赋给一个hide控件提交到服务器
document.getElementById("hidAnnotateData").value = plugInObj.GetCustomAnnotatesData();
plugInObj.SaveToURL("../upLoadPdfFile.jsp?", "EDITFILE", "", "", 0);

PutCustomAnnotatesData

语法：

javascript

PutCustomAnnotatesData(pData, [bstrUserName])

功能：
将自定义批注数据加载到PDF文档中。

参数：

名称	必选/可选	数据类型	说明
pData	必选	string	批注二进制数据
bstrUserName	可选	string	自定义批注人名称

返回值：
无返回值

说明：
参数pData：从服务器返回的批注二进制流数据。参数bstrUserName：可选。如果不传则加载所有用户的批注信息；如果有传值则只加载指定用户的批注信息。

使用示例：

javascript

// 基本用法
var plugInObj = OfficeControlObj.ActiveDocument;

// 加载所有批注数据
plugInObj.PutCustomAnnotatesData(annotatesData);
console.log("批注数据已加载");

// 加载指定用户的批注数据
plugInObj.PutCustomAnnotatesData(userAnnotatesData, "张三");
console.log("张三的批注数据已加载");

// 在文档打开事件中加载批注数据
<script type="text/javascript" language="javascript" for="TANGER_OCX" event="OnDocumentOpened(TANGER_OCX_str,TANGER_OCX_obj);">
    TANGER_OCX_obj.PutCustomAnnotatesData(AnnData);
</script>

方法分类总结

分类	方法	功能	说明
用户设置	`SetAnnotateUser`	设置批注人	设置自定义批注人名称
批注操作	`AddAnnotate`	添加批注	插入自定义批注
批注操作	`GetAnnotateCount`	获取批注个数	获取自定义批注个数
批注操作	`GetAnnotateObjFromIndex`	获取批注对象	根据索引获取自定义批注对象
批注操作	`RemoveAnnotateByIndex`	删除批注	根据索引删除指定的自定义批注对象
批注操作	`RemoveAllAnnotate`	删除所有批注	删除所有自定义批注
数据管理	`GetCustomAnnotatesData`	获取批注数据	获取PDF文档中自定义批注数据
数据管理	`PutCustomAnnotatesData`	加载批注数据	将自定义批注数据加载到PDF文档中

使用流程

1. 基本批注管理流程

javascript

// 基本批注管理流程
function basicAnnotateManagement() {
    var plugInObj = OfficeControlObj.ActiveDocument;
    
    // 设置批注人
    function setAnnotateUser() {
        plugInObj.SetAnnotateUser("当前用户");
        console.log("批注人已设置");
    }
    
    // 添加批注
    function addAnnotate() {
        plugInObj.AddAnnotate("这是一个重要的批注");
        console.log("批注已添加");
    }
    
    // 获取批注信息
    function getAnnotateInfo() {
        var count = plugInObj.GetAnnotateCount();
        console.log("批注个数:", count);
        
        for (var i = 0; i < count; i++) {
            var annotateObj = plugInObj.GetAnnotateObjFromIndex(i);
            if (annotateObj) {
                console.log("批注" + i + ":", annotateObj.AnnotData);
            }
        }
    }
    
    return {
        setAnnotateUser: setAnnotateUser,
        addAnnotate: addAnnotate,
        getAnnotateInfo: getAnnotateInfo
    };
}

2. 高级批注管理流程

javascript

// 高级批注管理流程
function advancedAnnotateManagement() {
    var plugInObj = OfficeControlObj.ActiveDocument;
    
    // 批注管理配置
    var annotateConfig = {
        enableLogging: true,
        enableValidation: true,
        enableErrorHandling: true,
        enableQualityControl: true
    };
    
    // 应用批注管理配置
    function applyAnnotateConfig() {
        try {
            if (annotateConfig.enableLogging) {
                console.log("批注管理日志已启用");
            }
            
            if (annotateConfig.enableValidation) {
                console.log("批注验证已启用");
            }
            
            console.log("批注管理配置应用成功");
        } catch (error) {
            console.error("批注管理配置应用失败:", error);
        }
    }
    
    // 监控批注状态
    function monitorAnnotateStatus() {
        var status = {
            annotateCount: plugInObj.GetAnnotateCount(),
            annotatesData: plugInObj.GetCustomAnnotatesData()
        };
        
        console.log("批注状态监控:", status);
        return status;
    }
    
    return {
        applyAnnotateConfig: applyAnnotateConfig,
        monitorAnnotateStatus: monitorAnnotateStatus
    };
}

3. 批注质量控制流程

javascript

// 批注质量控制流程
function annotateQualityControl() {
    var plugInObj = OfficeControlObj.ActiveDocument;
    
    // 批注质量控制
    function controlAnnotateQuality() {
        var annotateQuality = {
            totalAnnotates: 0,
            validAnnotates: 0,
            invalidAnnotates: 0,
            qualityScore: 0
        };
        
        annotateQuality.totalAnnotates = plugInObj.GetAnnotateCount();
        
        for (var i = 0; i < annotateQuality.totalAnnotates; i++) {
            var annotateObj = plugInObj.GetAnnotateObjFromIndex(i);
            if (annotateObj && annotateObj.AnnotData && annotateObj.AnnotData.trim() !== "") {
                annotateQuality.validAnnotates++;
            } else {
                annotateQuality.invalidAnnotates++;
            }
        }
        
        if (annotateQuality.totalAnnotates > 0) {
            annotateQuality.qualityScore = (annotateQuality.validAnnotates / annotateQuality.totalAnnotates) * 100;
        }
        
        console.log("批注质量控制:", annotateQuality);
        return annotateQuality;
    }
    
    // 执行质量控制
    var qualityResult = controlAnnotateQuality();
    console.log("批注质量控制结果:", qualityResult);
}

完整示例

1. 基础批注管理

javascript

// 基础批注管理示例
function basicAnnotateManagement() {
    var plugInObj = OfficeControlObj.ActiveDocument;
    
    // 设置批注人
    function setAnnotateUser() {
        plugInObj.SetAnnotateUser("当前用户");
        console.log("批注人已设置");
    }
    
    // 添加批注
    function addAnnotate() {
        plugInObj.AddAnnotate("这是一个重要的批注");
        console.log("批注已添加");
    }
    
    // 获取批注信息
    function getAnnotateInfo() {
        var count = plugInObj.GetAnnotateCount();
        console.log("批注个数:", count);
        
        for (var i = 0; i < count; i++) {
            var annotateObj = plugInObj.GetAnnotateObjFromIndex(i);
            if (annotateObj) {
                console.log("批注" + i + ":", annotateObj.AnnotData);
            }
        }
    }
    
    return {
        setAnnotateUser: setAnnotateUser,
        addAnnotate: addAnnotate,
        getAnnotateInfo: getAnnotateInfo
    };
}

2. 高级批注管理

javascript

// 高级批注管理示例
function advancedAnnotateManagement() {
    var plugInObj = OfficeControlObj.ActiveDocument;
    
    // 批注管理配置
    var annotateConfig = {
        enableLogging: true,
        enableValidation: true,
        enableErrorHandling: true,
        enableQualityControl: true
    };
    
    // 应用批注管理配置
    function applyAnnotateConfig() {
        if (annotateConfig.enableLogging) {
            console.log("批注管理日志已启用");
        }
        
        if (annotateConfig.enableValidation) {
            console.log("批注验证已启用");
        }
        
        console.log("批注管理配置应用完成");
    }
    
    // 监控批注状态
    function monitorAnnotateStatus() {
        var status = {
            annotateCount: plugInObj.GetAnnotateCount(),
            annotatesData: plugInObj.GetCustomAnnotatesData()
        };
        
        console.log("批注状态:", status);
        return status;
    }
    
    return {
        applyAnnotateConfig: applyAnnotateConfig,
        monitorAnnotateStatus: monitorAnnotateStatus
    };
}

3. 批注质量控制

javascript

// 批注质量控制示例
function annotateQualityControl() {
    var plugInObj = OfficeControlObj.ActiveDocument;
    
    // 批注质量控制
    function controlAnnotateQuality() {
        var annotateQuality = {
            totalAnnotates: 0,
            validAnnotates: 0,
            invalidAnnotates: 0,
            qualityScore: 0
        };
        
        annotateQuality.totalAnnotates = plugInObj.GetAnnotateCount();
        
        for (var i = 0; i < annotateQuality.totalAnnotates; i++) {
            var annotateObj = plugInObj.GetAnnotateObjFromIndex(i);
            if (annotateObj && annotateObj.AnnotData && annotateObj.AnnotData.trim() !== "") {
                annotateQuality.validAnnotates++;
            } else {
                annotateQuality.invalidAnnotates++;
            }
        }
        
        if (annotateQuality.totalAnnotates > 0) {
            annotateQuality.qualityScore = (annotateQuality.validAnnotates / annotateQuality.totalAnnotates) * 100;
        }
        
        console.log("批注质量控制:", annotateQuality);
        return annotateQuality;
    }
    
    // 执行质量控制
    var qualityResult = controlAnnotateQuality();
    console.log("批注质量控制结果:", qualityResult);
}

注意事项

批注人设置：在文档打开事件中设置批注人名称
批注内容：批注内容不能为空，确保内容的有效性
批注位置：批注位置需要正确设置
错误处理：实现完善的错误处理机制
性能考虑：避免频繁操作批注
资源管理：及时清理不需要的批注
状态同步：保持批注状态的一致性

错误处理

javascript

// 批注管理错误处理
function handleAnnotateError(operationType, error) {
    console.error("批注管理处理失败:", operationType, error.message);
    
    switch(operationType) {
        case 'AddAnnotate':
            console.log("批注添加失败，请检查:");
            console.log("1. 批注内容是否有效");
            console.log("2. 批注位置是否正确");
            console.log("3. 文档状态是否正常");
            break;
        case 'GetAnnotateObjFromIndex':
            console.log("批注对象获取失败，请检查:");
            console.log("1. 批注索引是否正确");
            console.log("2. 批注是否存在");
            console.log("3. 文档状态是否正常");
            break;
        case 'RemoveAnnotateByIndex':
            console.log("批注删除失败，请检查:");
            console.log("1. 批注索引是否正确");
            console.log("2. 批注是否存在");
            console.log("3. 文档状态是否正常");
            break;
        default:
            console.log("未知批注管理处理失败");
    }
}

最佳实践

1. 批注管理最佳实践

javascript

// 批注管理最佳实践
function annotateManagementBestPractice() {
    // 批注管理配置
    var annotateConfig = {
        enableLogging: true,
        enableValidation: true,
        enableErrorHandling: true,
        enableQualityControl: true
    };
    
    // 应用批注管理配置
    function applyAnnotateConfig() {
        try {
            // 设置批注管理处理
            if (annotateConfig.enableLogging) {
                console.log("批注管理日志已启用");
            }
            
            if (annotateConfig.enableValidation) {
                console.log("批注验证已启用");
            }
            
            console.log("批注管理配置应用成功");
        } catch (error) {
            handleAnnotateError('applyAnnotateConfig', error);
        }
    }
    
    // 应用配置
    applyAnnotateConfig();
}

2. 批注质量控制最佳实践

javascript

// 批注质量控制最佳实践
function annotateQualityControlBestPractice() {
    // 批注质量控制
    function controlAnnotateQuality() {
        try {
            // 批注质量控制
            var annotateQuality = {
                totalAnnotates: 0,
                validAnnotates: 0,
                invalidAnnotates: 0,
                qualityScore: 0
            };
            
            // 计算质量分数
            if (annotateQuality.totalAnnotates > 0) {
                annotateQuality.qualityScore = (annotateQuality.validAnnotates / annotateQuality.totalAnnotates) * 100;
            }
            
            console.log("批注质量控制完成:", annotateQuality);
            return annotateQuality;
        } catch (error) {
            console.error("批注质量控制失败:", error.message);
            return null;
        }
    }
    
    // 执行质量控制
    var qualityResult = controlAnnotateQuality();
    console.log("批注质量控制结果:", qualityResult);
}

技术要点

批注人设置：在文档打开事件中设置批注人名称
批注内容：批注内容不能为空，确保内容的有效性
批注位置：批注位置需要正确设置
错误处理：完善的错误处理机制
性能优化：避免频繁操作批注
资源管理：及时清理不需要的批注
状态同步：保持批注状态的一致性

PDF插件自定义批注相关接口 ​

概述 ​

批注用户设置 ​

SetAnnotateUser ​

批注操作方法 ​

AddAnnotate ​

GetAnnotateCount ​

GetAnnotateObjFromIndex ​

RemoveAnnotateByIndex ​

RemoveAllAnnotate ​

批注数据管理 ​

GetCustomAnnotatesData ​

PutCustomAnnotatesData ​

方法分类总结 ​

使用流程 ​

1. 基本批注管理流程 ​

2. 高级批注管理流程 ​

3. 批注质量控制流程 ​

完整示例 ​

1. 基础批注管理 ​

2. 高级批注管理 ​

3. 批注质量控制 ​

注意事项 ​

错误处理 ​

最佳实践 ​

1. 批注管理最佳实践 ​

2. 批注质量控制最佳实践 ​

技术要点 ​

PDF插件自定义批注相关接口

概述

批注用户设置

SetAnnotateUser

批注操作方法

AddAnnotate

GetAnnotateCount

GetAnnotateObjFromIndex

RemoveAnnotateByIndex

RemoveAllAnnotate

批注数据管理

GetCustomAnnotatesData

PutCustomAnnotatesData

方法分类总结

使用流程

1. 基本批注管理流程

2. 高级批注管理流程

3. 批注质量控制流程

完整示例

1. 基础批注管理

2. 高级批注管理

3. 批注质量控制

注意事项

错误处理

最佳实践

1. 批注管理最佳实践

2. 批注质量控制最佳实践

技术要点