CanvasRenderingContext2D：putImageData() 方法

基线 广泛可用

此功能已经过完善，可在许多设备和浏览器版本上运行。它自以下日期起在各浏览器中可用： 2015 年 7 月.

Canvas 2D API 的 CanvasRenderingContext2D.putImageData() 方法将来自给定 ImageData 对象的数据绘制到画布上。如果提供了脏矩形，则仅绘制该矩形中的像素。此方法不受画布变换矩阵的影响。

注意：可以使用 getImageData() 方法从画布中检索图像数据。

您可以在文章 使用画布进行像素操作 中找到有关 putImageData() 和画布内容的一般操作的更多信息。

语法

js
putImageData(imageData, dx, dy)
putImageData(imageData, dx, dy, dirtyX, dirtyY, dirtyWidth, dirtyHeight)

参数

imageData

包含像素值数组的 ImageData 对象。

dx

在目标画布中放置图像数据的水平位置（x 坐标）。

dy

在目标画布中放置图像数据的垂直位置（y 坐标）。

dirtyX 可选

将从中提取图像数据的左上角的水平位置（x 坐标）。默认为 0。

dirtyY 可选

将从中提取图像数据的左上角的垂直位置（y 坐标）。默认为 0。

dirtyWidth 可选

要绘制的矩形的宽度。默认为图像数据的宽度。

dirtyHeight 可选

要绘制的矩形的高度。默认为图像数据的高度。

返回值

无 (undefined).

异常

NotSupportedError DOMException

如果任何参数为无穷大，则抛出。

InvalidStateError DOMException

如果 ImageData 对象的数据已分离，则抛出。

示例

了解 putImageData

要了解此算法在幕后做了什么，以下是在 CanvasRenderingContext2D.fillRect() 之上的实现。

HTML

html
<canvas id="canvas"></canvas>

JavaScript

js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

function putImageData(
  ctx,
  imageData,
  dx,
  dy,
  dirtyX,
  dirtyY,
  dirtyWidth,
  dirtyHeight,
) {
  const data = imageData.data;
  const height = imageData.height;
  const width = imageData.width;
  dirtyX = dirtyX || 0;
  dirtyY = dirtyY || 0;
  dirtyWidth = dirtyWidth !== undefined ? dirtyWidth : width;
  dirtyHeight = dirtyHeight !== undefined ? dirtyHeight : height;
  const limitBottom = dirtyY + dirtyHeight;
  const limitRight = dirtyX + dirtyWidth;
  for (let y = dirtyY; y < limitBottom; y++) {
    for (let x = dirtyX; x < limitRight; x++) {
      const pos = y * width + x;
      ctx.fillStyle = `rgb(${data[pos * 4 + 0]} ${data[pos * 4 + 1]}
      ${data[pos * 4 + 2]} / ${data[pos * 4 + 3] / 255})`;
      ctx.fillRect(x + dx, y + dy, 1, 1);
    }
  }
}

// Draw content onto the canvas
ctx.fillRect(0, 0, 100, 100);
// Create an ImageData object from it
const imagedata = ctx.getImageData(0, 0, 100, 100);
// use the putImageData function that illustrates how putImageData works
putImageData(ctx, imagedata, 150, 0, 50, 50, 25, 25);

结果

由于浏览器优化导致的数据丢失

警告：由于将预乘 alpha 颜色值转换为和从预乘 alpha 颜色值转换的损失性，使用 putImageData() 刚刚设置的像素可能以不同的值返回给等效的 getImageData()。

JavaScript

js
const canvas = document.createElement("canvas");
canvas.width = 1;
canvas.height = 1;
const context = canvas.getContext("2d");
const imgData = context.getImageData(0, 0, canvas.width, canvas.height);
const pixels = imgData.data;
pixels[0 + 0] = 1;
pixels[0 + 1] = 127;
pixels[0 + 2] = 255;
pixels[0 + 3] = 1;
console.log("before:", pixels);
context.putImageData(imgData, 0, 0);
const imgData2 = context.getImageData(0, 0, canvas.width, canvas.height);
const pixels2 = imgData2.data;
console.log("after:", pixels2);

输出可能如下所示

before: Uint8ClampedArray(4) [ 1, 127, 255, 1 ]
after: Uint8ClampedArray(4) [ 255, 255, 255, 1 ]

规范

规范
HTML 标准
# dom-context-2d-putimagedata-dev

浏览器兼容性

BCD 表仅在浏览器中加载

另请参阅