html2canvas在Firefox上background-size黑畫面的問題

malagege included in HTML

2014-11-12 226 words 2 minutes

Contents

html2canvas 是什麼？

html2canvas 是一套 JavaScript 函式庫，能夠將 HTML 元素「截圖」轉換為 Canvas 圖片，讓使用者可以將網頁內容匯出為圖片檔案。

常見應用場景：

讓使用者截圖並儲存活動票券、證書
前端產生報表圖片
網頁分享卡片的圖片產生

Firefox 上的 background-size 黑畫面問題

在使用 html2canvas 時，若元素的背景圖片使用了像素值設定尺寸（如 background-size: 200px），在 Firefox 上會出現黑畫面或背景圖無法顯示的問題。

這是因為 html2canvas 在解析特定版本 Firefox 的 background-size 數值時存在相容性問題，無法正確讀取像素值。

問題程式碼：

1
2
3
4
5


/* ❌ Firefox 上 html2canvas 可能顯示黑畫面 */
.hero {
  background-image: url('image.jpg');
  background-size: 800px;
}

解決方法：

改用 cover 或 contain 關鍵字：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


/* ✅ 使用 cover */
.hero {
  background-image: url('image.jpg');
  background-size: cover;
  background-position: center;
}

/* ✅ 使用 contain */
.thumbnail {
  background-image: url('image.jpg');
  background-size: contain;
  background-repeat: no-repeat;
}

cover 與 contain 的差異

屬性值	說明
`cover`	等比例縮放，完全覆蓋容器，可能裁切圖片
`contain`	等比例縮放，完整顯示圖片，可能有空白邊
`100% 100%`	拉伸填滿容器，不等比例
`200px`	固定寬度，高度等比例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


/* cover：圖片填滿，可能裁切 */
.banner {
  background-size: cover;
  background-position: center;
}

/* contain：圖片完整顯示 */
.logo {
  background-size: contain;
  background-repeat: no-repeat;
  background-position: center;
}

html2canvas 常見相容性問題與解決思路

CSS 屬性支援限制：html2canvas 不支援所有 CSS 屬性，如 box-shadow、text-shadow 某些語法可能無法正確渲染。
跨域圖片：外部圖片需要 CORS 支援，或使用 proxy 選項。
字體不一致：確保截圖時字體已完全載入（使用 document.fonts.ready）。
iFrame 內容：無法截取跨域 iFrame 的內容。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// 基本使用方式
html2canvas(document.getElementById('target'), {
  useCORS: true,        // 允許跨域圖片
  allowTaint: false,    // 不允許污染 canvas（與跨域相關）
  scale: window.devicePixelRatio,  // 高 DPI 螢幕的清晰度
}).then(canvas => {
  document.body.appendChild(canvas);
  // 或下載為圖片
  const link = document.createElement('a');
  link.download = 'screenshot.png';
  link.href = canvas.toDataURL();
  link.click();
});