企业官网建设流程全解析

html2canvas 快速上手：从 npm 安装到首个浏览器端截图

【免费下载链接】html2canvasScreenshots with JavaScript项目地址: https://gitcode.com/gh_mirrors/ht/html2canvas

本篇技术指南以 docs/getting-started.md 为核心脉络，面向希望在浏览器端用 JavaScript 把 DOM 元素"拍"成<canvas>图片的开发者，完整覆盖 html2canvas 的安装方式、最小可用示例、html2canvas(element, options)的调用签名与 Promise 用法，并结合仓库源码（src/index.ts）、配置文档（docs/configuration.md）与示例页面（examples/demo.html）补充选项默认值、忽略规则与底层渲染流程。读完本文，你将能独立完成一次"安装 → 渲染 → 拿到 canvas"的完整实践，并理解截图背后"克隆 DOM → 解析样式 → 绘制 canvas"的机制。

一、html2canvas 是什么

html2canvas 是一个纯 JavaScript 的 HTML 渲染器：它直接在用户的浏览器中读取当前页面的 DOM 树与各个元素的计算样式，据此在<canvas>上重新"绘制"出页面或其局部的截图。正如 README.md 所述，它并不是调用浏览器底层 API 拍摄真实屏幕快照，而是基于 DOM 中可读取的信息重建页面表示，因此：

• 整个过程发生在客户端浏览器，不依赖任何服务器端渲染；
• 它只能正确渲染自己"认识"的 CSS 属性，docs/documentation.md 明确说明存在不少尚不支持的 CSS 特性；
• 受浏览器同源策略限制，跨域图片需要借助 docs/proxy.md 中描述的代理方案才能读取。

仓库当前版本为1.4.1（见 package.json），入口实现位于 src/index.ts。

二、安装

2.1 通过 npm 安装

在项目根目录执行：

npm install html2canvas

安装完成后，在 ES Module 环境中导入：

import html2canvas from 'html2canvas';

仓库的 package.json 声明了三种分发入口，按使用环境自动选择：

项目依赖极少，仅css-line-break与text-segmentation两个运行时库；engines字段要求 Node 版本不低于 8.0.0（用于构建/开发环境，运行时仍依赖浏览器）。

2.2 直接下载构建产物

也可以从项目的 Release 页面下载已构建好的html2canvas.js（或压缩版dist/html2canvas.min.js），通过<script>标签引入后，html2canvas会作为全局函数可用。仓库中的示例页面正是这种用法，例如 examples/demo.html：

<script type="text/javascript" src="../dist/html2canvas.js"></script> <script type="text/javascript"> html2canvas(document.body).then(function(canvas) { document.body.appendChild(canvas); }); </script>

注意：html2canvas 的 API 基于 Promise 实现。若要兼容不支持原生 Promise 的旧浏览器（如 IE9），需要在使用前引入es6-promise之类的 polyfill（README.md）。

三、最小可用示例

安装完成后的第一次调用只需一行：

html2canvas(document.body).then(function(canvas) { document.body.appendChild(canvas); });

逐句拆解：

1. html2canvas(element)接收一个HTMLElement作为要渲染的目标元素（这里传入document.body，即渲染整个页面）；
2. 函数返回一个Promise，其 resolve 值是一个<canvas>元素；
3. 通过then拿到 canvas 后，把它appendChild回页面即可看到渲染结果。

从源码看，入口签名是（src/index.ts）：

const html2canvas = (element: HTMLElement, options: Partial<Options> = {}): Promise<HTMLCanvasElement> => { return renderElement(element, options); };

element是必选参数，options为可选参数，最终一定返回Promise<HTMLCanvasElement>。

3.1 只渲染某个局部元素

不必总是渲染整页。把任意 DOM 元素传进去，就只渲染该元素及其子内容。例如 examples/demo2.html 渲染了整个body，而 examples/existing_canvas.html 展示了只渲染#content元素的写法：

html2canvas(document.querySelector('#content'), {canvas: canvas, scale: 1}).then(function(canvas) { console.log('Drew on the existing canvas'); });

3.2 参数校验与边界行为

src/index.ts 的renderElement对入参做了防御性校验，可作为排查问题的依据：

• 传入的element不是对象（如undefined），Promise 会被reject('Invalid element provided as first argument')；
• 元素不属于任何Document，抛错Element is not attached to a Document；
• 文档不属于任何Window，抛错Document is not attached to a Window。

四、常用配置选项

html2canvas(element, options)的第二个参数是可选配置对象。docs/configuration.md 给出了完整的选项表，以下为全量选项及默认值：

这些选项在 src/index.ts 中被分组消费：allowTaint/imageTimeout/proxy/useCORS构成资源加载配置，windowWidth/windowHeight/scrollX/scrollY构成视口边界（windowBounds），scale/x/y/width/height/canvas构成渲染配置，onclone/ignoreElements则进入克隆配置。

4.1 排除不需要渲染的元素

除了ignoreElements谓词，html2canvas 还支持属性约定：给元素加上data-html2canvas-ignore属性，它就会从渲染中被排除。该属性在 src/dom/document-cloner.ts 中定义为常量IGNORE_ATTRIBUTE，并在克隆节点时被检查（src/dom/document-cloner.ts）：带此属性、或命中ignoreElements谓词的元素不会被复制进克隆文档。

仓库的回归测试 tests/reftests/options/ignore.html 同时演示了两种排除方式：

<!-- 通过 data 属性排除 --> <div id="ignored">h2cOptions = {ignoreElements: function(element) { return element.className === 'ignored'; }};

一个典型场景是官网示例组件 www/src/components/example.js 中，用data-html2canvas-ignore把"预览画布容器"自身排除在截图之外，避免截图里嵌套截图。

五、渲染流程与底层原理

理解了调用方式后，再看 src/index.ts 中renderElement的完整链路，能帮助你更好地定位配置生效的位置：

1. 创建上下文：根据allowTaint、imageTimeout、proxy、useCORS、logging等构造Context，并基于scrollX/scrollY/windowWidth/windowHeight计算视口边界；
2. 克隆文档：DocumentCloner将目标元素复制到离屏 iframe 中（克隆过程中应用ignoreElements与data-html2canvas-ignore过滤）；若提供了onclone回调，会在克隆完成后、绘制开始前执行，可用于临时改写样式或内容；
3. 解析尺寸：计算待渲染区域的宽高与偏移；对于body/html元素按文档尺寸解析，否则按元素边界解析；
4. 确定背景色：通过parseBackgroundColor综合documentElement、body与backgroundColor选项决定画布底色（src/index.ts），backgroundColor: null时最终为透明；
5. 两条渲染路径：
   • 默认的计算渲染（CanvasRenderer）：把克隆 DOM 解析成内部节点树（parseTree），再逐个绘制 CSS 属性；
   • ForeignObject 渲染（foreignObjectRendering: true且浏览器支持时）：直接把克隆的 DOM 节点序列化进foreignObject由浏览器原生排版，效果更接近真实页面；
6. 清理：默认（removeContainer: true）销毁临时克隆 iframe，随后返回画布。

README 中特别强调：html2canvas 是浏览器端库，不适用于 Node.js，且对页面内容策略没有任何"魔法"绕过能力——跨域图片必须借助代理（proxy选项，详见 docs/proxy.md）或 CORS（useCORS）方案。

六、构建与本地预览（可选）

若希望从源码自行构建，仓库 README.md 提供了标准流程：

# 克隆仓库后安装依赖 npm install # 构建浏览器产物到 dist/ npm run build

构建脚本链（package.json）会依次执行 TypeScript 编译、Rollup 打包（rollup.config.ts）、生成回归测试清单并用 uglifyjs 产出dist/html2canvas.min.js。开发时也可以直接运行仓库自带的示例（examples/目录下的 HTML 引用了../dist/html2canvas.js，需先构建产物），或在 www/static/tests/index.html 的测试控制台页面中交互式验证各渲染场景。

七、常见疑问速查

• 截图后 canvas 是空白的？检查目标元素是否已挂载到文档（未挂载会抛错），以及width/height/scale是否被设成了不合理的值；注意渲染基于计算样式，未支持 CSS 属性可能缺失。
• 跨域图片不显示？默认行为是"留空 proxy 则不加载跨域图片"（见 docs/configuration.md 中proxy说明）；请配置代理或使用 CORS 服务端。
• 如何去掉白色背景得到透明 PNG？设置backgroundColor: null（透明）；需要固定底色时传任意 CSS 颜色字符串。
• 不想让某个弹层/按钮出现在截图里？给该元素添加data-html2canvas-ignore属性，或通过ignoreElements谓词过滤。

至此，你已经掌握 html2canvas 从安装到调用的完整路径；更深入的能力（如代理、支持特性清单）可继续阅读仓库中的 docs/configuration.md、docs/proxy.md 与 docs/features.md。

【免费下载链接】html2canvasScreenshots with JavaScript项目地址: https://gitcode.com/gh_mirrors/ht/html2canvas