Skip to content

文档通用方法

概述

本节介绍软航OFFICE文档控件国产化版本文档通用方法,这些方法允许开发者控制文档状态、显示对话框、打印文档、获取版本信息等,为文档管理系统提供完整的通用功能。

文档保护方法

SetReadOnly

语法:

javascript
SetReadOnly(vbool, [password], [ProtectOption], [ProtectType])

功能:
设置文档为只读/可写。

参数:

名称必选/可选数据类型说明
vbool必选bool是否只读
password必选string保护密码
ProtectOption可选long保护选项
ProtectType可选long保护模式类型

返回值:
无返回值

说明:
设置文档为只读/可写,即文档保护,不可编辑的状态。

ProtectType参数说明:

模式说明
0修订启用保护模式后仅允许修订操作
1批注启用保护模式后仅允许批注操作
2填写窗体启用保护模式后仅允许填写窗体操作
3只读启用保护模式后仅允许只读操作

使用示例:

javascript
// 基本用法
var obj = OfficeControlObj;

// 设置文档为只读
obj.SetReadOnly(true, "123456");
console.log("文档已设置为只读");

// 设置文档为可写
obj.SetReadOnly(false, "123456");
console.log("文档已设置为可写");

// 设置文档为只读并指定保护类型
obj.SetReadOnly(true, "123456", 0, 3);
console.log("文档已设置为只读模式");

对话框显示方法

ShowDialog

语法:

javascript
ShowDialog(DlgType)

功能:
显示一个指定类型的对话框和用户交互。

参数:

名称必选/可选数据类型说明
DlgType必选ShowDialogType对话框类型

返回值:
无返回值

说明:
显示一个指定类型的对话框和用户交互,参数为对话框类型。

ShowDialogType参数说明:

对话框类型说明
0新建对象显示新建对象对话框
1打开显示打开文件对话框
2保存显示保存文件对话框
3另存为显示另存为对话框
4打印显示打印对话框
5页面设置显示页面设置对话框
6文件属性显示文件属性对话框

使用示例:

javascript
// 基本用法
var obj = OfficeControlObj;

// 显示打开对话框
obj.ShowDialog(1);
console.log("打开对话框已显示");

// 显示保存对话框
obj.ShowDialog(2);
console.log("保存对话框已显示");

// 显示打印对话框
obj.ShowDialog(4);
console.log("打印对话框已显示");

打印相关方法

PrintOut

语法:

javascript
PrintOut([PromptToSelectPrinter])

功能:
打印当前文档。

参数:

名称必选/可选数据类型说明
PromptToSelectPrinter可选bool是否选择打印机

返回值:
无返回值

说明:
打印当前文档。可选参数是是否提示用户选择打印机,缺省值为false,即不选择打印机,用当前默认打印机直接打印。

使用示例:

javascript
// 基本用法
var obj = OfficeControlObj;

// 使用默认打印机打印
obj.PrintOut();
console.log("文档已打印");

// 提示用户选择打印机
obj.PrintOut(true);
console.log("文档已打印并提示选择打印机");

PrintPreview

语法:

javascript
PrintPreview()

功能:
显示打印预览视图。

返回值:
无返回值

使用示例:

javascript
// 基本用法
var obj = OfficeControlObj;

// 显示打印预览
obj.PrintPreview();
console.log("打印预览已显示");

ExitPrintPreview

语法:

javascript
ExitPrintPreview()

功能:
退出打印预览视图。

返回值:
无返回值

使用示例:

javascript
// 基本用法
var obj = OfficeControlObj;

// 退出打印预览
obj.ExitPrintPreview();
console.log("打印预览已退出");

文档操作方法

Close

语法:

javascript
Close()

功能:
关闭当前文档。

返回值:
无返回值

使用示例:

javascript
// 基本用法
var obj = OfficeControlObj;

// 关闭当前文档
obj.Close();
console.log("文档已关闭");

版本信息方法

GetWPSVer

语法:

javascript
GetWPSVer()

功能:
获得客户机当前安装的WPS版本。

返回值:
数值型。返回值的含义如下:

版本说明
6WPS2005或者2007、2012WPS2005或者2007、2012版本
9WPS2013或者2016WPS2013或者2016版本
100错误本机没有安装WPS

使用示例:

javascript
// 基本用法
var obj = OfficeControlObj;

// 获取WPS版本
var wpsVersion = obj.GetWPSVer();
console.log("WPS版本:", wpsVersion);

// 根据版本执行不同操作
switch(wpsVersion) {
    case 6:
        console.log("WPS2005/2007/2012版本");
        break;
    case 9:
        console.log("WPS2013/2016版本");
        break;
    case 100:
        console.log("未安装WPS");
        break;
    default:
        console.log("未知WPS版本");
}

GetPluginVersion

语法:

javascript
GetPluginVersion()

功能:
获得客户机当前安装的文档控件版本。

返回值:
数值型。

使用示例:

javascript
// 基本用法
var obj = OfficeControlObj;

// 获取文档控件版本
var pluginVersion = obj.GetPluginVersion();
console.log("文档控件版本:", pluginVersion);

消息显示方法

ShowTipMessage

语法:

javascript
ShowTipMessage(Caption, Text, [isError])

功能:
显示一个模式对话框。

参数:

名称必选/可选数据类型说明
Caption必选string对话框的标题
Text必选string对话框的文本
isError可选bool是否是错误信息

返回值:
无返回值

说明:
显示一个模式对话框。当控件处于全屏状态时,ALERT的提示框无法显示出来,可以用本方法来作为弹出提示框。

使用示例:

javascript
// 基本用法
var obj = OfficeControlObj;

// 显示提示消息
obj.ShowTipMessage("提示", "操作成功完成");
console.log("提示消息已显示");

// 显示错误消息
obj.ShowTipMessage("错误", "操作失败", true);
console.log("错误消息已显示");

ShowConfirmMessage

语法:

javascript
ShowConfirmMessage(Caption, Text, [IsError], [IsTopMost])

功能:
弹出自定义的确认对话框。

参数:

名称必选/可选数据类型说明
Caption必选string对话框的标题
Text必选string对话框的文本
IsError可选bool是否是错误信息
IsTopMost可选bool对话框是否置顶

返回值:
布尔型。

说明:
该方法可以弹出一个自定义的确认对话框,并可以返回确定或取消的布尔值。开发人员可以通过返回值来做下一步的逻辑操作。

使用示例:

javascript
// 基本用法
var obj = OfficeControlObj;

// 显示确认对话框
var result = obj.ShowConfirmMessage("确认", "是否要保存文档?");
if (result) {
    console.log("用户点击了确定");
    // 执行保存操作
} else {
    console.log("用户点击了取消");
}

// 显示错误确认对话框
var result = obj.ShowConfirmMessage("错误", "文档保存失败,是否重试?", true, true);
if (result) {
    console.log("用户选择重试");
} else {
    console.log("用户选择取消");
}

ShowUIMessage

语法:

javascript
ShowUIMessage(bstrMes)

功能:
弹出自定义的齿轮转动进度信息对话框。

参数:

名称必选/可选数据类型说明
bstrMes必选string消息字符串

返回值:
无返回值

说明:
该方法需要结合CloseUIMessage方法使用。可以用在通过代码批量或长时间处理某项任务时弹出这个对话框,增强用户体验。

使用示例:

javascript
// 基本用法
var obj = OfficeControlObj;

// 显示进度消息
obj.ShowUIMessage("正在提交数据,请稍候");
console.log("进度消息已显示");

// 在长时间操作中使用
function longOperation() {
    obj.ShowUIMessage("正在处理文档,请稍候");
    
    // 执行长时间操作
    setTimeout(function() {
        obj.CloseUIMessage();
        console.log("操作完成");
    }, 3000);
}

CloseUIMessage

语法:

javascript
CloseUIMessage()

功能:
关闭自定义的齿轮转动进度信息对话框。

返回值:
无返回值

说明:
该方法需要结合ShowUIMessage方法使用。

使用示例:

javascript
// 基本用法
var obj = OfficeControlObj;

// 关闭进度消息
obj.CloseUIMessage();
console.log("进度消息已关闭");

授权文件管理方法

NtkoDownLoadCfgFile

语法:

javascript
NtkoDownLoadCfgFile(CfgFileUrl, IsShowUI)

功能:
从服务器上下载文档控件的授权文件,并替换本地的授权文件。

参数:

名称必选/可选数据类型说明
CfgFileUrl必选string授权文件的服务器地址
IsShowUI必选bool是否弹窗显示替换状态信息

返回值:
无返回值

说明:
此方法用于替换控件授权文件,如从带时间限制授权替换到正式授权场景。

注意: 此方法仅linux版文档控件2.1.0之后的版本可用。

使用示例:

javascript
// 基本用法
var obj = OfficeControlObj;

// 下载并替换授权文件
function downloadCfgFile() {
    if (obj.NtkoCfgFileID == "{A745D19F-0627-4CB9-97A7-E0441EB100FF}") {
        console.log("已成功替换授权文件");
    } else {
        console.log("尚未替换授权文件");
        obj.NtkoDownLoadCfgFile("http://192.168.0.171:1986/Demo/ntkocfgfile.dat", true);
    }
}

// 执行授权文件下载
downloadCfgFile();

界面操作方法

CapturePicAsTempFile

语法:

javascript
CapturePicAsTempFile()

功能:
对当前控件界面进行截屏并生成临时图片文件。

返回值:
String型字符串

说明:
本方法主要解决在一些UI框架下,需要弹出遮罩层信息窗口却被控件窗体挡住的情况。通过使用本方法,可以实现在弹出遮罩层前,先将控件界面截图,然后通过IMG标签将方法生成的临时文件在页面上显示出来,同时将控件大小置为1px,这样就可以避免控件挡住遮罩层的问题。

使用示例:

javascript
// 基本用法
var obj = OfficeControlObj;

// 截取控件界面
var tempFile = obj.CapturePicAsTempFile();
console.log("临时图片文件:", tempFile);

// 在弹出遮罩层前截取界面
function showOverlay() {
    // 截取控件界面
    var tempFile = obj.CapturePicAsTempFile();
    
    // 显示截取的图片
    var img = document.createElement('img');
    img.src = tempFile;
    img.style.position = 'absolute';
    img.style.top = '0';
    img.style.left = '0';
    img.style.zIndex = '1000';
    document.body.appendChild(img);
    
    // 将控件大小置为1px
    obj.style.width = '1px';
    obj.style.height = '1px';
    
    // 显示遮罩层
    showOverlayDialog();
}

水印操作方法

NtkoAddTextWaterMarkScreen

语法:

javascript
NtkoAddTextWaterMarkScreen(strValue, [ucolor], [urotate], [uFontSize], [strFontName], [ublend])

功能:
为文档控件添加窗口水印。

参数:

名称必选/可选数据类型说明
strValue必选string水印文字
ucolor可选long颜色索引值
urotate可选long字体倾斜度
uFontSize可选long字体大小
strFontName可选string字体类型
ublend可选long字体透明度

返回值:
布尔值

使用示例:

javascript
// 基本用法
var obj = OfficeControlObj;

// 添加水印
var result = obj.NtkoAddTextWaterMarkScreen("NTKO", 0xFF0000, 30, 16, "宋体", 100);
if (result) {
    console.log("水印添加成功");
} else {
    console.log("水印添加失败");
}

// 添加自定义水印
var result = obj.NtkoAddTextWaterMarkScreen("机密文档", 0x0000FF, 45, 20, "黑体", 80);
console.log("自定义水印添加结果:", result);

工具栏控制方法

NtkoSetToolBarsOption

语法:

javascript
NtkoSetToolBarsOption([uItem])

功能:
控制wps内置某个工具栏是否勾选。

参数:

名称必选/可选数据类型说明
uItem必选long工具栏序列号

返回值:
无返回值

说明:
本方法用于控制wps内置某个工具栏是否勾选。

工具栏序列号说明:

工具栏名称序列号
Standard(常用)1
Formatting(格式)2
Tables and Borders(表格和边框)3
Align(对象对齐)4
Reviewing (审阅)5

使用示例:

javascript
// 基本用法
var obj = OfficeControlObj;

// 控制常用工具栏
obj.NtkoSetToolBarsOption(1);
console.log("常用工具栏已控制");

// 控制格式工具栏
obj.NtkoSetToolBarsOption(2);
console.log("格式工具栏已控制");

// 控制审阅工具栏
obj.NtkoSetToolBarsOption(5);
console.log("审阅工具栏已控制");

方法分类总结

分类方法功能说明
文档保护SetReadOnly设置只读状态设置文档为只读/可写
对话框ShowDialog显示对话框显示指定类型的对话框
打印PrintOut打印文档打印当前文档
打印PrintPreview打印预览显示打印预览视图
打印ExitPrintPreview退出预览退出打印预览视图
文档操作Close关闭文档关闭当前文档
版本信息GetWPSVer获取WPS版本获得客户机当前安装的WPS版本
版本信息GetPluginVersion获取控件版本获得客户机当前安装的文档控件版本
消息显示ShowTipMessage显示提示消息显示一个模式对话框
消息显示ShowConfirmMessage显示确认消息弹出自定义的确认对话框
消息显示ShowUIMessage显示进度消息弹出自定义的齿轮转动进度信息对话框
消息显示CloseUIMessage关闭进度消息关闭自定义的齿轮转动进度信息对话框
授权管理NtkoDownLoadCfgFile下载授权文件从服务器上下载文档控件的授权文件
界面操作CapturePicAsTempFile截取界面对当前控件界面进行截屏并生成临时图片文件
水印操作NtkoAddTextWaterMarkScreen添加水印为文档控件添加窗口水印
工具栏控制NtkoSetToolBarsOption控制工具栏控制wps内置某个工具栏是否勾选

使用流程

1. 基本文档操作流程

javascript
// 基本文档操作流程
function basicDocumentOperation() {
    var obj = OfficeControlObj;
    
    // 设置文档保护
    function setDocumentProtection() {
        obj.SetReadOnly(true, "123456");
        console.log("文档保护已设置");
    }
    
    // 显示对话框
    function showDialog() {
        obj.ShowDialog(1); // 显示打开对话框
        console.log("对话框已显示");
    }
    
    // 打印文档
    function printDocument() {
        obj.PrintOut();
        console.log("文档已打印");
    }
    
    return {
        setDocumentProtection: setDocumentProtection,
        showDialog: showDialog,
        printDocument: printDocument
    };
}

2. 高级文档操作流程

javascript
// 高级文档操作流程
function advancedDocumentOperation() {
    var obj = OfficeControlObj;
    
    // 文档操作配置
    var documentConfig = {
        enableProtection: true,
        enablePrinting: true,
        enableDialogs: true,
        enableVersionCheck: true
    };
    
    // 应用文档操作配置
    function applyDocumentConfig() {
        try {
            if (documentConfig.enableProtection) {
                console.log("文档保护已启用");
            }
            
            if (documentConfig.enablePrinting) {
                console.log("打印功能已启用");
            }
            
            console.log("文档操作配置应用成功");
        } catch (error) {
            console.error("文档操作配置应用失败:", error);
        }
    }
    
    // 监控文档状态
    function monitorDocumentStatus() {
        var status = {
            wpsVersion: obj.GetWPSVer(),
            pluginVersion: obj.GetPluginVersion(),
            isProtected: false // 需要根据实际情况判断
        };
        
        console.log("文档状态监控:", status);
        return status;
    }
    
    return {
        applyDocumentConfig: applyDocumentConfig,
        monitorDocumentStatus: monitorDocumentStatus
    };
}

3. 文档操作质量控制流程

javascript
// 文档操作质量控制流程
function documentOperationQualityControl() {
    var obj = OfficeControlObj;
    
    // 文档操作质量控制
    function controlDocumentOperationQuality() {
        var documentQuality = {
            totalOperations: 0,
            successfulOperations: 0,
            failedOperations: 0,
            qualityScore: 0
        };
        
        // 检查版本信息
        var wpsVersion = obj.GetWPSVer();
        var pluginVersion = obj.GetPluginVersion();
        
        documentQuality.totalOperations = 2;
        
        if (wpsVersion !== 100) {
            documentQuality.successfulOperations++;
        } else {
            documentQuality.failedOperations++;
        }
        
        if (pluginVersion > 0) {
            documentQuality.successfulOperations++;
        } else {
            documentQuality.failedOperations++;
        }
        
        if (documentQuality.totalOperations > 0) {
            documentQuality.qualityScore = (documentQuality.successfulOperations / documentQuality.totalOperations) * 100;
        }
        
        console.log("文档操作质量控制:", documentQuality);
        return documentQuality;
    }
    
    // 执行质量控制
    var qualityResult = controlDocumentOperationQuality();
    console.log("文档操作质量控制结果:", qualityResult);
}

完整示例

1. 基础文档操作

javascript
// 基础文档操作示例
function basicDocumentOperation() {
    var obj = OfficeControlObj;
    
    // 设置文档保护
    function setDocumentProtection() {
        obj.SetReadOnly(true, "123456");
        console.log("文档保护已设置");
    }
    
    // 显示对话框
    function showDialog() {
        obj.ShowDialog(1);
        console.log("对话框已显示");
    }
    
    // 打印文档
    function printDocument() {
        obj.PrintOut();
        console.log("文档已打印");
    }
    
    return {
        setDocumentProtection: setDocumentProtection,
        showDialog: showDialog,
        printDocument: printDocument
    };
}

2. 高级文档操作

javascript
// 高级文档操作示例
function advancedDocumentOperation() {
    var obj = OfficeControlObj;
    
    // 文档操作配置
    var documentConfig = {
        enableProtection: true,
        enablePrinting: true,
        enableDialogs: true,
        enableVersionCheck: true
    };
    
    // 应用文档操作配置
    function applyDocumentConfig() {
        if (documentConfig.enableProtection) {
            console.log("文档保护已启用");
        }
        
        if (documentConfig.enablePrinting) {
            console.log("打印功能已启用");
        }
        
        console.log("文档操作配置应用完成");
    }
    
    // 监控文档状态
    function monitorDocumentStatus() {
        var status = {
            wpsVersion: obj.GetWPSVer(),
            pluginVersion: obj.GetPluginVersion(),
            isProtected: false
        };
        
        console.log("文档状态:", status);
        return status;
    }
    
    return {
        applyDocumentConfig: applyDocumentConfig,
        monitorDocumentStatus: monitorDocumentStatus
    };
}

3. 文档操作质量控制

javascript
// 文档操作质量控制示例
function documentOperationQualityControl() {
    var obj = OfficeControlObj;
    
    // 文档操作质量控制
    function controlDocumentOperationQuality() {
        var documentQuality = {
            totalOperations: 0,
            successfulOperations: 0,
            failedOperations: 0,
            qualityScore: 0
        };
        
        // 检查版本信息
        var wpsVersion = obj.GetWPSVer();
        var pluginVersion = obj.GetPluginVersion();
        
        documentQuality.totalOperations = 2;
        
        if (wpsVersion !== 100) {
            documentQuality.successfulOperations++;
        } else {
            documentQuality.failedOperations++;
        }
        
        if (pluginVersion > 0) {
            documentQuality.successfulOperations++;
        } else {
            documentQuality.failedOperations++;
        }
        
        if (documentQuality.totalOperations > 0) {
            documentQuality.qualityScore = (documentQuality.successfulOperations / documentQuality.totalOperations) * 100;
        }
        
        console.log("文档操作质量控制:", documentQuality);
        return documentQuality;
    }
    
    // 执行质量控制
    var qualityResult = controlDocumentOperationQuality();
    console.log("文档操作质量控制结果:", qualityResult);
}

注意事项

  1. 文档保护:设置文档保护时确保密码安全
  2. 对话框显示:确保对话框类型正确
  3. 打印操作:确保打印机可用
  4. 错误处理:实现完善的错误处理机制
  5. 性能考虑:避免频繁的操作
  6. 资源管理:及时清理不需要的资源
  7. 用户体验:确保操作不影响用户体验

错误处理

javascript
// 文档操作错误处理
function handleDocumentOperationError(operationType, error) {
    console.error("文档操作处理失败:", operationType, error.message);
    
    switch(operationType) {
        case 'SetReadOnly':
            console.log("设置只读状态失败,请检查:");
            console.log("1. 密码是否正确");
            console.log("2. 文档状态是否正常");
            console.log("3. 保护类型是否有效");
            break;
        case 'PrintOut':
            console.log("打印文档失败,请检查:");
            console.log("1. 打印机是否可用");
            console.log("2. 文档是否可打印");
            console.log("3. 打印设置是否正确");
            break;
        case 'ShowDialog':
            console.log("显示对话框失败,请检查:");
            console.log("1. 对话框类型是否正确");
            console.log("2. 控件状态是否正常");
            console.log("3. 用户权限是否足够");
            break;
        default:
            console.log("未知文档操作处理失败");
    }
}

最佳实践

1. 文档操作最佳实践

javascript
// 文档操作最佳实践
function documentOperationBestPractice() {
    // 文档操作配置
    var documentConfig = {
        enableLogging: true,
        enableValidation: true,
        enableErrorHandling: true,
        enableQualityControl: true
    };
    
    // 应用文档操作配置
    function applyDocumentConfig() {
        try {
            // 设置文档操作处理
            if (documentConfig.enableLogging) {
                console.log("文档操作日志已启用");
            }
            
            if (documentConfig.enableValidation) {
                console.log("文档操作验证已启用");
            }
            
            console.log("文档操作配置应用成功");
        } catch (error) {
            handleDocumentOperationError('applyDocumentConfig', error);
        }
    }
    
    // 应用配置
    applyDocumentConfig();
}

2. 文档操作质量控制最佳实践

javascript
// 文档操作质量控制最佳实践
function documentOperationQualityControlBestPractice() {
    // 文档操作质量控制
    function controlDocumentOperationQuality() {
        try {
            // 文档操作质量控制
            var documentQuality = {
                totalOperations: 0,
                successfulOperations: 0,
                failedOperations: 0,
                qualityScore: 0
            };
            
            // 计算质量分数
            if (documentQuality.totalOperations > 0) {
                documentQuality.qualityScore = (documentQuality.successfulOperations / documentQuality.totalOperations) * 100;
            }
            
            console.log("文档操作质量控制完成:", documentQuality);
            return documentQuality;
        } catch (error) {
            console.error("文档操作质量控制失败:", error.message);
            return null;
        }
    }
    
    // 执行质量控制
    var qualityResult = controlDocumentOperationQuality();
    console.log("文档操作质量控制结果:", qualityResult);
}

技术要点

  1. 文档保护:设置文档保护时确保密码安全
  2. 对话框显示:确保对话框类型正确
  3. 打印操作:确保打印机可用
  4. 错误处理:完善的错误处理机制
  5. 性能优化:避免频繁的操作
  6. 资源管理:及时清理不需要的资源
  7. 用户体验:确保操作不影响用户体验