跳转至

插入图片

本页面介绍如何在Excel中插入图片，包括基础插入、锚点类型选择、图片优化等功能。

基础用法

在单元格中插入图片

from symphra_excel import Workbook
from symphra_excel.images.image_processor import CellImageOptions

wb = Workbook()
sheet = wb.create_worksheet("图片示例")

# 插入图片到B3单元格
sheet.insert_image_in_cell("logo.png", 'B3')

wb.save("with_image.xlsx")

锚点类型选择

OneCellAnchor锚点（默认）

图片固定大小，不会随单元格变化：

from symphra_excel import Workbook
from symphra_excel.images.image_processor import CellImageOptions

wb = Workbook()
sheet = wb.create_worksheet("图片示例")

# 使用默认OneCellAnchor（固定大小）
options = CellImageOptions(
    anchor_type="oneCell",  # 默认值
    margin=8  # 8像素边距
)
sheet.insert_image_in_cell("logo.png", 'B3', options=options)

wb.save("oneCell_example.xlsx")

TwoCellAnchor锚点（vue-office兼容）

图片随单元格大小变化：

wb = Workbook()
sheet = wb.create_worksheet("图片示例")

# 使用TwoCellAnchor（随单元格变化）
options = CellImageOptions(
    anchor_type="twoCell",  # 显式指定
    margin=8
)
sheet.insert_image_in_cell("logo.png", 'B3', options=options)

wb.save("twoCell_example.xlsx")

边距设置

控制图片与单元格边框的距离：

# 无边距（图片可能压边框）
options = CellImageOptions(
    anchor_type="oneCell",
    margin=0
)

# 紧凑边距
options = CellImageOptions(
    anchor_type="oneCell",
    margin=4  # 4像素
)

# 推荐边距
options = CellImageOptions(
    anchor_type="oneCell",
    margin=8  # 8像素
)

# 宽松边距
options = CellImageOptions(
    anchor_type="oneCell",
    margin=12  # 12像素
)

完整示例

示例1: 基础图片插入

from symphra_excel import Workbook
from symphra_excel.images.image_processor import CellImageOptions
from symphra_excel.utils.format_fix import fix_xlsx

wb = Workbook()
sheet = wb.create_worksheet("报表")

# 插入图片（默认使用OneCellAnchor，8px边距）
sheet.insert_image_in_cell("company_logo.png", 'A1')

# 添加标题
sheet.set_value("A3", "2024年度报告")

wb.save("report_basic.xlsx")
fix_xlsx("report_basic.xlsx")

示例2: 指定锚点类型和边距

wb = Workbook()
sheet = wb.create_worksheet("产品")

# 使用TwoCellAnchor（vue-office兼容）
options = CellImageOptions(
    anchor_type="twoCell",
    margin=8
)
sheet.insert_image_in_cell("product_image.png", 'B2', options=options)

# 添加产品信息
sheet.set_value("A1", "产品名称")
sheet.set_value("C1", "产品图片")

wb.save("product_sheet.xlsx")
fix_xlsx("product_sheet.xlsx")

示例3: 模板中使用图片

from symphra_excel import TemplateWorkbook
from symphra_excel.utils.format_fix import fix_xlsx

# 渲染带图片的模板
with TemplateWorkbook("template.xlsx") as twb:
    data = {
        "logo_path": "company_logo.png",
        "chart_path": "sales_chart.png"
    }

    twb.render(data)
    twb.save("filled_template.xlsx")

fix_xlsx("filled_template.xlsx")

示例4: 图片占位符

wb = Workbook()
sheet = wb.create_worksheet("报告")

# 添加占位符文本
sheet.set_value("A1", "Logo位置")
sheet.set_value("D1", "图表位置")

# 在指定位置插入图片
sheet.insert_image_in_cell("logo.png", 'A2',
    options=CellImageOptions(anchor_type="oneCell", margin=8))
sheet.insert_image_in_cell("chart.png", 'D2',
    options=CellImageOptions(anchor_type="twoCell", margin=8))

wb.save("report_placeholder.xlsx")
fix_xlsx("report_placeholder.xlsx")

锚点类型选择指南

OneCellAnchor（默认）适用场景

  • ✅ 传统桌面版Excel
  • ✅ 图片大小需要固定
  • ✅ 精确像素级控制
  • ✅ 兼容老版本应用
options = CellImageOptions(
    anchor_type="oneCell",  # 默认，可省略
    margin=8
)

TwoCellAnchor适用场景

  • ✅ vue-office/excel在线预览
  • ✅ Web应用中的Excel展示
  • ✅ 需要图片随单元格变化
  • ✅ 现代响应式应用
options = CellImageOptions(
    anchor_type="twoCell",
    margin=8
)

支持的图片格式

  • PNG (.png) - 推荐，支持透明背景
  • JPEG (.jpg, .jpeg) - 照片类图片
  • GIF (.gif) - 简单动画
  • BMP (.bmp) - 未压缩图片
  • WebP (.webp) - 现代格式

最佳实践

✅ 推荐做法

from symphra_excel.utils.format_fix import fix_xlsx

# 1. 使用推荐的8px边距
options = CellImageOptions(margin=8)

# 2. 保存后调用fix_xlsx修复
wb.save("output.xlsx")
fix_xlsx("output.xlsx")

# 3. 使用正确的API方法
sheet.insert_image_in_cell("logo.png", 'B3', options=options)

# 4. 检查文件存在
import os
if os.path.exists("logo.png"):
    sheet.insert_image_in_cell("logo.png", 'A1')

❌ 避免的做法

# 1. 不推荐无边距（可能压边框）
options = CellImageOptions(margin=0)

# 2. 不推荐超大图片
# 可能导致内存问题

# 3. 路径不正确
sheet.insert_image_in_cell("wrong_path.png", 'A1')

下一步