Appearance
文档通用方法
概述
本节介绍软航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版本。
返回值:
数值型。返回值的含义如下:
值 | 版本 | 说明 |
---|---|---|
6 | WPS2005或者2007、2012 | WPS2005或者2007、2012版本 |
9 | WPS2013或者2016 | WPS2013或者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);
}
注意事项
- 文档保护:设置文档保护时确保密码安全
- 对话框显示:确保对话框类型正确
- 打印操作:确保打印机可用
- 错误处理:实现完善的错误处理机制
- 性能考虑:避免频繁的操作
- 资源管理:及时清理不需要的资源
- 用户体验:确保操作不影响用户体验
错误处理
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);
}
技术要点
- 文档保护:设置文档保护时确保密码安全
- 对话框显示:确保对话框类型正确
- 打印操作:确保打印机可用
- 错误处理:完善的错误处理机制
- 性能优化:避免频繁的操作
- 资源管理:及时清理不需要的资源
- 用户体验:确保操作不影响用户体验