html2canvas 截图踩坑实录：文字偏移、Flex 布局与图标尺寸

## 问题一：截图文字整体下移

### 现象

截图后所有组件内的文字整体向下偏移，表现为：

- 文本上方内边距变大
- 文本下方内边距被裁剪消失
- 元素整体高度不变，只是文字在容器内偏移了位置

受影响组件包括公告栏、金刚区、直播间、商品专区、商品列表等几乎所有含文字的组件。

### 排查过程

排除了以下无效尝试：

| 尝试方向 | 结果 |
|---|---|
| 组件根元素加 `overflow: hidden` | 不影响文字偏移 |
| 将 CSS `gap` 替换为 `margin` | 不影响文字偏移 |
| 将 `align-items: center` 替换为 `line-height` | 不影响文字偏移 |
| `onclone` 回调中修改克隆 DOM 样式 | 不影响文字偏移 |
| 手动 `cloneNode` + 屏幕外渲染 | 产生空白截图 |
| `foreignObjectRendering: true` | 产生空白截图 |

### 根因

html2canvas 内部会向 `body` 末尾插入一个隐藏的 `<div>`，内含一个 `<img>` 元素，用于测量文字基线（baseline）。

但全局 CSS 中对 `img` 标签设置了 `display: block`（来自 Tailwind Preflight 或 Element Plus 等 UI 库的 reset 样式），导致基线测量结果产生偏差，所有文字集体下移。

此 bug 讨论详见 html2canvas GitHub issue [#2775](https://github.com/niklasvh/html2canvas/issues/2775)。

### 解决方案（两处叠加）

**1. 升级 html2canvas 版本**

```
旧: html2canvas@1.4.1
新: @html2canvas/html2canvas@1.6.3
```

> v1.6.3 的 changelog 明确修复了文字对齐问题，同时包名从 `html2canvas` 变更为 `@html2canvas/html2canvas`。

**2. 截图前注入修复样式**

在调用 `html2canvas()` 之前，动态向 `<head>` 注入一条 CSS 规则，将测量用的隐藏 `<img>` 重置为 `inline-block`：

```js
const fixStyle = document.createElement("style");
document.head.appendChild(fixStyle);
if (fixStyle.sheet) {
  fixStyle.sheet.insertRule(
    "body > div:last-child img { display: inline-block; }"
  );
}
```

截图完成后移除该样式：

```js
fixStyle.remove();
```

### 为什么不能在 onclone 里修

`onclone` 回调处理的是 html2canvas **内部克隆后的**文档副本，此时基线测量已经完成。必须在调用前注入样式，影响到 html2canvas 克隆原 DOM 之前的环境。

---

## 问题二：底部导航截图布局错乱

### 现象

底部导航（BottomNav）在页面上正常水平排列，但截图后：

- 四个导航项变成单列竖向排列
- 图标和文字没有居中
- 文本不存在时图标异常变大

### 根因

底部导航的原始布局是 **Flexbox**：

```css
.tabBarBox {
  display: flex;
  flex-direction: row;      /* 关键：水平排列 */
}
.item {
  display: flex;
  flex-direction: column;   /* 图标在上，文字在下 */
  align-items: center;      /* 水平居中 */
  flex: 1;
}
```

html2canvas **不支持 `flex-direction: row`**。在截图渲染时，flex 容器被当作普通块级元素处理，导致横向排列变成纵向堆叠。

### 解决方案：截图前临时替换为 table 布局

利用 `table` / `table-cell` 作为 html2canvas 兼容的横排替代方案，截图前操作 DOM，截图后恢复：

```js
// 1. tabBarBox: flex → table
tabBar.style.display = "table";
tabBar.style.width = "100%";
tabBar.style.tableLayout = "fixed";

// 2. 每个 .item: flex-column → table-cell
item.style.display = "table-cell";
item.style.textAlign = "center";
item.style.verticalAlign = "top";

// 3. 内部 img 和 span: 改为 block 实现纵向堆叠 + 居中
const img = item.querySelector("img");
const span = item.querySelector("span.name");

if (img) {
  img.style.display = "block";
  img.style.marginLeft = "auto";
  img.style.marginRight = "auto";
}
if (span) {
  span.style.display = "block";
  span.style.textAlign = "center";
}
```

这里 `vertical-align: top` 而非 `middle`，是为了匹配原始 flex 布局的 `align-items: center` 效果——flex-start 对应 table-cell 的 top 对齐。

### 状态备份与恢复

操作真实 DOM 后必须完整恢复，否则页面会残留修改后的样式：

```js
// 备份 —— 只备份原本就有值的 inline style 属性
navBackup.push({
  el: tabBar,
  display: tabBar.style.display,
});
navBackup.push({
  el: item,
  display: item.style.display,
  textAlign: item.style.textAlign,
  verticalAlign: item.style.verticalAlign,
});
navBackup.push({
  el: img,
  display: img?.style.display,
  marginLeft: img?.style.marginLeft,
  marginRight: img?.style.marginRight,
  width: img?.style.width,
  height: img?.style.height,
});

// 截图后恢复
navBackup.forEach((s) => {
  if (!s.el) return;
  if (s.display !== undefined) s.el.style.display = s.display;
  if (s.textAlign !== undefined) s.el.style.textAlign = s.textAlign;
  if (s.verticalAlign !== undefined) s.el.style.verticalAlign = s.verticalAlign;
  if (s.marginLeft !== undefined) s.el.style.marginLeft = s.marginLeft;
  if (s.marginRight !== undefined) s.el.style.marginRight = s.marginRight;
  if (s.width !== undefined) s.el.style.width = s.width;
  if (s.height !== undefined) s.el.style.height = s.height;
});
```

> 注意：用 `!== undefined` 判断而非 truthy，因为空字符串 `""` 是合法的 CSS 值，表示"该属性原本没有内联样式，设置为空即是清理"。

---

## 问题三：无文本时图标尺寸异常

### 现象

居中问题解决后，当底部导航项的文本不存在（`item.text === ''`）时，截图中的图标大小与页面上不一致。

业务的 CSS 逻辑是：无文本时图标放大到 45×45px（类名 `icon-max`），有文本时保持 22×22px（类名 `icon`）：

```css
.icon {
  width: 22px;
  height: 22px;
}
.icon-max {
  width: 45px;
  height: 45px;
}
```

### 根因

我们将 img 设为 `display: block` 来让它在 `table-cell` 中独占一行并居中，但没有显式指定 `width` 和 `height`。html2canvas 在克隆 DOM 后，对 CSS 类选择器的级联支持不可靠——`.icon` / `.icon-max` 中定义的尺寸未能正确应用到 `display: block` 的 img 上，导致图标按原始图片的自然尺寸渲染（远大于 45px）。

### 解决方案：getComputedStyle 锁定尺寸

在设置 `display: block` 之后，读取浏览器**已计算好的**真实尺寸，强制写成内联样式：

```js
if (img) {
  img.style.display = "block";
  img.style.marginLeft = "auto";
  img.style.marginRight = "auto";

// 读取浏览器已计算的尺寸，锁定为内联样式
  const cs = getComputedStyle(img);
  img.style.width = cs.width;   // "45px" 或 "22px"
  img.style.height = cs.height;
}
```

**为什么这样做有效**：浏览器本身对 CSS 类选择器的处理是正确的——`.icon-max` 的 45px 已经生效，`getComputedStyle` 返回的就是 "45px"。只是 html2canvas 在自己的渲染管线中用不好。把计算后的最终值转成内联样式，绕过了 html2canvas 的 CSS 级联短板。

---

## 完整修改文件清单

| 文件 | 改动内容 |
|---|---|
| `package.json` | `html2canvas@1.4.1` → `@html2canvas/html2canvas@1.6.3` |
| `src/views/Decoration/Decoration.vue` | 文字基线修复注入、flex→table 布局转换、图标尺寸锁定、展开滚动区逻辑迁移至 `onclone` |
| `src/components/settings/BottomNavSettings.vue` | `el-color-picker` → 原生 `<input type="color">` |
| `src/components/settings/GoodsListSettings.vue` | 同上 |
| `src/components/settings/GoodsZoneSettings.vue` | 同上 |
| `src/components/settings/SpecialZoneSettings.vue` | 同上 |

---

## 总结

html2canvas 是一个能将 DOM 渲染到 Canvas 的强大工具，但它毕竟不是真正的浏览器引擎。使用中有几点值得注意：

1. **文字渲染受全局 CSS 影响** —— 升级版本 + 注入修复样式是经过验证的有效方案。
2. **Flexbox 支持不完整** —— 特别是 `flex-direction: row`，可用 `table` / `table-cell` 做临时平替。
3. **CSS 类选择器不完全可靠** —— 关键尺寸属性建议用 `getComputedStyle` 读取后转为内联样式。
4. **操作真实 DOM 必须备份恢复** —— 截图前修改 DOM，截图后用备份数据完整还原，包括空字符串的属性。

html2canvas 截图踩坑实录：文字偏移、Flex 布局与图标尺寸

// 评论区

发表评论

// 最新评论