自定义通讯相关方法

概述

本节介绍软航OFFICE文档控件提供的自定义通讯相关方法，这些方法允许开发者实现基于HTTP协议的自定义通讯功能，包括GET请求、POST请求、Multi-Part请求以及HTTP头信息管理等功能。

HTTP请求方法

DoWebGet

语法：

javascript

DoWebGet(URL)

功能：
该函数对URL执行指定的Web Get请求。

参数：

名称	必选/可选	数据类型	说明
URL	必选	string	Get请求返回信息

返回值：
Get请求返回信息。

说明：
该函数对URL执行指定的Web Get请求。同样，该函数唯一的参数URL，可以是绝对或者相对当前网页的URL，返回值可以保存在一个变量中。可以用该函数实现自定义的基于HTTP协议的通讯协议。或者在不提交当前页面的情况下从服务器及时获取信息。

使用示例：

javascript

// 执行GET请求
function doWebGet() {
    try {
        // 基本GET请求
        var response = OCX_OBJ.DoWebGet("http://example.com/api/data");
        console.log("GET请求响应:", response);
        return response;
    } catch (error) {
        console.error("GET请求失败:", error.message);
        return "";
    }
}

// 执行相对URL的GET请求
function doWebGetRelative() {
    try {
        var response = OCX_OBJ.DoWebGet("./api/data");
        console.log("相对URL GET请求响应:", response);
        return response;
    } catch (error) {
        console.error("相对URL GET请求失败:", error.message);
        return "";
    }
}

// 执行带参数的GET请求
function doWebGetWithParams() {
    try {
        var url = "http://example.com/api/data?param1=value1&param2=value2";
        var response = OCX_OBJ.DoWebGet(url);
        console.log("带参数GET请求响应:", response);
        return response;
    } catch (error) {
        console.error("带参数GET请求失败:", error.message);
        return "";
    }
}

// 批量执行GET请求
function doMultipleWebGet() {
    try {
        var urls = [
            "http://example.com/api/data1",
            "http://example.com/api/data2",
            "http://example.com/api/data3"
        ];
        var responses = {};
        
        for (var i = 0; i < urls.length; i++) {
            responses["data" + (i + 1)] = OCX_OBJ.DoWebGet(urls[i]);
        }
        
        console.log("批量GET请求响应:", responses);
        return responses;
    } catch (error) {
        console.error("批量GET请求失败:", error.message);
        return {};
    }
}

DoWebExecute

语法：

javascript

DoWebExecute(URL, CPARA)

功能：
该函数对URL执行指定的Multi-Part请求。

参数：

名称	必选/可选	数据类型	说明
URL	必选	string	Post请求返回信息
CPARA	必选	string	参数字符串

返回值：
Post请求返回信息。

说明：
该函数对URL执行指定的Multi-Part请求。同样，该函数的参数URL，可以是绝对或者相对当前网页的URL，CPARA参数是"&"分隔的"F1=V1"类型的参数串。请参考SaveToURL函数的介绍中有关CPARA的部分。该函数的返回值可以保存在一个变量中。可以用该函数实现自定义的基于HTTP协议的通讯协议。或者在不提交当前页面的情况下更新服务器的信息。

注意： 该方法执行的是Multi-Part请求。

使用示例：

javascript

// 执行Multi-Part请求
function doWebExecute() {
    try {
        // 基本Multi-Part请求
        var params = "name=张三&age=25&department=技术部";
        var response = OCX_OBJ.DoWebExecute("http://example.com/api/submit", params);
        console.log("Multi-Part请求响应:", response);
        return response;
    } catch (error) {
        console.error("Multi-Part请求失败:", error.message);
        return "";
    }
}

// 执行带复杂参数的Multi-Part请求
function doWebExecuteComplex() {
    try {
        var params = "title=文档标题&content=文档内容&author=作者&date=2024-01-01";
        var response = OCX_OBJ.DoWebExecute("http://example.com/api/document", params);
        console.log("复杂参数Multi-Part请求响应:", response);
        return response;
    } catch (error) {
        console.error("复杂参数Multi-Part请求失败:", error.message);
        return "";
    }
}

// 执行文件上传Multi-Part请求
function doWebExecuteFileUpload() {
    try {
        var params = "filename=document.docx&filetype=application/vnd.openxmlformats-officedocument.wordprocessingml.document&action=upload";
        var response = OCX_OBJ.DoWebExecute("http://example.com/api/upload", params);
        console.log("文件上传Multi-Part请求响应:", response);
        return response;
    } catch (error) {
        console.error("文件上传Multi-Part请求失败:", error.message);
        return "";
    }
}

DoWebExecute2

语法：

javascript

DoWebExecute2(URL, CPARA)

功能：
该函数对URL执行指定的Web Post请求。

参数：

名称	必选/可选	数据类型	说明
URL	必选	string	Post请求返回信息
CPARA	必选	string	参数字符串

返回值：
Post请求返回信息。

说明：
该函数对URL执行指定的Web Post请求。同样，该函数的参数URL，可以是绝对或者相对当前网页的URL，CPARA参数是"&"分隔的"F1=V1"类型的参数串。请参考SaveToURL函数的介绍中有关CPARA的部分。该函数的返回值可以保存在一个变量中。可以用该函数实现自定义的基于HTTP协议的通讯协议。或者在不提交当前页面的情况下更新服务器的信息。

注意： 该方法执行的是普通POST请求。

使用示例：

javascript

// 执行POST请求
function doWebExecute2() {
    try {
        // 基本POST请求
        var params = "username=admin&password=123456&action=login";
        var response = OCX_OBJ.DoWebExecute2("http://example.com/api/login", params);
        console.log("POST请求响应:", response);
        return response;
    } catch (error) {
        console.error("POST请求失败:", error.message);
        return "";
    }
}

// 执行JSON数据POST请求
function doWebExecute2JSON() {
    try {
        var jsonData = JSON.stringify({
            "title": "文档标题",
            "content": "文档内容",
            "author": "作者"
        });
        var params = "data=" + encodeURIComponent(jsonData) + "&format=json";
        var response = OCX_OBJ.DoWebExecute2("http://example.com/api/save", params);
        console.log("JSON数据POST请求响应:", response);
        return response;
    } catch (error) {
        console.error("JSON数据POST请求失败:", error.message);
        return "";
    }
}

// 执行认证POST请求
function doWebExecute2Auth() {
    try {
        var params = "token=abc123&action=authenticate&timestamp=" + Date.now();
        var response = OCX_OBJ.DoWebExecute2("http://example.com/api/auth", params);
        console.log("认证POST请求响应:", response);
        return response;
    } catch (error) {
        console.error("认证POST请求失败:", error.message);
        return "";
    }
}

HTTP头信息管理

AddHTTPHeader

语法：

javascript

AddHTTPHeader(HeaderStr)

功能：
添加自定义的HTTP头信息。

参数：

名称	必选/可选	数据类型	说明
HeaderStr	必选	string	HTTP头字符串

返回值：
无返回值。

说明：
添加自定义的HTTP头信息。用于定制认证等。

使用示例：

javascript

// 添加HTTP头信息
function addHTTPHeader() {
    try {
        // 添加认证头
        OCX_OBJ.AddHTTPHeader("Authorization: Bearer abc123");
        console.log("认证头添加完成");
    } catch (error) {
        console.error("添加HTTP头失败:", error.message);
    }
}

// 添加多个HTTP头
function addMultipleHTTPHeaders() {
    try {
        // 添加认证头
        OCX_OBJ.AddHTTPHeader("Authorization: Bearer abc123");
        
        // 添加内容类型头
        OCX_OBJ.AddHTTPHeader("Content-Type: application/json");
        
        // 添加用户代理头
        OCX_OBJ.AddHTTPHeader("User-Agent: NTKO-Office-Control/1.0");
        
        console.log("多个HTTP头添加完成");
    } catch (error) {
        console.error("添加多个HTTP头失败:", error.message);
    }
}

// 添加自定义认证头
function addCustomAuthHeader() {
    try {
        // 添加API密钥头
        OCX_OBJ.AddHTTPHeader("X-API-Key: your-api-key-here");
        
        // 添加时间戳头
        OCX_OBJ.AddHTTPHeader("X-Timestamp: " + Date.now());
        
        // 添加签名头
        OCX_OBJ.AddHTTPHeader("X-Signature: your-signature-here");
        
        console.log("自定义认证头添加完成");
    } catch (error) {
        console.error("添加自定义认证头失败:", error.message);
    }
}

HTTPHeaderReset

语法：

javascript

HTTPHeaderReset()

功能：
清除已经自定义的所有HTTP头信息。

返回值：
无返回值。

说明：
清除已经自定义的所有HTTP头信息。用于定制认证等。

使用示例：

javascript

// 清除HTTP头信息
function httpHeaderReset() {
    try {
        OCX_OBJ.HTTPHeaderReset();
        console.log("HTTP头信息清除完成");
    } catch (error) {
        console.error("清除HTTP头信息失败:", error.message);
    }
}

// 重置并重新设置HTTP头
function resetAndSetHeaders() {
    try {
        // 清除现有头信息
        OCX_OBJ.HTTPHeaderReset();
        
        // 重新设置头信息
        OCX_OBJ.AddHTTPHeader("Authorization: Bearer new-token");
        OCX_OBJ.AddHTTPHeader("Content-Type: application/json");
        
        console.log("HTTP头信息重置并重新设置完成");
    } catch (error) {
        console.error("重置并设置HTTP头失败:", error.message);
    }
}

方法分类总结

分类	方法	功能	说明
HTTP请求	`DoWebGet`	执行Web Get请求	GET请求
	`DoWebExecute`	执行Multi-Part请求	Multi-Part请求
	`DoWebExecute2`	执行Web Post请求	POST请求
HTTP头管理	`AddHTTPHeader`	添加自定义HTTP头信息	头信息添加
	`HTTPHeaderReset`	清除所有HTTP头信息	头信息清除

使用流程

1. 基本HTTP通讯流程

javascript

// 基本HTTP通讯流程
function basicHTTPCommunication() {
    try {
        // 设置HTTP头
        OCX_OBJ.AddHTTPHeader("Authorization: Bearer token123");
        
        // 执行GET请求获取数据
        var data = OCX_OBJ.DoWebGet("http://example.com/api/data");
        console.log("获取的数据:", data);
        
        // 执行POST请求提交数据
        var params = "name=张三&age=25";
        var result = OCX_OBJ.DoWebExecute2("http://example.com/api/submit", params);
        console.log("提交结果:", result);
        
        console.log("基本HTTP通讯完成");
    } catch (error) {
        console.error("基本HTTP通讯失败:", error.message);
    }
}

2. 认证流程

javascript

// 认证流程
function authenticationFlow() {
    try {
        // 设置认证头
        OCX_OBJ.AddHTTPHeader("Authorization: Bearer token123");
        OCX_OBJ.AddHTTPHeader("Content-Type: application/json");
        
        // 执行认证请求
        var authParams = "username=admin&password=123456";
        var authResult = OCX_OBJ.DoWebExecute2("http://example.com/api/auth", authParams);
        console.log("认证结果:", authResult);
        
        // 执行需要认证的请求
        var protectedData = OCX_OBJ.DoWebGet("http://example.com/api/protected");
        console.log("受保护数据:", protectedData);
        
        console.log("认证流程完成");
    } catch (error) {
        console.error("认证流程失败:", error.message);
    }
}

3. 数据同步流程

javascript

// 数据同步流程
function dataSyncFlow() {
    try {
        // 设置同步头
        OCX_OBJ.AddHTTPHeader("X-Sync-Version: 1.0");
        OCX_OBJ.AddHTTPHeader("X-Client-ID: client123");
        
        // 获取服务器数据
        var serverData = OCX_OBJ.DoWebGet("http://example.com/api/sync");
        console.log("服务器数据:", serverData);
        
        // 同步本地数据到服务器
        var syncParams = "data=" + encodeURIComponent(JSON.stringify(localData));
        var syncResult = OCX_OBJ.DoWebExecute("http://example.com/api/sync", syncParams);
        console.log("同步结果:", syncResult);
        
        console.log("数据同步流程完成");
    } catch (error) {
        console.error("数据同步流程失败:", error.message);
    }
}

完整示例

1. 基础HTTP通讯

javascript

// 基础HTTP通讯示例
function basicHTTPExample() {
    try {
        // 执行GET请求
        var response = OCX_OBJ.DoWebGet("http://example.com/api/status");
        console.log("状态响应:", response);
        
        // 执行POST请求
        var params = "action=update&value=123";
        var result = OCX_OBJ.DoWebExecute2("http://example.com/api/update", params);
        console.log("更新结果:", result);
        
        console.log("基础HTTP通讯完成");
    } catch (error) {
        console.error("基础HTTP通讯失败:", error.message);
    }
}

2. 高级HTTP管理

javascript

// 高级HTTP管理示例
function advancedHTTPManagement() {
    try {
        // 设置多个HTTP头
        OCX_OBJ.AddHTTPHeader("Authorization: Bearer token123");
        OCX_OBJ.AddHTTPHeader("Content-Type: application/json");
        OCX_OBJ.AddHTTPHeader("X-API-Version: 2.0");
        
        // 执行多种类型的请求
        var getResponse = OCX_OBJ.DoWebGet("http://example.com/api/data");
        var postResponse = OCX_OBJ.DoWebExecute2("http://example.com/api/submit", "data=test");
        var multipartResponse = OCX_OBJ.DoWebExecute("http://example.com/api/upload", "file=document.docx");
        
        console.log("高级HTTP管理完成:", {
            get: getResponse,
            post: postResponse,
            multipart: multipartResponse
        });
    } catch (error) {
        console.error("高级HTTP管理失败:", error.message);
    }
}

3. HTTP通讯质量控制

javascript

// HTTP通讯质量控制示例
function httpCommunicationQualityControl() {
    try {
        // 设置质量控制头
        OCX_OBJ.AddHTTPHeader("X-Quality-Check: enabled");
        OCX_OBJ.AddHTTPHeader("X-Request-ID: " + Date.now());
        
        // 执行带质量控制的请求
        var qualityParams = "check=true&level=high&timestamp=" + Date.now();
        var qualityResult = OCX_OBJ.DoWebExecute2("http://example.com/api/quality", qualityParams);
        
        // 验证响应
        if (qualityResult && qualityResult.includes("success")) {
            console.log("质量控制通过:", qualityResult);
        } else {
            console.log("质量控制失败:", qualityResult);
        }
        
        console.log("HTTP通讯质量控制完成");
    } catch (error) {
        console.error("HTTP通讯质量控制失败:", error.message);
    }
}

注意事项

URL格式：支持绝对URL和相对URL
参数格式：CPARA参数使用"&"分隔的"F1=V1"格式
HTTP头管理：需要合理管理HTTP头信息
错误处理：实现完善的错误处理机制
安全性：注意保护敏感信息如认证令牌
性能优化：合理使用HTTP请求避免频繁调用
编码处理：注意URL编码和参数编码

错误处理

javascript

// HTTP通讯错误处理
function handleHTTPError(operation, error) {
    console.error("HTTP通讯失败:", operation, error.message);
    
    switch(operation) {
        case 'DoWebGet':
            console.log("GET请求失败，请检查:");
            console.log("1. URL是否正确");
            console.log("2. 网络连接是否正常");
            console.log("3. 服务器是否可访问");
            break;
        case 'DoWebExecute':
            console.log("Multi-Part请求失败，请检查:");
            console.log("1. URL是否正确");
            console.log("2. 参数格式是否正确");
            console.log("3. 服务器是否支持Multi-Part");
            break;
        case 'DoWebExecute2':
            console.log("POST请求失败，请检查:");
            console.log("1. URL是否正确");
            console.log("2. 参数格式是否正确");
            console.log("3. 服务器是否支持POST");
            break;
        case 'AddHTTPHeader':
            console.log("添加HTTP头失败，请检查:");
            console.log("1. 头信息格式是否正确");
            console.log("2. 头信息是否包含特殊字符");
            console.log("3. 头信息长度是否超限");
            break;
        default:
            console.log("未知HTTP通讯操作失败");
    }
}

最佳实践

1. HTTP通讯最佳实践

javascript

// HTTP通讯最佳实践
function httpCommunicationBestPractice() {
    try {
        // HTTP通讯配置
        var httpConfig = {
            baseUrl: "http://example.com/api",
            headers: {
                "Authorization": "Bearer token123",
                "Content-Type": "application/json",
                "User-Agent": "NTKO-Office-Control/1.0"
            },
            timeout: 30000
        };
        
        // 应用HTTP配置
        function applyHTTPConfig() {
            try {
                // 清除现有头信息
                OCX_OBJ.HTTPHeaderReset();
                
                // 添加配置的头信息
                for (var header in httpConfig.headers) {
                    OCX_OBJ.AddHTTPHeader(header + ": " + httpConfig.headers[header]);
                }
                
                console.log("HTTP配置应用成功");
            } catch (error) {
                console.error("应用HTTP配置失败:", error.message);
            }
        }
        
        // 执行HTTP通讯
        function executeHTTPCommunication() {
            try {
                // 执行GET请求
                var data = OCX_OBJ.DoWebGet(httpConfig.baseUrl + "/data");
                
                // 执行POST请求
                var params = "action=update&data=" + encodeURIComponent(JSON.stringify({test: "value"}));
                var result = OCX_OBJ.DoWebExecute2(httpConfig.baseUrl + "/update", params);
                
                console.log("HTTP通讯执行成功:", { data, result });
            } catch (error) {
                handleHTTPError('DoWebGet', error);
            }
        }
        
        // 应用配置并执行通讯
        applyHTTPConfig();
        executeHTTPCommunication();
        
    } catch (error) {
        console.error("HTTP通讯最佳实践失败:", error.message);
    }
}

2. HTTP管理最佳实践

javascript

// HTTP管理最佳实践
function httpManagementBestPractice() {
    try {
        // HTTP管理配置
        var httpManagementConfig = {
            authentication: {
                enabled: true,
                token: "bearer-token-123",
                refreshUrl: "http://example.com/api/refresh"
            },
            retry: {
                enabled: true,
                maxAttempts: 3,
                delay: 1000
            },
            monitoring: {
                enabled: true,
                logLevel: "info"
            }
        };
        
        // 应用HTTP管理配置
        function applyHTTPManagementConfig() {
            try {
                // 设置认证
                if (httpManagementConfig.authentication.enabled) {
                    OCX_OBJ.AddHTTPHeader("Authorization: " + httpManagementConfig.authentication.token);
                }
                
                // 设置监控头
                if (httpManagementConfig.monitoring.enabled) {
                    OCX_OBJ.AddHTTPHeader("X-Monitoring: enabled");
                    OCX_OBJ.AddHTTPHeader("X-Log-Level: " + httpManagementConfig.monitoring.logLevel);
                }
                
                console.log("HTTP管理配置应用成功");
            } catch (error) {
                console.error("应用HTTP管理配置失败:", error.message);
            }
        }
        
        // 应用配置
        applyHTTPManagementConfig();
        
    } catch (error) {
        console.error("HTTP管理最佳实践失败:", error.message);
    }
}

3. HTTP质量控制最佳实践

javascript

// HTTP质量控制最佳实践
function httpQualityControlBestPractice() {
    try {
        // HTTP质量控制
        function controlHTTPQuality() {
            try {
                // 设置质量控制头
                OCX_OBJ.AddHTTPHeader("X-Quality-Control: enabled");
                OCX_OBJ.AddHTTPHeader("X-Request-ID: " + Date.now());
                
                // 执行质量控制请求
                var qualityParams = "check=true&level=high&timestamp=" + Date.now();
                var qualityResult = OCX_OBJ.DoWebExecute2("http://example.com/api/quality", qualityParams);
                
                // 验证响应质量
                if (qualityResult && qualityResult.includes("success")) {
                    console.log("HTTP质量控制通过");
                    return true;
                } else {
                    console.log("HTTP质量控制失败");
                    return false;
                }
            } catch (error) {
                console.error("HTTP质量控制失败:", error.message);
                return false;
            }
        }
        
        // 执行质量控制
        var qualityResult = controlHTTPQuality();
        console.log("HTTP质量控制结果:", qualityResult);
        
    } catch (error) {
        console.error("HTTP质量控制最佳实践失败:", error.message);
    }
}

技术要点

URL格式：支持绝对URL和相对URL
参数格式：CPARA参数使用"&"分隔的"F1=V1"格式
HTTP头管理：需要合理管理HTTP头信息
错误处理：完善的错误处理机制
安全性：注意保护敏感信息
性能优化：合理使用HTTP请求
编码处理：注意URL编码和参数编码

总结

自定义通讯相关方法为软航OFFICE文档控件提供了强大的HTTP通讯功能。通过DoWebGet方法可以执行GET请求，通过DoWebExecute方法可以执行Multi-Part请求，通过DoWebExecute2方法可以执行POST请求，通过AddHTTPHeader方法可以添加自定义HTTP头信息，通过HTTPHeaderReset方法可以清除HTTP头信息，为开发者提供了灵活的自定义通讯接口，大大提升了控件的网络通讯能力和用户体验。

自定义通讯相关方法 ​

概述 ​

HTTP请求方法 ​

DoWebGet ​

DoWebExecute ​

DoWebExecute2 ​

HTTP头信息管理 ​

AddHTTPHeader ​

HTTPHeaderReset ​

方法分类总结 ​

使用流程 ​

1. 基本HTTP通讯流程 ​

2. 认证流程 ​

3. 数据同步流程 ​

完整示例 ​

1. 基础HTTP通讯 ​

2. 高级HTTP管理 ​

3. HTTP通讯质量控制 ​

注意事项 ​

错误处理 ​

最佳实践 ​

1. HTTP通讯最佳实践 ​

2. HTTP管理最佳实践 ​

3. HTTP质量控制最佳实践 ​

技术要点 ​

总结 ​

自定义通讯相关方法

概述

HTTP请求方法

DoWebGet

DoWebExecute

DoWebExecute2

HTTP头信息管理

AddHTTPHeader

HTTPHeaderReset

方法分类总结

使用流程

1. 基本HTTP通讯流程

2. 认证流程

3. 数据同步流程

完整示例

1. 基础HTTP通讯

2. 高级HTTP管理

3. HTTP通讯质量控制

注意事项

错误处理

最佳实践

1. HTTP通讯最佳实践

2. HTTP管理最佳实践

3. HTTP质量控制最佳实践

技术要点

总结