Flutter中如何向PdfGrid插入图片？BackgroundImage设置无效

问题表现 #

给PdfGrid单元格style.backgroundImage属性传入PdfBitmap对象插入图片，调用draw方法绘制后图片未正常展示，效果如下：

核心复现代码：

PdfBitmap pBmp = PdfBitmap(await _readImageData('1.jpg'));

PdfGridRow row2 = grid2.rows.add();
row2.cells[0].value = 'Velocidad - v [fpm]';
row2.cells[1].style.backgroundImage = pBmp;
...
grid2.draw(page: page, bounds: const Rect.fromLTWH(0, 130, 500, 500));

根因 #

1. 未配置backgroundImageLayout属性时，背景图默认按原始尺寸渲染，不会自动适配单元格大小，一旦图片偏移出单元格边界就会不可见。
2. 单元格默认带不透明白色背景刷，会直接覆盖下层的背景图。
3. 部分版本的PDF渲染库中，直接修改单元格默认style实例的属性不会触发样式更新标记，赋值操作实际不生效。

修复实现 #

// 加载解码图片
final PdfBitmap targetBmp = PdfBitmap(await _readImageData('1.jpg'));

PdfGridRow row2 = grid2.rows.add();
row2.cells[0].value = 'Velocidad - v [fpm]';
// 为单元格显式创建样式实例，全量配置所需参数
row2.cells[1].style = PdfGridCellStyle(
  backgroundImage: targetBmp,
  // 配置背景图拉伸适配单元格尺寸
  backgroundImageLayout: PdfBackgroundImageLayout.stretch,
  // 设置透明背景，避免遮挡图片
  backgroundBrush: PdfBrushes.transparent,
);
// 单元格仅展示图片时清空value，避免文本内容遮挡
// row2.cells[1].value = '';

// 按原有逻辑绘制网格
grid2.draw(page: page, bounds: const Rect.fromLTWH(0, 130, 500, 500));

排查补充 #

• 改完仍不显示的，先单独把图片直接绘制到页面上，排除图片读取、解码失败问题：

  page.graphics.drawImage(targetBmp, const Rect.fromLTWH(0, 0, 100, 100));
  

• 要保留图片原始比例不拉伸的，把backgroundImageLayout改成PdfBackgroundImageLayout.center，同时手动调整对应列宽、行高，保证单元格尺寸大于图片原始尺寸，防止图片被裁剪。

内容的提问来源于stack exchange，提问作者Carlos Aguas