如何通过Office.js替换Word文档图片并保留格式与布局？

阿华AIGC实验室

2026-6-13

问题描述

开发基于Office.js的Word加载项（后端ASP.NET Core，前端Angular），需向Word文档模板的内容控件填充数据（含图片）。因Office.js暂不支持Picture Content Controls，改用Rich Text Content Controls作为图片占位方案，但遇到以下问题：

替换Rich Text Content Controls内的嵌入式图片后，布局混乱（图片丢失格式、位置偏移、尺寸调整错误）
将控件包裹在文本框中维持布局时，无法继承原图片的边框、样式、裁剪形状、旋转等属性

已尝试方案

使用Rich Text Content Controls作为图片占位符
通过insertInlinePictureFromBase64()替换嵌入式图片
用文本框包裹控件辅助维持布局
未找到替换后保留原图片格式的有效方法

解决方案与最佳实践

方案1：提取原图片格式属性后复用

核心思路是先获取原占位图片的所有格式参数，插入新图片后将这些参数逐一应用，确保样式与布局一致。

代码示例（Office.js + TypeScript）

async function replacePictureInRichTextControl(controlTitle: string, base64Image: string) {
  await Word.run(async (context) => {
    // 定位目标富文本内容控件
    const controls = context.document.contentControls.getByTitle(controlTitle);
    controls.load('items');
    await context.sync();

    if (controls.items.length === 0) {
      throw new Error(`未找到标题为${controlTitle}的内容控件`);
    }

    const richTextControl = controls.items[0];
    // 获取控件内的嵌入式图片
    const inlinePictures = richTextControl.inlinePictures;
    inlinePictures.load('items');
    await context.sync();

    if (inlinePictures.items.length === 0) {
      throw new Error(`控件内未找到占位图片`);
    }

    const originalPic = inlinePictures.items[0];
    // 提取原图片关键格式属性
    originalPic.load([
      'width', 'height', 'rotation', 
      'border', 'cropTop', 'cropBottom', 'cropLeft', 'cropRight',
      'lockAspectRatio'
    ]);
    await context.sync();

    // 保存属性到变量
    const picProps = {
      width: originalPic.width,
      height: originalPic.height,
      rotation: originalPic.rotation,
      border: {
        type: originalPic.border.type,
        color: originalPic.border.color,
        lineWidth: originalPic.border.lineWidth
      },
      cropTop: originalPic.cropTop,
      cropBottom: originalPic.cropBottom,
      cropLeft: originalPic.cropLeft,
      cropRight: originalPic.cropRight,
      lockAspectRatio: originalPic.lockAspectRatio
    };

    // 删除原图片
    originalPic.delete();
    await context.sync();

    // 插入新图片并应用原属性
    const newPic = richTextControl.insertInlinePictureFromBase64(base64Image, Word.InsertLocation.end);
    newPic.width = picProps.width;
    newPic.height = picProps.height;
    newPic.rotation = picProps.rotation;
    newPic.border.type = picProps.border.type;
    newPic.border.color = picProps.border.color;
    newPic.border.lineWidth = picProps.border.lineWidth;
    newPic.cropTop = picProps.cropTop;
    newPic.cropBottom = picProps.cropBottom;
    newPic.cropLeft = picProps.cropLeft;
    newPic.cropRight = picProps.cropRight;
    newPic.lockAspectRatio = picProps.lockAspectRatio;

    await context.sync();
  });
}

方案2：浮动图片+隐藏内容控件标记

若嵌入式图片布局限制过多，可改用浮动图片配合隐藏内容控件作为定位标记，避免文本框带来的复杂度：

在模板中插入浮动图片并设置好所有目标格式（边框、裁剪、旋转等）
在图片旁插入隐藏的Rich Text Content Controls（设置appearance: 'hidden'）作为唯一标识
替换时通过隐藏控件定位到附近的浮动图片，提取格式属性后替换并应用

代码示例片段

async function replaceFloatingPicture(markerControlTitle: string, base64Image: string) {
  await Word.run(async (context) => {
    const markerControls = context.document.contentControls.getByTitle(markerControlTitle);
    markerControls.load('items');
    await context.sync();

    if (markerControls.items.length === 0) return;

    const marker = markerControls.items[0];
    const paragraph = marker.parentParagraph;
    // 获取段落内的浮动图片
    const floatingPics = paragraph.floatingPictures;
    floatingPics.load('items');
    await context.sync();

    if (floatingPics.items.length === 0) return;

    const originalPic = floatingPics.items[0];
    originalPic.load([
      'width', 'height', 'rotation', 'border', 
      'cropTop', 'cropBottom', 'cropLeft', 'cropRight',
      'horizontalAlignment', 'verticalAlignment'
    ]);
    await context.sync();

    // 保存属性
    const props = {
      width: originalPic.width,
      height: originalPic.height,
      rotation: originalPic.rotation,
      border: {...originalPic.border},
      cropTop: originalPic.cropTop,
      cropBottom: originalPic.cropBottom,
      cropLeft: originalPic.cropLeft,
      cropRight: originalPic.cropRight,
      horizontalAlignment: originalPic.horizontalAlignment,
      verticalAlignment: originalPic.verticalAlignment
    };

    // 删除原浮动图片
    originalPic.delete();
    await context.sync();

    // 插入新浮动图片并应用属性
    const newPic = paragraph.insertFloatingPictureFromBase64(base64Image, Word.InsertLocation.end);
    Object.assign(newPic, props);

    await context.sync();
  });
}