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 声明了三种分发入口按使用环境自动选择字段指向产物适用场景maindist/html2canvas.jsCommonJS / 浏览器直接引用moduledist/html2canvas.esm.jsES Module 打包器如 Rollup、Webpacktypingsdist/types/index.d.tsTypeScript 类型提示项目依赖极少仅css-line-break与text-segmentation两个运行时库engines字段要求 Node 版本不低于 8.0.0用于构建/开发环境运行时仍依赖浏览器。2.2 直接下载构建产物也可以从项目的 Release 页面下载已构建好的html2canvas.js或压缩版dist/html2canvas.min.js通过script标签引入后html2canvas会作为全局函数可用。仓库中的示例页面正是这种用法例如 examples/demo.htmlscript typetext/javascript src../dist/html2canvas.js/script script typetext/javascript html2canvas(document.body).then(function(canvas) { document.body.appendChild(canvas); }); /script注意html2canvas 的 API 基于 Promise 实现。若要兼容不支持原生 Promise 的旧浏览器如 IE9需要在使用前引入es6-promise之类的 polyfillREADME.md。三、最小可用示例安装完成后的第一次调用只需一行html2canvas(document.body).then(function(canvas) { document.body.appendChild(canvas); });逐句拆解html2canvas(element)接收一个HTMLElement作为要渲染的目标元素这里传入document.body即渲染整个页面函数返回一个Promise其 resolve 值是一个canvas元素通过then拿到 canvas 后把它appendChild回页面即可看到渲染结果。从源码看入口签名是src/index.tsconst html2canvas (element: HTMLElement, options: PartialOptions {}): PromiseHTMLCanvasElement { return renderElement(element, options); };element是必选参数options为可选参数最终一定返回PromiseHTMLCanvasElement。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不是对象如undefinedPromise 会被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 给出了完整的选项表以下为全量选项及默认值名称默认值说明allowTaintfalse是否允许跨域图片污染taintcanvasbackgroundColor#ffffff当 DOM 中未指定时使用的 canvas 背景色设为null则为透明canvasnull作为绘制底板的既有canvas元素foreignObjectRenderingfalse浏览器支持时是否使用 ForeignObject 渲染imageTimeout15000图片加载超时毫秒设为0关闭超时ignoreElements(element) false谓词函数返回true的元素会被移出渲染loggingtrue是否输出调试日志onclonenull克隆文档完成后回调可修改将被渲染的内容而不影响源文档proxynull用于加载跨域图片的代理地址留空则跨域图片不加载removeContainertrue是否清理 html2canvas 临时创建的克隆 DOMscalewindow.devicePixelRatio渲染缩放比例默认取浏览器设备像素比width元素宽度canvas 的宽度height元素高度canvas 的高度x元素 x 偏移裁剪 canvas 的 x 坐标y元素 y 偏移裁剪 canvas 的 y 坐标scrollX元素 scrollX渲染时使用的 x 方向滚动位置例如元素为position: fixed时scrollY元素 scrollY渲染时使用的 y 方向滚动位置windowWidthWindow.innerWidth渲染时使用的窗口宽度可能影响媒体查询等windowHeightWindow.innerHeight渲染时使用的窗口高度这些选项在 src/index.ts 中被分组消费allowTaint/imageTimeout/proxy/useCORS构成资源加载配置windowWidth/windowHeight/scrollX/scrollY构成视口边界windowBoundsscale/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 idignored>h2cOptions {ignoreElements: function(element) { return element.className ignored; }};一个典型场景是官网示例组件 www/src/components/example.js 中用data-html2canvas-ignore把预览画布容器自身排除在截图之外避免截图里嵌套截图。五、渲染流程与底层原理理解了调用方式后再看 src/index.ts 中renderElement的完整链路能帮助你更好地定位配置生效的位置创建上下文根据allowTaint、imageTimeout、proxy、useCORS、logging等构造Context并基于scrollX/scrollY/windowWidth/windowHeight计算视口边界克隆文档DocumentCloner将目标元素复制到离屏 iframe 中克隆过程中应用ignoreElements与data-html2canvas-ignore过滤若提供了onclone回调会在克隆完成后、绘制开始前执行可用于临时改写样式或内容解析尺寸计算待渲染区域的宽高与偏移对于body/html元素按文档尺寸解析否则按元素边界解析确定背景色通过parseBackgroundColor综合documentElement、body与backgroundColor选项决定画布底色src/index.tsbackgroundColor: null时最终为透明两条渲染路径默认的计算渲染CanvasRenderer把克隆 DOM 解析成内部节点树parseTree再逐个绘制 CSS 属性ForeignObject 渲染foreignObjectRendering: true且浏览器支持时直接把克隆的 DOM 节点序列化进foreignObject由浏览器原生排版效果更接近真实页面清理默认removeContainer: true销毁临时克隆 iframe随后返回画布。README 中特别强调html2canvas 是浏览器端库不适用于 Node.js且对页面内容策略没有任何魔法绕过能力——跨域图片必须借助代理proxy选项详见 docs/proxy.md或 CORSuseCORS方案。六、构建与本地预览可选若希望从源码自行构建仓库 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考