Adopt image fix from upstream PR #2876 (Issue #1804)

[protobi-pieter]

Source

Adopt PR exceljs#2876 from exceljs#2876
Also implemented in: https://github.com/Catscratch/exceljs (commit a55ca28)

Problem

When adding the same image multiple times non-consecutively, ExcelJS adds the wrong image reference.

Example:

const img1 = wb.addImage({ filename: 'image1.png', extension: 'PNG' });
const img2 = wb.addImage({ filename: 'image2.jpg', extension: 'JPEG' });

ws.addImage(img2, 'A1:A1');  // Image 2 ✅
ws.addImage(img1, 'A3:A3');  // Image 1 ✅
ws.addImage(img1, 'A5:A5');  // Should be Image 1, but becomes Image 2! ❌

Root Cause

In lib/xlsx/xform/sheet/worksheet-xform.js, the code only tracks preImageId but not the corresponding relationship ID (rIdImage). When the same image is reused after another image, the relationship ID lookup fails.

Solution

PR exceljs#2876 fixes this by:

1. Adding preRIdImage to track the relationship ID alongside preImageId
2. Using this.preRIdImage when the same image ID is detected
3. Storing both preImageId and preRIdImage for next iteration

Changes:

// Before:
let rIdImage = this.preImageId === medium.imageId ? 
  drawingRelsHash[medium.imageId] : 
  drawingRelsHash[drawing.rels.length];

// After:
let rIdImage = this.preImageId === medium.imageId ? 
  this.preRIdImage : 
  drawingRelsHash[drawing.rels.length];

// And store it:
this.preRIdImage = rIdImage;

Benefits

• ✅ Fixes incorrect image references when reusing images
• ✅ Maintains correct relationship IDs in OOXML
• ✅ Enables proper image caching/reuse patterns
• ✅ Has comprehensive test coverage

Attribution

Original PR author: wwwxy80s (@wwwxy80s)

• PR: Fix error of adding image in certain situations exceljs/exceljs#2876
• Email: xiaowangziwxy@gmail.com
• Also implemented in Catscratch fork (commit a55ca28)

Related

• Upstream Issue: [BUG] Export to EXCEL, image is wrong exceljs/exceljs#1804
• Upstream PR: Fix error of adding image in certain situations exceljs/exceljs#2876 (still open since Feb 2024)
• Discussion: [BUG] Export to EXCEL, image is wrong exceljs/exceljs#1804

Plan

1. ✅ Create this tracking issue
2. Apply changes to our fork
3. Add/update test coverage
4. Comment on upstream PR Fix error of adding image in certain situations exceljs/exceljs#2876 about adoption

[protobi-pieter]

✅ Complete

This issue was successfully resolved in commit cdb3dad on November 7, 2025, and closed on November 10, 2025.

Changes Applied

Adopted the fix from upstream PR #2876 which resolves upstream issue #1804:

lib/xlsx/xform/sheet/worksheet-xform.js:

// Before:
let rIdImage = this.preImageId === medium.imageId ? 
  drawingRelsHash[medium.imageId] :  // ❌ Wrong! Used imageId as hash key
  drawingRelsHash[drawing.rels.length];

// After:
let rIdImage = this.preImageId === medium.imageId ? 
  this.preRIdImage :  // ✅ Use stored relationship ID
  drawingRelsHash[drawing.rels.length];

// And now we store it:
this.preRIdImage = rIdImage;

spec/integration/issues/issue-1804-add-image.spec.js (53 lines):

• Comprehensive test case for the bug scenario
• Tests that reused images maintain correct references
• Verifies image IDs after save/load cycle

spec/integration/data/image1.jpg:

• Added second test image for multi-image tests

What This Fixes

Before: When adding the same image multiple times non-consecutively, wrong image references were created:

ws.addImage(img2, 'A1:A1');  // Image 2 ✅
ws.addImage(img1, 'A3:A3');  // Image 1 ✅
ws.addImage(img1, 'A5:A5');  // Should be img1, but became img2! ❌

After: All image references are now correct:

ws.addImage(img2, 'A1:A1');  // Image 2 ✅
ws.addImage(img1, 'A3:A3');  // Image 1 ✅
ws.addImage(img1, 'A5:A5');  // Image 1 ✅

Root Cause

The code tracked preImageId but not the corresponding relationship ID (rIdImage). When the same image was reused after another image, it would incorrectly look up the relationship using the imageId as a hash key instead of using the stored rId.

Testing

• ✅ Comprehensive test suite added
• ✅ All existing tests pass
• ✅ Code merged to master branch
• ✅ Pushed to remote repository

Attribution

Original work by wwwxy80s

• PR: Fix error of adding image in certain situations exceljs/exceljs#2876 (open since Feb 2024)
• Issue: [BUG] Export to EXCEL, image is wrong exceljs/exceljs#1804
• Email: xiaowangziwxy@gmail.com
• Also implemented in: https://github.com/Catscratch/exceljs (commit a55ca28)