在dolanmiu/docx项目中高效使用图片的完整指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00136/article/details/148508158

在dolanmiu/docx项目中高效使用图片的完整指南

docx Easily generate and modify .docx files with JS/TS with a nice declarative API. Works for Node and on the Browser. 项目地址: https://gitcode.com/gh_mirrors/do/docx

前言

在现代文档处理中，图片是不可或缺的元素。dolanmiu/docx项目提供了强大的图片处理能力，让开发者可以轻松地在Word文档中插入、定位和格式化图片。本文将全面介绍如何在项目中高效使用图片功能。

基础图片插入

创建图片实例

要在文档中添加图片，首先需要创建一个ImageRun实例。这是最基本的图片操作方式：

const image = new ImageRun({
    type: 'png',  // 图片类型：png/jpeg/jpg/bmp/gif
    data: fs.readFileSync("./path/to/image.png"),  // 图片数据缓冲区
    transformation: {
        width: 300,  // 宽度（单位：EMU）
        height: 200  // 高度（单位：EMU）
    }
});

将图片添加到文档

创建图片实例后，需要将其添加到段落中：

const doc = new Document({
    sections: [{
        children: [
            new Paragraph({
                children: [image]  // 将图片添加到段落
            })
        ]
    }]
});

图片定位方式

dolanmiu/docx支持两种主要的图片定位方式：

1. 内联图片（默认）

内联图片会像普通文本一样排列在文档流中，不与其他元素重叠。

// 默认即为内联图片
const inlineImage = new ImageRun({
    type: 'png',
    data: buffer,
    transformation: {
        width: 100,
        height: 100
    }
});

2. 浮动图片

浮动图片可以覆盖在文本上方，实现更灵活的布局：

const floatingImage = new ImageRun({
    type: 'png',
    data: buffer,
    transformation: {
        width: 200,
        height: 200
    },
    floating: {
        horizontalPosition: {
            offset: 1014400  // 水平偏移量
        },
        verticalPosition: {
            offset: 1014400  // 垂直偏移量
        }
    }
});

高级定位选项

相对定位

可以基于页面边距等参考点进行定位：

floating: {
    horizontalPosition: {
        relative: HorizontalPositionRelativeFrom.RIGHT_MARGIN,
        offset: 1014400
    },
    verticalPosition: {
        relative: VerticalPositionRelativeFrom.BOTTOM_MARGIN,
        offset: 1014400
    }
}

对齐方式

除了偏移量，还可以使用对齐方式：

floating: {
    horizontalPosition: {
        relative: HorizontalPositionRelativeFrom.PAGE,
        align: HorizontalPositionAlign.CENTER
    },
    verticalPosition: {
        relative: VerticalPositionRelativeFrom.PAGE,
        align: VerticalPositionAlign.CENTER
    }
}

文字环绕效果

浮动图片可以实现文字环绕效果：

floating: {
    wrap: {
        type: TextWrappingType.SQUARE,  // 环绕类型
        side: TextWrappingSide.BOTH_SIDES  // 环绕方向
    }
}

环绕类型选项：

NONE：无环绕
SQUARE：方形环绕
TIGHT：紧密环绕
TOP_AND_BOTTOM：上下环绕

边距设置

为图片添加边距，使文字不会紧贴图片：

floating: {
    margins: {
        top: 201440,
        bottom: 201440,
        left: 201440,
        right: 201440
    }
}

辅助文本

为图片添加描述性文本，增强可访问性：

altText: {
    title: "产品示意图",
    description: "展示最新产品的三维渲染图",
    name: "产品图1"
}

实际应用场景

1. 页眉页脚图片

const doc = new Document({
    headers: {
        default: new Header({
            children: [
                new Paragraph({
                    children: [
                        new ImageRun({
                            type: 'png',
                            data: fs.readFileSync("./logo.png"),
                            transformation: {
                                width: 100,
                                height: 50
                            }
                        })
                    ]
                })
            ]
        })
    }
});

2. 图文混排文档

const doc = new Document({
    sections: [{
        children: [
            new Paragraph({
                children: [
                    new ImageRun({
                        type: 'png',
                        data: fs.readFileSync("./chart.png"),
                        transformation: {
                            width: 400,
                            height: 300
                        },
                        floating: {
                            horizontalPosition: {
                                align: HorizontalPositionAlign.RIGHT
                            },
                            wrap: {
                                type: TextWrappingType.SQUARE,
                                side: TextWrappingSide.LEFT
                            }
                        }
                    }),
                    new TextRun({
                        text: "这里是围绕图片的说明文字..."
                    })
                ]
            })
        ]
    }]
});