单元格内嵌图片

GcExcel Java 支持将图片直接嵌入工作表单元格中，功能与微软Excel原生能力类似。单元格内的图片会固定绑定在单元格上，单元格旁会显示图片图标以代表该单元格数据。图片会随单元格同步移动、调整大小或被删除。导出为PDF、HTML和图片格式时，单元格内的图片均可正常保留。

在单元格中添加图片

你可以通过IRange.setCellPicture方法将图片嵌入单元格。添加图片时，需创建包含图片数据及可选替代文本的CellPicture对象，再将该对象赋值给目标单元格即可。

替代文本可在筛选、排序等需要文本求值的功能中作为显示值使用。若未设置替代文本，系统会使用本地化默认值（英文为“Picture”、中文为“图片”、日文为“画像”、韩文为“그림”、德文为“Bild”）。你可调用CellPicture.setAltText方法自定义替代文本。

以下示例演示如何向单元格中添加带替代文本的图片。

// 创建新工作簿
Workbook workbook = new Workbook();
IWorksheet sheet = workbook.getActiveSheet();
try {    
// 从文件读取图片数据            
byte[] imageData = Files.readAllBytes(Paths.get("Picture1.png"));
    // 为单元格设置图片及替代文本            
sheet.getRange("A1").setCellPicture(new CellPicture(imageData, "连衣裙"));
    // 保存为Excel文件            
workbook.save("PictureinCell.xlsx");
} catch (IOException e) {    
throw new RuntimeException("加载图片资源出错", e);
}

运行效果如下图所示：

注意：当单元格包含内嵌图片时，IRange.setValue 会返回CalcError.Value，而IRange.getText 会返回空字符串。

从单元格中读取图片

可使用IRange.getCellPicture方法读取单元格中的图片。若单元格包含内嵌图片，该方法会返回CellPicture对象；若无图片则返回空值。该方法同时支持读取由IMAGE()函数生成的有效图片。

CellPicture.getImageData方法以字节数组形式返回图片二进制数据副本。支持的图片格式包括PNG、JPG、GIF、BMP和SVG。修改返回的字节数组，不会影响单元格中已存储的原图。

以下示例演示从单元格读取图片数据并保存为PNG文件。

// 创建新工作簿
Workbook workbook = new Workbook();
IWorksheet sheet = workbook.getActiveSheet();
try {    
// 从文件读取图片数据        
byte[] imageData = Files.readAllBytes(Paths.get("Picture1.png"));
    // 为单元格设置图片及替代文本        
sheet.getRange("A1").setCellPicture(new CellPicture(imageData, "连衣裙"));
    // 从单元格读取图片        
CellPicture picture = sheet.getRange("A1").getCellPicture();
    if (picture != null) {        
// 获取替代文本                
String altText = picture.getAltText();        
System.out.println("替代文本: " + altText);  // 输出：替代文本: 连衣裙                
// 获取图片二进制数据                
byte[] retrievedData = picture.getImageData();
        // 保存为文件                
Files.write(Paths.get("retrieved_picture.png"), retrievedData);    
}
} catch (IOException e) {    
throw new RuntimeException("加载图片资源出错", e);
}

修改替代文本

读取得到的CellPicture对象是单元格图片数据的副本，直接修改该对象不会自动更新单元格内容。若要修改单元格内的图片内容或替代文本，需新建或编辑CellPicture对象，再重新通过IRange.setCellPicture方法赋值回单元格。

以下示例演示修改单元格图片的替代文本。

// 创建新工作簿
Workbook workbook = new Workbook();
IWorksheet sheet = workbook.getActiveSheet();
try {    
// 从文件读取图片数据        
byte[] imageData = Files.readAllBytes(Paths.get("Picture1.png"));
    // 为单元格设置图片及替代文本        
sheet.getRange("A1").setCellPicture(new CellPicture(imageData, "连衣裙"));
    // 获取单元格现有图片对象        
CellPicture existingPicture = sheet.getRange("A1").getCellPicture();
    // 修改替代文本并重新赋值        
existingPicture.setAltText("带亮片的粉色连衣裙");    
sheet.getRange("A1").setCellPicture(existingPicture);
} catch (IOException e) {    
throw new RuntimeException("加载图片资源出错", e);
}
// 保存为Excel文件
workbook.save("ModifyPictureinCell.xlsx");

运行效果如下图所示：

从单元格中移除图片

可通过以下任意一种方式移除单元格中的图片，若作用于多单元格区域，会批量移除每个单元格内的图片：

使用IRange.clear() 或IRange.clearContents() 方法。IRange.clear() 会清除单元格格式和图片，而IRange.clearContents() 仅移除图片、保留单元格原有格式。
将IRange.setCellPicture 方法赋值为null。
调用IRange.setValue 为单元格设置任意值。

以下示例演示多种移除单元格图片的方式。

// 创建新工作簿
Workbook workbook = new Workbook();
IWorksheet sheet = workbook.getActiveSheet();
try {    
// 从文件读取图片数据        
byte[] imageData = Files.readAllBytes(Paths.get("Picture1.png"));
    // 为单元格设置图片及替代文本        
sheet.getRange("A1").setCellPicture(new CellPicture(imageData, "连衣裙"));
    // 方法1：使用ClearContents()移除图片        
sheet.getRange("A1").clearContents();
    // 方法2：将CellPicture设为null移除图片        
sheet.getRange("A1").setCellPicture(null);
    // 方法3：为单元格赋值覆盖移除图片        
sheet.getRange("A1").setValue("无图片");
    // 保存为Excel文件        
workbook.save("RemovePicture.xlsx");
} catch (IOException e) {    
throw new RuntimeException("加载图片资源出错", e);
}