跳转至

模板中图片占位符

本页面介绍如何在模板中使用图片占位符，包括锚点类型和边距配置。

基本用法

图片占位符

在模板中使用图片占位符语法：

{{image:logo}}
{{image:product_photo}}
{{image:chart_image}}

提供图片数据

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

with TemplateWorkbook("template.xlsx") as template:
    data = {
        "logo": "path/to/logo.png",
        "product_photo": "path/to/product.jpg",
        "chart_image": "path/to/chart.png"
    }

    template.render(data)
    template.save("output.xlsx")

# 修复格式，确保兼容性
fix_xlsx("output.xlsx")

锚点类型配置

OneCellAnchor（默认）

模板中的图片占位符默认使用OneCellAnchor锚点：

# 模板中的占位符 {{image:logo}}
# 渲染时会自动使用OneCellAnchor锚点
# 图片固定大小，适合传统Excel场景

TwoCellAnchor（vue-office兼容）

如果需要vue-office预览支持，可以在数据中指定锚点类型：

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

with TemplateWorkbook("template_with_options.xlsx") as template:
    # 获取工作表
    sheet = template.worksheets[0]

    # 渲染基本数据
    template.render({
        "title": "月度报告",
        "date": "2025-11-01"
    })

    # 手动插入图片并指定TwoCellAnchor
    from symphra_excel.images.image_processor import CellImageOptions

    options = CellImageOptions(
        anchor_type="twoCell",  # 指定TwoCellAnchor
        margin=8  # 8像素边距
    )

    sheet.insert_image_in_cell("logo.png", 'A1', options=options)

    template.save("output_vue_office.xlsx")

fix_xlsx("output_vue_office.xlsx")

边距设置

默认边距

模板中图片占位符默认使用8像素边距：

{{image:logo}}  # 8px边距（默认）
{{image:photo}}  # 8px边距（默认）

自定义边距

# 在模板渲染后调整边距
with TemplateWorkbook("template.xlsx") as template:
    # 渲染数据
    template.render(data)

    # 获取工作表并调整图片边距
    sheet = template.worksheets[0]

    # 使用不同边距
    options_compact = CellImageOptions(
        anchor_type="oneCell",
        margin=4  # 紧凑边距
    )

    options_loose = CellImageOptions(
        anchor_type="oneCell",
        margin=12  # 宽松边距
    )

    sheet.insert_image_in_cell("logo.png", 'A1', options=options_compact)
    sheet.insert_image_in_cell("photo.png", 'B3', options=options_loose)

    template.save("output_custom_margin.xlsx")

完整示例

示例1: 产品目录（推荐配置）

模板布局:

产品名称: {{name}}
{{image:product_image}}
价格: {{price}}
描述: {{description}}

渲染代码:

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

products = [
    {
        "name": "笔记本电脑",
        "product_image": "images/laptop.png",
        "price": 5000,
        "description": "高性能办公笔记本",
    },
    {
        "name": "鼠标",
        "product_image": "images/mouse.png",
        "price": 50,
        "description": "无线蓝牙鼠标",
    },
]

for idx, product in enumerate(products, start=1):
    with TemplateWorkbook("product_template.xlsx") as template:
        # 渲染基本数据
        template.render(product)

        # 获取工作表并设置图片锚点
        sheet = template.worksheets[0]
        options = CellImageOptions(
            anchor_type="oneCell",  # 默认OneCellAnchor
            margin=8  # 8像素边距
        )
        sheet.insert_image_in_cell(
            "images/laptop.png",
            'B2',
            options=options
        )

        template.save(f"product_{idx}.xlsx")

# 修复所有文件格式
for idx in range(1, len(products) + 1):
    fix_xlsx(f"product_{idx}.xlsx")

示例2: 报告封面（vue-office兼容）

模板:

{{image:company_logo}}

2024年度报告

{{company_name}}
{{date}}

数据:

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

data = {
    "company_logo": "assets/logo.png",
    "company_name": "ABC科技有限公司",
    "date": "2025-11-01",
}

with TemplateWorkbook("report_template.xlsx") as template:
    # 渲染基本数据
    template.render(data)

    # 获取工作表并插入图片
    sheet = template.worksheets[0]

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

    template.save("report_2025.xlsx")

fix_xlsx("report_2025.xlsx")

示例3: 混合锚点类型

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

with TemplateWorkbook("mixed_template.xlsx") as template:
    template.render(data)
    sheet = template.worksheets[0]

    # Logo使用OneCellAnchor（固定大小）
    logo_options = CellImageOptions(
        anchor_type="oneCell",
        margin=8
    )
    sheet.insert_image_in_cell("logo.png", 'A1', options=logo_options)

    # 图表使用TwoCellAnchor（随单元格变化）
    chart_options = CellImageOptions(
        anchor_type="twoCell",
        margin=8
    )
    sheet.insert_image_in_cell("chart.png", 'D1', options=chart_options)

    template.save("mixed_anchors.xlsx")

fix_xlsx("mixed_anchors.xlsx")

图片尺寸处理

自动适配

模板中的图片会根据单元格大小自动调整：

# 图片会自动适配到包含它的单元格大小
{{image:product_image}}  # 自动调整大小

手动控制尺寸

# 在模板渲染后调整尺寸
with TemplateWorkbook("template.xlsx") as template:
    template.render(data)
    sheet = template.worksheets[0]

    # 创建不同尺寸的选项
    small_options = CellImageOptions(
        anchor_type="oneCell",
        margin=4
    )
    large_options = CellImageOptions(
        anchor_type="oneCell",
        margin=12
    )

    sheet.insert_image_in_cell("small_logo.png", 'A1', options=small_options)
    sheet.insert_image_in_cell("large_banner.png", 'A3', options=large_options)

    template.save("sized_images.xlsx")

最佳实践

✅ 推荐做法

from symphra_excel import TemplateWorkbook
from symphra_excel.images.image_processor import CellImageOptions
from symphra_excel.utils.format_fix import fix_xlsx
import os

# 1. 检查图片文件存在
logo_path = "assets/logo.png"
if not os.path.exists(logo_path):
    raise FileNotFoundError(f"Logo文件不存在: {logo_path}")

# 2. 使用推荐的8px边距
options = CellImageOptions(
    anchor_type="oneCell",
    margin=8  # 推荐值
)

# 3. 保存后调用fix_xlsx
with TemplateWorkbook("template.xlsx") as template:
    template.render(data)
    sheet = template.worksheets[0]
    sheet.insert_image_in_cell(logo_path, 'A1', options=options)
    template.save("output.xlsx")

fix_xlsx("output.xlsx")

❌ 避免的做法

# 1. 图片路径不正确
data = {
    "logo": "wrong/path/logo.png",
}

# 2. 不调用fix_xlsx
wb.save("output.xlsx")  # 缺少 fix_xlsx(output.xlsx)

# 3. 使用无边距
options = CellImageOptions(margin=0)  # 可能压边框

# 4. 超大图片
# 可能导致内存问题

下一步

下一步