DOCX
图片
在文档中插入图片，支持缩放、旋转、裁剪和浮动定位
使用 { image: {...} } 在段落中嵌入图片。支持 JPG、PNG、GIF、BMP、SVG 等格式。
data 字段接受原始字节（Uint8Array、ArrayBuffer、Buffer），也支持 base64 data URL（如 data:image/png;base64,...）。在 JSON 或浏览器环境中没有磁盘文件时，使用 data URL 最为方便。
基本图片
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
{
"image": {
"type": "png",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAoAAAAFoCAIAAABIUN0GAAAGFklEQVR4nO3OMQ3AQBAEseOPJwDD4rcYSwbgu/sAgOf2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAoP0AAIL2AwAI2g8AIGg/AICg/QAAgvYDAAjaDwAgaD8AgKD9AACC9gMACNoPACBoPwCAnB/XZ/UJD/Bi1wAAAABJRU5ErkJggg==",
"transformation": { "width": "5.3cm", "height": "4.0cm" }
}
}
]
}
}
]
}
]
}
import { readFileSync } from "node:fs";
const imageBuffer = readFileSync("photo.png");
{
children: [
{
paragraph: {
children: [
{
image: {
type: "png",
data: imageBuffer,
transformation: { width: "5.3cm", height: "4.0cm" },
},
},
],
},
},
],
}
变换
控制尺寸、旋转和翻转：
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
{
"image": {
"type": "jpg",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"transformation": {
"width": "7.9cm",
"height": "5.3cm",
"rotation": 45,
"flip": { "horizontal": true }
}
}
}
]
}
}
]
}
]
}
{
image: {
type: "jpg",
data: imageBuffer,
width: "7.9cm",
height: "5.3cm",
rotation: 45, // 旋转 45 度
flip: {
horizontal: true, // 水平翻转
},
},
}
裁剪
使用 srcRect 裁剪源图片：
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
{
"image": {
"type": "png",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"transformation": { "width": "5.3cm", "height": "5.3cm" },
"srcRect": { "left": 1000, "top": 1000, "right": 1000, "bottom": 1000 }
}
}
]
}
}
]
}
]
}
{
image: {
type: "png",
data: imageBuffer,
width: "5.3cm",
height: "5.3cm",
srcRect: {
left: 1000, // 裁剪左边缘（EMU 单位）
top: 1000, // 裁剪上边缘（EMU 单位）
right: 1000, // 裁剪右边缘（EMU 单位）
bottom: 1000, // 裁剪下边缘（EMU 单位）
},
},
}
浮动图片
使用 floating 选项进行带文字环绕的图片定位：
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
{
"image": {
"type": "png",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"transformation": { "width": "4.0cm", "height": "4.0cm" },
"floating": {
"horizontalPosition": { "offset": 720000 },
"verticalPosition": { "offset": 720000 },
"wrap": { "type": "square" }
}
}
}
]
}
}
]
}
]
}
{
image: {
type: "png",
data: imageBuffer,
width: "4.0cm",
height: "4.0cm",
floating: {
horizontalPosition: {
offset: 720000, // 距页面左侧的位置（EMU 单位）
},
verticalPosition: {
offset: 720000, // 距页面顶部的位置（EMU 单位）
},
wrap: {
type: "square", // 文字环绕图片
},
},
},
}
图片效果（Blip Effects）
使用 blipEffects 直接对图片应用调整效果：
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
{
"image": {
"type": "jpg",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"transformation": { "width": "4.0cm", "height": "4.0cm" },
"blipEffects": { "luminance": { "bright": 30, "contrast": -20 } }
}
}
]
}
}
]
}
]
}
{
image: {
type: "jpg",
data: imageBuffer,
width: "4.0cm",
height: "4.0cm",
blipEffects: {
// 亮度 +30%，对比度 -20%
luminance: { bright: 30, contrast: -20 },
},
},
}
可用的图片效果
| 属性 | 类型 | 说明 |
|---|---|---|
grayscale | boolean | 转为灰度图 |
luminance | { bright?, contrast? } | 调整亮度/对比度（百分比） |
hsl | { hue?, saturation?, luminance? } | 调整 HSL 颜色值 |
tint | { hue?, amount? } | 应用着色 |
duotone | { color1, color2 } | 双色调映射 |
biLevel | { threshold } | 黑白阈值（0-100） |
灰度
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
{
"image": {
"type": "jpg",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"transformation": { "width": "4.0cm", "height": "4.0cm" },
"blipEffects": { "grayscale": true }
}
}
]
}
}
]
}
]
}
{
image: {
type: "jpg",
data: imageBuffer,
transformation: { width: "4.0cm", height: "4.0cm" },
blipEffects: { grayscale: true },
},
}
双色调
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
{
"image": {
"type": "jpg",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"transformation": { "width": "4.0cm", "height": "4.0cm" },
"blipEffects": {
"duotone": { "color1": { "value": "002060" }, "color2": { "value": "D0CECE" } }
}
}
}
]
}
}
]
}
]
}
{
image: {
type: "jpg",
data: imageBuffer,
width: "4.0cm",
height: "4.0cm",
blipEffects: {
duotone: {
color1: { value: "002060" },
color2: { value: "D0CECE" },
},
},
},
}
着色
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
{
"image": {
"type": "jpg",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"transformation": { "width": "4.0cm", "height": "4.0cm" },
"blipEffects": { "tint": { "hue": 6000000, "amount": 40 } }
}
}
]
}
}
]
}
]
}
{
image: {
type: "jpg",
data: imageBuffer,
width: "4.0cm",
height: "4.0cm",
blipEffects: {
tint: { hue: 6000000, amount: 40 },
},
},
}
SVG 带回退
{
"sections": [
{
"children": [
{
"paragraph": {
"children": [
{
"image": {
"type": "svg",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"transformation": { "width": "5.3cm", "height": "5.3cm" },
"fallback": {
"type": "png",
"data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
}
}
}
]
}
}
]
}
]
}
{
image: {
type: "svg",
data: svgBuffer,
width: "5.3cm",
height: "5.3cm",
fallback: {
type: "png",
data: pngBuffer,
},
},
}