插入图像 - 动态图像指南

PDF4me 支持在生成的文档中动态插入图像，允许您使用来自数据源的徽标、照片、图表、示意图和其他视觉内容填充模板。图像可以通过公共渠道提供。 URLs 或者 Base64编码字符串。

图像语法要求

The image syntax must be placed inside a Text Box in Word for proper image population. Create a text box at the desired location in your template before adding image merge fields.

图像插入方法

PDF4me 支持两种向模板提供图像数据的方法：

方法一：公众形象 URL

使用公开可访问的图片 URLs 插入来自网络的图片。

句法：

<<image [imageUrl]>>

数据示例：

{
  "imageUrl": "https://public-url/image.png"
}

使用案例：

公司徽标托管在公共服务器上
来自电商平台的产品图片
在线生成和托管的图表和图形
公共资源图像

方法二： Base64 编码图像

使用插入图像 Base64图像文件的编码字符串表示形式。

句法：

<<image [imageBase64]>>

数据示例：

{
  "imageBase64": "iVBORw0KGgoAAAANSUhEUgAAAfQAAAH0CAYAAADL1t+KAAAACXBIWXMAABcSAAAXEgFnn9JSAACU6ElEQVR4nOz953tjR5bn+34jtoMn6D2ZSaaRL5lSmR5z5t5/+9xzZqZ7qktSeksmvfcG3mzsveO+2ACVUklKUspMksj1eZ7qqpZECCCZ+CEiVqyljDEGIYQQQlxr+rKfgBBCCCH+OAl0IYQQogtIoAshhBBdQAJdCCGE6AIS6EIIIUQXkEAXQggh..."
}

优势：

无需网络连接即可工作
安全可靠 - 无外部依赖
对图像数据的完全控制
适用于敏感文件

图像格式选项

使用格式设置开关控制图像在文本框中的显示方式。这些选项决定图像的大小和宽高比。

保持宽高比

句法： <<image [imageUrl] -keepRatio>>

行为：

保持文本框大小不变
调整图像大小以适应文本框边界
保持原始图像宽高比
如果宽高比不同，图像可能无法填满整个文本框。

最适合： 标志、图标和图像中必须避免失真。

适合身高

句法： <<image [imageUrl] -fitHeight>>

行为：

保持文本框宽度
调整文本框高度以匹配图像宽高比
图片完全填充文本框
文本框尺寸会根据图像大小而变化。

最适合： 灵活布局中的可变高度图像

合身宽度

句法： <<image [imageUrl] -fitWidth>>

行为：

保持文本框高度
调整文本框宽度以匹配图像宽高比
图片完全填充文本框
文本框宽度会根据图像进行调整

最适合： 横向横幅，固定高度的标题

尺码合适

句法： <<image [imageUrl] -fitSize>>

行为：

调整文本框尺寸以匹配图像大小
使用原始图像尺寸
图片以实际尺寸显示
文本框会根据图像尺寸自动调整大小

最适合： 何时需要精确保留原始图像尺寸

尺码有限

句法： <<image [imageUrl] -fitSizeLim>>

行为：

调整文本框大小以适应图像大小
不会超出原始文本框尺寸
如果图片较小，可以缩小文本框。
阻止文本框放大

最适合： 限制最大图像尺寸，同时允许较小的图像。

格式比较

格式选项	宽度	高度	宽高比	文本框大小
`-keepRatio`	固定的	固定的	保存完好	未改变
`-fitHeight`	固定的	多变的	保存完好	高度变化
`-fitWidth`	多变的	固定的	保存完好	宽度变化
`-fitSize`	多变的	多变的	保存完好	两者都发生了变化
`-fitSizeLim`	多变的	多变的	保存完好	受限

实际案例

示例 1：公司标志

模板：

[Create a text box in header]
<<image [companyLogo] -keepRatio>>

数据：

{
  "companyLogo": "https://company.com/images/logo.png"
}

示例 2：产品图片

模板：

<<foreach [product in products]>>
Product: <<[product.name]>>
[Text box:] <<image [product.imageUrl] -fitHeight>>
Price: $<<[product.price]>>

<</foreach>>

数据：

{
  "products": [
    {
      "name": "Laptop Pro",
      "imageUrl": "https://example.com/laptop.jpg",
      "price": "1299.99"
    },
    {
      "name": "Wireless Mouse",
      "imageUrl": "https://example.com/mouse.jpg",
      "price": "29.99"
    }
  ]
}

示例 3：签名图像（Base64）

模板：

Authorized Signature:
[Text box:] <<image [signatureBase64] -fitSizeLim>>

Name: <<[signatoryName]>>
Date: <<[signatureDate]:"dd.MM.yyyy">>

数据：

{
  "signatureBase64": "iVBORw0KGgoAAAANSUhEUgA...[truncated]",
  "signatoryName": "John Smith",
  "signatureDate": "2024/01/15"
}

表格中的图像

将图像插入与表格结构相结合，可以创建条理清晰的视觉演示文稿。

产品目录表

模板：

Product | Image | Price
<<foreach [item in catalog]>>
<<[item.name]>> | [Text box: <<image [item.imageUrl] -keepRatio>>] | $<<[item.price]>>
<</foreach>>

条件图像插入

仅当图像数据可用时才插入图像。

可选徽标示例

模板：

<<if [logoUrl != null]>>
[Text box:] <<image [logoUrl] -keepRatio>>
<</if>>

默认图像回退

模板：

<<if [productImage != null]>>
[Text box:] <<image [productImage] -fitHeight>>
<<else>>
[Text box:] <<image [defaultProductImage] -fitHeight>>
<</if>>

文档中的多张图片

从单个数据源生成包含多个动态图像的文档。

示例：带图表的报告

模板：

Sales Report - <<[reportMonth]:"MMMM yyyy">>

Revenue Chart:
[Text box:] <<image [revenueChartUrl] -fitWidth>>

Expense Chart:
[Text box:] <<image [expenseChartUrl] -fitWidth>>

Growth Chart:
[Text box:] <<image [growthChartUrl] -fitWidth>>

图像质量考量

图片最佳实践 URLs

使用 HTTPS - 安全的 URLs 防止安全警告
永恒的 URLs - 确保 URLs 保持可访问性
尺寸合适 - 使用尺寸适合输出的图像
格式兼容性 - 常用格式： PNG， JPG， GIF
CDN托管 使用可靠的内容分发网络

最佳实践 Base64 图片

优化文件大小 - 编码前先压缩图像
使用适当的分辨率 - 匹配预期的输出分辨率
考虑数据大小 - 大的 Base64 字符串会增加有效载荷大小
格式选择 - PNG 为了透明起见， JPG 用于拍照
编码质量 确保适当 Base64 编码

Word中的文本框设置

创建图像占位符

插入文本框：
- Word 功能区 → 插入 → 文本框
- 在所需位置绘制文本框
- 输入框中的“调整大小”以估算图像尺寸
配置文本框：
- 如果需要，可以移除文本框边框。
- 将文本框填充设置为“无填充”以使其透明
- 根据需要配置文本换行
添加图像语法：
- 点击文本框内部
- 类型图像合并字段语法
- 添加合适的格式选项

图片插入故障排除

常见问题

问题： 生成的文档中未显示图像。
解决方案： 请确认图片语法位于文本框内，而不是普通段落内。

问题： 图像出现失真
解决方案： 使用 -keepRatio 保持宽高比

问题： 图片过大或过小
解决方案： 调整文本框大小或使用合适的适应选项

问题： Base64 图片加载失败
解决方案： 核实 Base64 编码完整有效

问题： URL 图片无法加载
解决方案： 查看 URL 无障碍访问，确保 HTTPS验证图像格式

问题： 图片位置不正确
解决方案： 在 Word 模板中重新定位文本框

高级图像技术

响应式图像尺寸

对于可能需要以不同尺寸查看的文档：

[Large text box:] <<image [headerImage] -fitSizeLim>>

这样，图像可以根据需要缩小，但不会超出文本框的边界。

图片及说明文字

模板：

[Text box:] <<image [chartUrl] -fitWidth>>

Figure <<[$index + 1]>>: <<[chartTitle]>>
Source: <<[chartSource]>>

条件图像格式化

根据数据属性选择格式：

<<if [imageOrientation == "landscape"]>>
[Wide text box:] <<image [imageUrl] -fitWidth>>
<<else>>
[Tall text box:] <<image [imageUrl] -fitHeight>>
<</if>>

完整示例：产品资料

模板：

<<[productName]:caps>>

Product Image:
[Text box 300x300:] <<image [productImageUrl] -keepRatio>>

Specifications:
• Model: <<[modelNumber]>>
• Category: <<[category]>>
• Price: $<<[price]:"F2">>

Additional Images:
<<foreach [img in additionalImages]>>
[Text box 150x150:] <<image [img.url] -keepRatio>>
<<[img.caption]>>
<</foreach>>

Company Logo:
[Text box 200x60:] <<image [companyLogoBase64] -fitHeight>>

:::提示：图像优化

为了获得最佳效果，请在将图像添加到数据源之前对其进行优化。将图像调整到合适的尺寸并进行压缩，以在保持图像质量的前提下减小文件大小。

:::

:::警告：文本框要求

图片必须插入到 Word 模板的文本框中。在普通段落中使用图片语法将无法正确显示图片。请务必为每个动态图片位置创建一个文本框占位符。

:::

图像语法要求​

图像插入方法​

方法一：公众形象 URL​

方法二： Base64 编码图像​

图像格式选项​

保持宽高比​

适合身高​

合身宽度​

尺码合适​

尺码有限​

格式比较​

实际案例​

示例 1：公司标志​

示例 2：产品图片​

示例 3：签名图像（Base64）​

表格中的图像​

产品目录表​

条件图像插入​

可选徽标示例​

默认图像回退​

文档中的多张图片​

示例：带图表的报告​

图像质量考量​

图片最佳实践 URLs​

最佳实践 Base64 图片​

Word中的文本框设置​

创建图像占位符​

图片插入故障排除​

常见问题​

高级图像技术​

响应式图像尺寸​

图片及说明文字​

条件图像格式化​

完整示例：产品资料​

图像语法要求

图像插入方法

方法一：公众形象 URL

方法二： Base64 编码图像

图像格式选项

保持宽高比

适合身高

合身宽度

尺码合适

尺码有限

格式比较

实际案例

示例 1：公司标志

示例 2：产品图片

示例 3：签名图像（Base64）

表格中的图像

产品目录表

条件图像插入

可选徽标示例

默认图像回退

文档中的多张图片

示例：带图表的报告

图像质量考量

图片最佳实践 URLs

最佳实践 Base64 图片

Word中的文本框设置

创建图像占位符

图片插入故障排除

常见问题

高级图像技术

响应式图像尺寸

图片及说明文字

条件图像格式化

完整示例：产品资料