软航科技文档中心

Appearance

图片操作相关方法 ​

从本地添加图片 ​

AddPicFromLocal ​

语法：

javascript
AddPicFromLocal(Filename, [PromptSelect], [IsFloat], [left], [top], [relative], [scale], [zorder], [IsDoOCR], [IsTransBackground])

功能：
用来从本地增加图片到Office文档。

参数：

名称必选/可选数据类型说明
Filename必选string本地图片文件路径
PromptSelect可选bool是否允许用户选择文件，缺省是true，允许选择
IsFloat可选bool是否浮动图片，缺省是true，代表浮动
left可选long插入图片的左边距
top可选long插入图片的上边距
relative可选long图片定位模式
scale可选long图片缩放值，默认100无缩放
zorder可选long图片相对文字位置
IsDoOCR可选bool是否识别图片文件
IsTransBackground可选bool白色背景是否透明，默认false

返回值：
无返回值

说明：
该函数用来从本地增加图片到Office文档。

参数说明：

  • Filename：本地图片文件路径
  • PromptSelect：是否允许用户选择文件，缺省是true，允许选择
  • IsFloat：是否浮动图片，缺省是true，代表浮动
  • left：缺省值是0；如果IsFloat为false，则在当前光标处插入。该参数不起作用。如果IsFloat为true，则指明插入的图片相对于当前段落左栏的位置，以磅为单位
  • top：缺省值是0；如果IsFloat为false，则在当前光标处插入。该参数不起作用。如果IsFloat为true，则指明插入的图片相对于当前段落顶部的位置，以磅为单位
  • relative：取值1-4。1：光标位置；2：页边距；3：页面距离 4：默认设置栏，段落（为兼容以前版本默认方式）
  • scale：图片缩放值，默认100无缩放
  • zorder：表示图片是置于文字的上方还是下方。0：下方；1：上方
  • IsDoOCR：是否识别图片文件
  • IsTransBackground：白色背景是否透明，默认false

使用示例：

javascript
// 从本地添加图片
OCX_OBJ.AddPicFromLocal(
    "", // 路径
    true, // 是否提示选择文件
    true, // 是否浮动图片
    0, // 如果是浮动图片，相对于左边的Left 单位磅
    0, // 如果是浮动图片，相对于当前段落Top
    1, // 当前光标处
    100, // 无缩放
    1 // 文字上方
);

// 指定文件路径添加图片
OCX_OBJ.AddPicFromLocal("C:\\images\\logo.png", false, true, 50, 100, 1, 80, 1);

从URL添加图片 ​

AddPicFromURL ​

语法：

javascript
AddPicFromURL(URL, [IsFloat], [left], [top], [relative], [scale], [zorder], [IsDoOCR], [IsTransBackground])

功能：
用来从URL增加图片到Office文档。

参数：

名称必选/可选数据类型说明
URL必选string图片URL地址
IsFloat可选bool是否浮动图片，缺省是true，代表浮动
left可选long插入图片的左边距
top可选long插入图片的上边距
relative可选long图片定位模式
scale可选long图片缩放值，默认100无缩放
zorder可选long图片相对文字位置
IsDoOCR可选bool是否识别图片文件
IsTransBackground可选bool白色背景是否透明，默认false

返回值：
无返回值

说明：
该函数用来从URL增加图片到Office文档。

参数说明：

  • URL：该URL返回的必须是Office支持的文件类型
  • IsFloat：是否浮动图片，缺省是true，代表浮动
  • left：缺省值是0；如果IsFloat为false，则在当前光标处插入。该参数不起作用。如果IsFloat为true，则指明插入的图片相对于当前段落左栏的位置，以磅为单位
  • top：缺省值是0；如果IsFloat为false，则在当前光标处插入。该参数不起作用。如果IsFloat为true，则指明插入的图片相对于当前段落顶部的位置，以磅为单位
  • relative：取值1-4。1：光标位置；2：页边距；3：页面距离 4：默认设置栏，段落（为兼容以前版本默认方式）
  • scale：图片缩放值，默认100无缩放
  • zorder：表示图片是置于文字的上方还是下方。0：下方；1：上方
  • IsDoOCR：是否识别图片文件
  • IsTransBackground：白色背景是否透明，默认false

使用示例：

javascript
// 从URL添加图片
OCX_OBJ.AddPicFromURL(
    "http://example.com/image.jpg", // URL 注意：URL必须返回Word支持的图片类型
    true, // 是否浮动图片
    0, // 如果是浮动图片，相对于左边的Left 单位磅
    0, // 如果是浮动图片，相对于当前段落Top
    1, // 当前光标处
    100, // 无缩放
    1 // 文字上方
);

// 指定URL添加图片
OCX_OBJ.AddPicFromURL("http://localhost/images/logo.png", true, 100, 50, 2, 80, 1);

从扫描仪添加图片 ​

AddPicFromScanner ​

语法：

javascript
AddPicFromScanner([IsDoOCR])

功能：
从扫描仪插入图片到当前光标位置。

参数：

名称必选/可选数据类型说明
IsDoOCR可选bool是否识别图片文件

返回值：
无返回值

说明：
从扫描仪插入图片到当前光标位置。

使用示例：

javascript
// 从扫描仪添加图片
OCX_OBJ.AddPicFromScanner();

// 从扫描仪添加图片并进行OCR识别
OCX_OBJ.AddPicFromScanner(true);

从本地添加多张图片 ​

AddMultiPicFromLocal ​

语法：

javascript
AddMultiPicFromLocal()

功能：
从本地插入多张图片。

返回值：
无返回值

说明：
从本地插入多张图片。方法执行后，会弹出文件对话框供用户选择。

使用示例：

javascript
// 从本地添加多张图片
OCX_OBJ.AddMultiPicFromLocal();

方法分类总结 ​

分类方法功能说明
本地图片AddPicFromLocal从本地添加图片从本地文件系统添加图片
AddMultiPicFromLocal从本地添加多张图片批量添加本地图片
网络图片AddPicFromURL从URL添加图片从网络地址添加图片
扫描仪AddPicFromScanner从扫描仪添加图片从扫描仪设备添加图片

使用流程 ​

1. 从本地添加图片 ​

javascript
// 从本地添加图片
function addLocalImage() {
    try {
        // 添加本地图片
        OCX_OBJ.AddPicFromLocal(
            "C:\\images\\logo.png", // 图片路径
            false, // 不提示选择文件
            true, // 浮动图片
            100, // 左边距
            50, // 上边距
            1, // 光标位置
            80, // 缩放80%
            1 // 文字上方
        );
        
        console.log("本地图片添加完成");
        
    } catch (error) {
        console.error("添加本地图片失败:", error.message);
    }
}

2. 从URL添加图片 ​

javascript
// 从URL添加图片
function addUrlImage() {
    try {
        // 添加网络图片
        OCX_OBJ.AddPicFromURL(
            "http://example.com/image.jpg", // 图片URL
            true, // 浮动图片
            0, // 左边距
            0, // 上边距
            1, // 光标位置
            100, // 无缩放
            1 // 文字上方
        );
        
        console.log("网络图片添加完成");
        
    } catch (error) {
        console.error("添加网络图片失败:", error.message);
    }
}

3. 从扫描仪添加图片 ​

javascript
// 从扫描仪添加图片
function addScannerImage() {
    try {
        // 从扫描仪添加图片
        OCX_OBJ.AddPicFromScanner(true); // 进行OCR识别
        
        console.log("扫描仪图片添加完成");
        
    } catch (error) {
        console.error("添加扫描仪图片失败:", error.message);
    }
}

完整示例 ​

1. 基础图片添加 ​

javascript
// 基础图片添加示例
function addBasicImages() {
    try {
        // 添加本地图片
        OCX_OBJ.AddPicFromLocal("C:\\images\\logo.png", false, true, 0, 0, 1, 100, 1);
        
        // 添加网络图片
        OCX_OBJ.AddPicFromURL("http://example.com/banner.jpg", true, 0, 0, 1, 100, 1);
        
        console.log("基础图片添加完成");
        
    } catch (error) {
        console.error("基础图片添加失败:", error.message);
    }
}

2. 高级图片管理 ​

javascript
// 高级图片管理示例
function addAdvancedImages() {
    try {
        // 添加带OCR识别的图片
        OCX_OBJ.AddPicFromLocal("C:\\images\\document.png", false, true, 0, 0, 1, 100, 1, true, false);
        
        // 添加透明背景图片
        OCX_OBJ.AddPicFromURL("http://example.com/transparent.png", true, 0, 0, 1, 100, 1, false, true);
        
        // 添加多张本地图片
        OCX_OBJ.AddMultiPicFromLocal();
        
        console.log("高级图片管理完成");
        
    } catch (error) {
        console.error("高级图片管理失败:", error.message);
    }
}

3. 图片定位和缩放 ​

javascript
// 图片定位和缩放示例
function addPositionedImages() {
    try {
        // 添加定位图片
        OCX_OBJ.AddPicFromLocal(
            "C:\\images\\watermark.png", // 图片路径
            false, // 不提示选择
            true, // 浮动图片
            200, // 左边距200磅
            100, // 上边距100磅
            2, // 页边距定位
            50, // 缩放50%
            0 // 文字下方
        );
        
        // 添加缩放图片
        OCX_OBJ.AddPicFromURL(
            "http://example.com/large.jpg", // 图片URL
            true, // 浮动图片
            0, // 左边距
            0, // 上边距
            1, // 光标位置
            25, // 缩放25%
            1 // 文字上方
        );
        
        console.log("图片定位和缩放完成");
        
    } catch (error) {
        console.error("图片定位和缩放失败:", error.message);
    }
}

图片定位模式说明 ​

Relative参数取值 ​

值说明用途
1光标位置在当前光标位置插入图片
2页边距相对于页边距定位
3页面距离相对于页面距离定位
4默认设置栏，段落为兼容以前版本默认方式

Zorder参数取值 ​

值说明效果
0下方图片在文字下方
1上方图片在文字上方

注意事项 ​

  1. 版本要求：此方法是增强版及以上版本所有
  2. 图片格式：支持Office支持的图片格式（JPG、PNG、GIF、BMP等）
  3. 文件路径：本地文件路径必须存在且可访问
  4. 网络图片：URL必须返回Office支持的图片类型
  5. 扫描仪：需要连接扫描仪设备
  6. OCR识别：需要安装OCR识别软件
  7. 图片定位：合理设置图片定位参数

错误处理 ​

javascript
// 图片操作错误处理
function handleImageError(operation, error) {
    console.error("图片操作失败:", operation, error.message);
    
    switch(operation) {
        case 'AddPicFromLocal':
            console.log("添加本地图片失败，请检查:");
            console.log("1. 文件路径是否正确");
            console.log("2. 文件是否存在");
            console.log("3. 文件格式是否支持");
            break;
        case 'AddPicFromURL':
            console.log("添加网络图片失败，请检查:");
            console.log("1. URL是否有效");
            console.log("2. 网络连接是否正常");
            console.log("3. 图片格式是否支持");
            break;
        case 'AddPicFromScanner':
            console.log("添加扫描仪图片失败，请检查:");
            console.log("1. 扫描仪是否连接");
            console.log("2. 扫描仪驱动是否安装");
            console.log("3. 扫描仪是否正常工作");
            break;
        case 'AddMultiPicFromLocal':
            console.log("添加多张图片失败，请检查:");
            console.log("1. 文件选择对话框是否正常");
            console.log("2. 选择的文件是否有效");
            console.log("3. 文件格式是否支持");
            break;
        default:
            console.log("未知图片操作失败");
    }
}

最佳实践 ​

1. 图片添加最佳实践 ​

javascript
// 图片添加最佳实践
function imageAddBestPractice() {
    try {
        // 检查文档状态
        if (OCX_OBJ.DocType === 0) {
            console.log("请先打开文档");
            return;
        }
        
        // 添加本地图片
        function addLocalImageWithErrorHandling() {
            try {
                OCX_OBJ.AddPicFromLocal(
                    "C:\\images\\logo.png",
                    false, // 不提示选择
                    true, // 浮动图片
                    0, // 左边距
                    0, // 上边距
                    1, // 光标位置
                    100, // 无缩放
                    1 // 文字上方
                );
                console.log("本地图片添加成功");
            } catch (error) {
                handleImageError('AddPicFromLocal', error);
            }
        }
        
        // 添加网络图片
        function addUrlImageWithErrorHandling() {
            try {
                OCX_OBJ.AddPicFromURL(
                    "http://example.com/image.jpg",
                    true, // 浮动图片
                    0, // 左边距
                    0, // 上边距
                    1, // 光标位置
                    100, // 无缩放
                    1 // 文字上方
                );
                console.log("网络图片添加成功");
            } catch (error) {
                handleImageError('AddPicFromURL', error);
            }
        }
        
        // 执行图片添加
        addLocalImageWithErrorHandling();
        addUrlImageWithErrorHandling();
        
    } catch (error) {
        console.error("图片添加最佳实践失败:", error.message);
    }
}

2. 图片管理最佳实践 ​

javascript
// 图片管理最佳实践
function imageManagementBestPractice() {
    try {
        // 图片添加配置
        var imageConfig = {
            localPath: "C:\\images\\",
            urlBase: "http://example.com/images/",
            defaultScale: 100,
            defaultZorder: 1,
            defaultRelative: 1
        };
        
        // 添加配置化图片
        function addConfiguredImage(type, filename, options) {
            try {
                var config = Object.assign({
                    scale: imageConfig.defaultScale,
                    zorder: imageConfig.defaultZorder,
                    relative: imageConfig.defaultRelative,
                    isFloat: true,
                    left: 0,
                    top: 0
                }, options);
                
                if (type === 'local') {
                    OCX_OBJ.AddPicFromLocal(
                        imageConfig.localPath + filename,
                        false,
                        config.isFloat,
                        config.left,
                        config.top,
                        config.relative,
                        config.scale,
                        config.zorder
                    );
                } else if (type === 'url') {
                    OCX_OBJ.AddPicFromURL(
                        imageConfig.urlBase + filename,
                        config.isFloat,
                        config.left,
                        config.top,
                        config.relative,
                        config.scale,
                        config.zorder
                    );
                }
                
                console.log("配置化图片添加成功:", filename);
                
            } catch (error) {
                console.error("配置化图片添加失败:", filename, error.message);
            }
        }
        
        // 使用配置化方法添加图片
        addConfiguredImage('local', 'logo.png', { scale: 80 });
        addConfiguredImage('url', 'banner.jpg', { scale: 120, zorder: 0 });
        
        console.log("图片管理最佳实践完成");
        
    } catch (error) {
        console.error("图片管理最佳实践失败:", error.message);
    }
}

3. 图片质量控制最佳实践 ​

javascript
// 图片质量控制最佳实践
function imageQualityBestPractice() {
    try {
        // 图片质量检查
        function checkImageQuality(imagePath) {
            // 检查文件是否存在
            if (!imagePath || imagePath === "") {
                console.log("图片路径不能为空");
                return false;
            }
            
            // 检查文件扩展名
            var validExtensions = ['.jpg', '.jpeg', '.png', '.gif', '.bmp', '.tiff'];
            var extension = imagePath.toLowerCase().substring(imagePath.lastIndexOf('.'));
            
            if (validExtensions.indexOf(extension) === -1) {
                console.log("不支持的图片格式:", extension);
                return false;
            }
            
            return true;
        }
        
        // 添加质量检查的图片
        function addQualityCheckedImage(imagePath, options) {
            if (checkImageQuality(imagePath)) {
                try {
                    OCX_OBJ.AddPicFromLocal(
                        imagePath,
                        false,
                        options.isFloat || true,
                        options.left || 0,
                        options.top || 0,
                        options.relative || 1,
                        options.scale || 100,
                        options.zorder || 1
                    );
                    console.log("质量检查通过，图片添加成功");
                } catch (error) {
                    console.error("图片添加失败:", error.message);
                }
            }
        }
        
        // 使用质量检查添加图片
        addQualityCheckedImage("C:\\images\\logo.png", {
            scale: 80,
            zorder: 1
        });
        
        console.log("图片质量控制最佳实践完成");
        
    } catch (error) {
        console.error("图片质量控制最佳实践失败:", error.message);
    }
}

技术要点 ​

  1. 版本兼容性：确保使用增强版及以上版本
  2. 图片格式支持：支持Office支持的图片格式
  3. 文件路径管理：正确处理本地和网络路径
  4. 图片定位：合理设置图片定位参数
  5. 缩放控制：合理设置图片缩放比例
  6. OCR识别：正确配置OCR识别功能
  7. 错误处理：完善的错误处理机制

总结 ​

图片操作相关方法为软航OFFICE文档控件提供了强大的图片管理能力。通过AddPicFromLocal方法可以从本地添加图片，通过AddPicFromURL方法可以从网络添加图片，通过AddPicFromScanner方法可以从扫描仪添加图片，通过AddMultiPicFromLocal方法可以批量添加本地图片，为开发者提供了灵活的图片管理功能，大大提升了控件的图片处理能力和用户体验。

Copyright © 2025 软航科技