HTMLCanvasElement: getContext() 方法

语法

getContext(contextType)
getContext(contextType, contextAttributes)

参数

contextType

一个字符串，包含定义与画布关联的绘图上下文的上下文标识符。可能的值是

"2d"

创建一个表示二维渲染上下文的 CanvasRenderingContext2D 对象。

"webgl" (或 "experimental-webgl")

创建一个表示三维渲染上下文的 WebGLRenderingContext 对象。此上下文仅在实现 WebGL 1 (OpenGL ES 2.0) 的浏览器中可用。

"webgl2"

创建一个表示三维渲染上下文的 WebGL2RenderingContext 对象。此上下文仅在实现 WebGL 2 (OpenGL ES 3.0) 的浏览器中可用。

"webgpu"

创建一个表示 WebGPU 渲染管线的 3D 渲染上下文的 GPUCanvasContext 对象。此上下文仅在实现 WebGPU API 的浏览器中可用。

"bitmaprenderer"

创建一个 ImageBitmapRenderingContext，它仅提供用给定的 ImageBitmap 替换画布内容的功能。

注意: "experimental-webgl" 标识符用于 WebGL 的新实现。这些实现要么尚未达到测试套件的符合性，要么平台上的图形驱动程序尚未稳定。 Khronos Group 根据特定的 符合性规则 来认证 WebGL 实现。

contextAttributes 可选

在创建渲染上下文时，您可以使用多个上下文属性，例如

js

const gl = canvas.getContext("webgl", {
  antialias: false,
  depth: false,
});

2d 上下文属性

alpha

一个布尔值，指示画布是否包含 alpha 通道。如果设置为 false，浏览器现在知道背景始终是不透明的，这可以加快透明内容和图像的绘制速度。

colorSpace 可选

指定渲染上下文的颜色空间。可能的值是

• "srgb" 选择 sRGB 颜色空间。这是默认值。
• "display-p3" 选择 display-p3 颜色空间。

colorType 可选

指定渲染上下文的颜色类型。可能的值是

• "unorm8" 将颜色通道设置为 8 位无符号值。这是默认值。
• "float16" 将颜色通道设置为 16 位浮点值。

desynchronized

一个布尔值，提示用户代理通过将画布绘制周期与事件循环分离来减少延迟。

willReadFrequently

一个布尔值，指示是否计划了大量读取操作。这将强制使用软件（而不是硬件加速）的 2D 画布，并在频繁调用 getImageData() 时节省内存。

WebGL 上下文属性

alpha

一个布尔值，指示画布是否包含 alpha 缓冲区。

depth

一个布尔值，指示是否请求绘制缓冲区具有至少 16 位的深度缓冲区。

stencil

一个布尔值，指示是否请求绘制缓冲区具有至少 8 位的模板缓冲区。

desynchronized

一个布尔值，提示用户代理通过将画布绘制周期与事件循环分离来减少延迟。

antialias

一个布尔值，指示是否在可能的情况下执行抗锯齿。

failIfMajorPerformanceCaveat

一个布尔值，指示当系统性能较低或没有硬件 GPU 可用时，是否创建上下文。

powerPreference

一个提示用户代理指示适合 WebGL 上下文的 GPU 配置的值。可能的值是

"default"

让用户代理决定最适合的 GPU 配置。这是默认值。

"high-performance"

优先考虑渲染性能而不是功耗。

"low-power"

优先考虑省电而不是渲染性能。

premultipliedAlpha

一个布尔值，指示页面合成器将假设绘制缓冲区包含预乘 alpha 的颜色。

preserveDrawingBuffer

如果值为 true，则缓冲区不会被清除，并将保留其值，直到被清除或由作者覆盖。

xrCompatible

一个布尔值，提示用户代理为 沉浸式 XR 设备 使用兼容的图形适配器。不建议在上下文创建时设置此同步标志；而应在您打算开始 XR 会话时调用异步 WebGLRenderingContext.makeXRCompatible() 方法。

注意: WebGPU 规范没有为 getContext() 定义任何特定的上下文属性。相反，它通过 GPUCanvasContext.configure() 方法提供配置选项。

返回值

一个渲染上下文，可以是

• "2d" 的 CanvasRenderingContext2D；
• "webgl" 和 "experimental-webgl" 的 WebGLRenderingContext；
• "webgl2" 的 WebGL2RenderingContext；
• "webgpu" 的 GPUCanvasContext；
• "bitmaprenderer" 的 ImageBitmapRenderingContext。

如果上下文标识符不受支持，或者画布已设置为不同的上下文模式，则返回 null。

异常

InvalidStateError DOMException

如果在调用 HTMLCanvasElement.transferControlToOffscreen() 后画布已将其控制权转移到屏幕外，则会抛出异常。

示例

给定此 <canvas> 元素

<canvas id="canvas" width="300" height="300"></canvas>

您可以使用以下代码获取画布的 2d 上下文

const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");
console.log(ctx); // CanvasRenderingContext2D { /* … */ }

现在您拥有了画布的 2D 渲染上下文，并可以在其中进行绘制。

规范

浏览器兼容性

另见

• HTMLCanvasElement: 定义 HTMLCanvasElement.getContext() 方法的接口
• OffscreenCanvas.getContext()
• CanvasRenderingContext2D.getContextAttributes(), WebGLRenderingContext.getContextAttributes()
• CanvasRenderingContext2D, ImageBitmapRenderingContext, WebGLRenderingContext, WebGL2RenderingContext, GPUCanvasContext: 可用的渲染上下文
• 维基百科上的 DCI-P3 颜色空间
• 维基百科上的 sRGB 颜色空间