07 图片操作 - ZeroHawkeye/wordZero GitHub Wiki
图片操作
WordZero 提供了强大而灵活的图片操作功能，支持多种图片格式、位置控制、大小调整和文字环绕等特性。本章将详细介绍如何在Word文档中插入和管理图片。
📷 支持的图片格式
WordZero 支持以下常见的图片格式：
- PNG - 支持透明背景，适合图标和简单图形
- JPEG - 适合照片和复杂图像
- GIF - 支持动画，适合简单动画效果
// 图片格式常量
document.ImageFormatPNG
document.ImageFormatJPEG
document.ImageFormatGIF
🖼️ 基础图片插入
从文件添加图片
最简单的方式是从本地文件添加图片：
package main
import (
"log"
"github.com/ZeroHawkeye/wordZero/pkg/document"
)
func main() {
doc := document.New()
// 从文件添加图片
imageInfo, err := doc.AddImageFromFile("path/to/image.jpg", &document.ImageConfig{
Size: &document.ImageSize{
Width: 80.0, // 宽度80毫米
Height: 60.0, // 高度60毫米
},
AltText: "示例图片",
Title: "这是一张示例图片",
})
if err != nil {
log.Fatalf("添加图片失败: %v", err)
}
// 保存文档
err = doc.Save("with_image.docx")
if err != nil {
log.Fatalf("保存失败: %v", err)
}
}
从数据添加图片
也可以直接从字节数据添加图片：
// 假设 imageData 是图片的字节数据
imageInfo, err := doc.AddImageFromData(
imageData,
"image.png", // 文件名
document.ImageFormatPNG, // 图片格式
200, 150, // 原始宽度和高度（像素）
&document.ImageConfig{
Size: &document.ImageSize{
Width: 50.0, // 显示宽度（毫米）
Height: 37.5, // 显示高度（毫米）
},
},
)
📐 图片大小控制
指定精确尺寸
imageConfig := &document.ImageConfig{
Size: &document.ImageSize{
Width: 100.0, // 宽度100毫米
Height: 75.0, // 高度75毫米
},
}
保持长宽比
只设置一个维度，自动计算另一个维度：
imageConfig := &document.ImageConfig{
Size: &document.ImageSize{
Width: 80.0, // 只设置宽度
KeepAspectRatio: true, // 保持长宽比
},
}
动态调整大小
添加图片后可以动态调整大小：
// 创建新的尺寸
newSize := &document.ImageSize{
Width: 120.0,
Height: 90.0,
}
// 调整图片大小
err := doc.ResizeImage(imageInfo, newSize)
if err != nil {
log.Printf("调整大小失败: %v", err)
}
📍 图片位置控制
WordZero 支持三种图片位置模式：
嵌入式图片（默认）
嵌入式图片跟随文本流，在段落中的固定位置显示：
imageConfig := &document.ImageConfig{
Position: document.ImagePositionInline,
Alignment: document.AlignCenter, // 段落内居中
}
左浮动图片
图片浮动到页面左侧，文字在右侧环绕：
imageConfig := &document.ImageConfig{
Position: document.ImagePositionFloatLeft,
WrapText: document.ImageWrapSquare, // 四周环绕
}
右浮动图片
图片浮动到页面右侧，文字在左侧环绕：
imageConfig := &document.ImageConfig{
Position: document.ImagePositionFloatRight,
WrapText: document.ImageWrapTight, // 紧密环绕
}
位置偏移
可以为浮动图片设置精确的偏移量：
imageConfig := &document.ImageConfig{
Position: document.ImagePositionFloatRight,
OffsetX: 5.0, // 距离右边5毫米
OffsetY: 2.0, // 向下偏移2毫米
}
🔄 文字环绕模式
WordZero 支持多种文字环绕模式：
无环绕
imageConfig := &document.ImageConfig{
WrapText: document.ImageWrapNone,
}
四周环绕
文字在图片四周环绕：
imageConfig := &document.ImageConfig{
WrapText: document.ImageWrapSquare,
}
紧密环绕
文字紧贴图片轮廓环绕：
imageConfig := &document.ImageConfig{
WrapText: document.ImageWrapTight,
}
上下环绕
文字只在图片上方和下方显示：
imageConfig := &document.ImageConfig{
WrapText: document.ImageWrapTopAndBottom,
}
⚙️ 图片属性设置
可访问性属性
为图片设置替代文字和标题，提高文档的可访问性：
// 设置替代文字（Alt Text）
err := doc.SetImageAltText(imageInfo, "数据统计图表显示销售增长趋势")
// 设置图片标题
err := doc.SetImageTitle(imageInfo, "2023年第三季度销售数据分析")
动态属性修改
图片添加后可以动态修改各种属性：
// 修改位置
err := doc.SetImagePosition(imageInfo, document.ImagePositionFloatLeft, 3.0, 1.0)
// 修改文字环绕
err := doc.SetImageWrapText(imageInfo, document.ImageWrapTight)
// 修改对齐方式（仅对嵌入式图片有效）
err := doc.SetImageAlignment(imageInfo, document.AlignCenter)
📋 完整示例
以下是一个综合运用各种图片功能的完整示例：
package main
import (
"fmt"
"log"
"github.com/ZeroHawkeye/wordZero/pkg/document"
)
func main() {
// 创建新文档
doc := document.New()
// 添加文档标题
titlePara := doc.AddParagraph("图片功能演示文档")
titlePara.AddFormattedText("图片功能演示文档", &document.TextFormat{
Bold: true,
FontSize: 18,
})
doc.AddParagraph("本文档演示了WordZero的各种图片功能。")
// 1. 添加标题横幅图片（嵌入式，居中）
headerImage, err := doc.AddImageFromFile("images/header.jpg", &document.ImageConfig{
Size: &document.ImageSize{
Width: 150.0,
KeepAspectRatio: true,
},
Position: document.ImagePositionInline,
Alignment: document.AlignCenter,
AltText: "文档标题横幅",
Title: "WordZero图片功能演示横幅",
})
if err != nil {
log.Fatalf("添加标题图片失败: %v", err)
}
doc.AddParagraph("上方是文档的标题横幅图片，使用了嵌入式布局和居中对齐。")
// 2. 添加左浮动配图
_, err = doc.AddImageFromFile("images/chart.png", &document.ImageConfig{
Size: &document.ImageSize{
Width: 60.0,
Height: 45.0,
},
Position: document.ImagePositionFloatLeft,
WrapText: document.ImageWrapSquare,
AltText: "数据图表",
Title: "销售数据统计图表",
OffsetX: 2.0,
})
if err != nil {
log.Fatalf("添加左浮动图片失败: %v", err)
}
doc.AddParagraph("这段文字演示了左浮动图片的效果。左侧的图表使用了四周环绕模式，" +
"文字会自动在图片右侧和下方流动。这种布局在技术文档和报告中非常实用，" +
"可以有效利用页面空间，同时保持良好的阅读体验。图表显示了重要的业务数据，" +
"为文档内容提供了有力的数据支撑。")
// 3. 添加右浮动装饰图片
_, err = doc.AddImageFromFile("images/decoration.png", &document.ImageConfig{
Size: &document.ImageSize{
Width: 40.0,
Height: 30.0,
},
Position: document.ImagePositionFloatRight,
WrapText: document.ImageWrapTight,
AltText: "装饰图片",
Title: "页面装饰元素",
OffsetX: 1.5,
OffsetY: 0.5,
})
if err != nil {
log.Fatalf("添加右浮动图片失败: %v", err)
}
doc.AddParagraph("右侧的装饰图片使用了紧密环绕模式，文字会更贴近图片边缘。" +
"这种设置适合用于装饰性图片，可以创造更紧凑的布局效果。通过精确的偏移设置，" +
"可以实现专业级的排版效果。")
// 4. 动态调整图片属性
err = doc.SetImageAltText(headerImage, "WordZero功能展示的专业横幅图片")
if err != nil {
log.Printf("设置替代文字失败: %v", err)
}
// 5. 保存文档
err = doc.Save("image_demo.docx")
if err != nil {
log.Fatalf("保存文档失败: %v", err)
}
fmt.Println("图片演示文档创建成功！")
}
🎯 最佳实践
1. 图片大小优化
- 为网络传输优化图片文件大小
- 根据显示尺寸选择合适的分辨率
- PNG适合简单图形，JPEG适合照片
// 推荐的图片配置
imageConfig := &document.ImageConfig{
Size: &document.ImageSize{
Width: 80.0, // 根据页面布局设置合适大小
KeepAspectRatio: true, // 保持长宽比避免变形
},
AltText: "清晰描述图片内容", // 提供有意义的替代文字
}
2. 布局设计
- 嵌入式图片适合重要说明图
- 浮动图片适合辅助性内容
- 合理使用文字环绕提高空间利用率
// 标题图片使用嵌入式居中
titleImageConfig := &document.ImageConfig{
Position: document.ImagePositionInline,
Alignment: document.AlignCenter,
}
// 配图使用浮动布局
contentImageConfig := &document.ImageConfig{
Position: document.ImagePositionFloatLeft,
WrapText: document.ImageWrapSquare,
OffsetX: 2.0, // 适当的间距
}
3. 可访问性
- 始终提供有意义的替代文字
- 为复杂图片提供详细说明
- 使用标题属性提供额外信息
// 良好的可访问性设置
err := doc.SetImageAltText(imageInfo, "2023年第三季度销售数据柱状图，显示三个产品线的增长趋势")
err = doc.SetImageTitle(imageInfo, "产品A增长15%，产品B增长8%，产品C增长22%")
🔍 常见问题
图片不显示
- 检查图片文件路径是否正确
- 确认图片格式是否支持
- 验证图片文件是否损坏
布局异常
- 检查图片尺寸设置是否合理
- 确认文字环绕模式是否适当
- 调整偏移量避免重叠
性能问题
- 避免使用过大的图片文件
- 批量处理图片时考虑内存使用
- 合理设置图片显示尺寸
📚 相关功能
通过本章的学习，您已经掌握了WordZero图片操作的完整功能。合理运用这些特性，可以创建专业且美观的Word文档。