toDataURL

定义

toDataURL是HTMLCanvasElement接口上的一个实例方法，调用后会返回一个数据URL(data URL)字符串，其中包含以参数指定格式表示的画面图像^[3]。若调用时不传参数，则等同于请求PNG格式，返回值以「data:image/png」开头^[1]。

方法可接受2个可选参数：第1个参数 type 是表示图像格式的字符串，默认值为image/png；第2个参数 quality 是0到1之间的数值，用于在使用有损压缩格式(如image/jpeg、image/webp)时决定图像质量^[4]。返回值是包含请求数据的URL字符串；当画布宽度或高度为0、或超过最大画布尺寸时，返回的字符串为「data:」^[3]。

原理

画布在浏览器中以位图形式保存像素数据，toDataURL的工作流程是先取画布的位图快照，再按目标格式对像素做编码，最后把编码结果按数据URL的语法拼成字符串^[5]。其数据URL形式可概括为 $data:[\text{MIME类型}][;base64],\text{数据}$，浏览器必须支持PNG，许多浏览器还支持JPEG与WebP等编码格式^[1]。

围绕格式请求有一个约定：若请求的类型不被支持，实现会退回PNG输出，因此开发者可通过检查返回字符串是否以「data:image/png」开头来判断指定格式是否生效^[6]。对于支持写入分辨率元数据的格式，生成的图像数据分辨率为96dpi；对于不支持透明通道的格式，画布内容会先被合成到不透明背景上再编码^[3]。

安全方面，该方法与toBlob、getImageData一样会检查画布的「源干净」(origin-clean)标志：若画布位图中含有来自其他站点的内容，调用会抛出SecurityError异常，以避免跨源数据被读出。

发展历程

toDataURL随HTML5画布规范一起出现。早期草案即规定，无参数调用时返回表示PNG图像的数据URL，并对无像素的画布返回最短的「data:」字符串^[6]。规范同时确定了只强制要求支持PNG、其他类型由用户代理自行决定的支持策略^[6]。

从浏览器兼容角度看，该特性自2015年7月起在主流浏览器中广泛可用，被各浏览器实现共同支持^[3]。随后JPEG、WebP等格式的支持逐渐增加，编码质量参数也随之被更多实现接受^[4]。

应用

最常见的用途是把画布内容导出为可下载的图片：先取得画布的数据URL，再动态创建带download属性的链接元素，把它作为链接地址并触发点击，即可保存为图像文件^[2]。

数据URL还可直接赋给图像元素的src属性，用于把处理后的画面嵌入页面或做灰度转换等动态效果^[3]。在移动端与跨平台框架中也有同类接口，例如某些系统画布接口提供相同名字的方法，把绘制结果以数据URI形式返回，参数含义与网页版本一致^[7]。

局限

toDataURL把整幅图像编码成内存中的字符串，图像较大时不仅影响性能，还可能超出浏览器的URL长度限制，把它赋给图像元素的src时尤为明显；因此官方文档建议优先改用toBlob并配合createObjectURL^[3]。由于结果是Base64编码文本，体积通常比原始二进制更大，不适合作为大量图像的长期存储方式^[4]。

该方法还受同源策略限制：画布一旦被来自其他站点的内容污染，调用就会抛出SecurityError而无法导出。此外，格式支持取决于浏览器实现，只有PNG被强制要求，请求其他类型不保证得到对应编码^[3]。

参见

• HTMLCanvasElement —— toDataURL所属的接口，代表网页中的画布元素。

• 数据URL —— 该方法返回结果所采用的数据嵌入形式。

• Canvas API —— 提供网页2D与WebGL绘图的整套接口。

• toBlob —— 导出画布内容的替代方法，以二进制对象返回结果。

• Base64 —— 数据URL中常用的文本编码方式。