ImageData: ImageData() 构造函数

语法

new ImageData(width, height)
new ImageData(width, height, settings)

new ImageData(dataArray, width)
new ImageData(dataArray, width, height)
new ImageData(dataArray, width, height, settings)

参数

width

一个无符号长整数，表示图像的宽度。

height

一个无符号长整数，表示图像的高度。如果提供了数组，则此值是可选的：高度将根据数组大小和提供的宽度推断得出。

settings 可选

具有以下属性的对象：

colorSpace

指定图像数据的颜色空间。可以设置为 "srgb" 表示 sRGB 颜色空间，或设置为 "display-p3" 表示 display-p3 颜色空间。

pixelFormat

指定像素格式。可能的值：

• "rgba-unorm8"，表示每组件 8 位无符号归一化格式的 RGBA，使用 Uint8ClampedArray。这是默认值。
• "rgba-float16"：表示 16 位每分量的 RGBA，使用 Float16Array。浮点像素值允许表示任意宽色域和高动态范围 (HDR) 的颜色。

dataArray

一个 Uint8ClampedArray 或 Float16Array，包含图像的底层像素表示。如果未提供此类数组，将创建一个具有指定 width 和 height 的透明黑色矩形图像。dataArray 的类型必须与 settings.pixelFormat 匹配。

返回值

一个新的 ImageData 对象。

异常

IndexSizeError DOMException

如果指定了 dataArray，但其长度不等于 (bytesPerPixel * width * height)，或者如果未指定 height，则长度不等于 (bytesPerPixel * width) 的倍数，则抛出此错误。当 pixelFormat 为 "rgba-unorm8" 时，bytesPerPixel 为 4，否则为 8。

InvalidStateError DOMException

如果 dataArray 的类型是 Uint8ClampedArray 且 pixelFormat 未设置为 "rgba-unorm8"，或者如果 dataArray 的类型是 Float16Array 且 pixelFormat 未设置为 "rgba-float16"，则抛出此错误。

示例

创建空白 ImageData 对象

此示例创建一个宽度为 200 像素、高度为 100 像素的 ImageData 对象，总共包含 20,000 个像素。

let imageData = new ImageData(200, 100);
// ImageData { width: 200, height: 100, data: Uint8ClampedArray[80000] }

使用 display-p3 色彩空间的 ImageData

此示例创建一个具有 display-p3 色彩空间的 ImageData 对象。

let imageData = new ImageData(200, 100, { colorSpace: "display-p3" });

用于宽色域和高动态范围 (HDR) 的浮点像素数据

浮点像素值允许在任意宽的色域和高动态范围 (HDR) 中表示颜色。您可以将 pixelFormat 设置为 "rgba-float16"，以使用每组件 16 位的 RGBA 值。这要求 dataArray 是一个 Float16Array。

let floatArray = new Float16Array(4 * 200 * 200);
let imageData = new ImageData(floatArray, 200, 200, {
  pixelFormat: "rgba-float16",
});
console.log(imageData.pixelFormat); // "rgba-float16"

使用数组初始化 ImageData

此示例使用数组定义的像素颜色来实例化 ImageData 对象。

HTML

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

JavaScript

数组 (arr) 的长度为 40000：它由 10,000 个像素组成，每个像素由 4 个值定义。ImageData 构造函数为新对象指定了 width 为 200，因此其 height 默认为 10,000 除以 200，即 50。

const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");
const arr = new Uint8ClampedArray(40_000);

// Fill the array with the same RGBA values
for (let i = 0; i < arr.length; i += 4) {
  arr[i + 0] = 0; // R value
  arr[i + 1] = 190; // G value
  arr[i + 2] = 0; // B value
  arr[i + 3] = 255; // A value
}

// Initialize a new ImageData object
let imageData = new ImageData(arr, 200);

// Draw image data to the canvas
ctx.putImageData(imageData, 20, 20);

结果

规范

浏览器兼容性

另见

• CanvasRenderingContext2D.createImageData()，可以在 worker 之外使用的创建方法。