HTMLCanvasElement：getContext() 方法

基线 广泛可用

此功能已得到良好建立，并且可在许多设备和浏览器版本中使用。它自以下时间起在所有浏览器中都可用： 2015 年 7 月.

HTMLCanvasElement.getContext() 方法返回画布上的绘图上下文，如果上下文标识符不受支持或画布已设置为不同的上下文模式，则返回null。

对同一画布元素使用相同 contextType 参数的后续调用始终会返回与第一次调用方法时返回的相同的绘图上下文实例。无法在给定的画布元素上获取不同的绘图上下文对象。

语法

js
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"，它将创建一个GPUCanvasContext 对象，该对象表示用于 WebGPU 渲染管线的 3D 渲染上下文。此上下文仅在实现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 可选

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

desynchronized

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

willReadFrequently

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

WebGL 上下文属性

alpha

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

深度

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

模板

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

desynchronized

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

抗锯齿

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

failIfMajorPerformanceCaveat

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

powerPreference

提示用户代理指示哪种 GPU 配置适合 WebGL 上下文。可能的值为

"默认"

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

"高性能"

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

"低功耗"

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

premultipliedAlpha

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

preserveDrawingBuffer

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

xrCompatible

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

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

返回值

一个渲染上下文，它可以是

如果 contextType 与可能的绘图上下文不匹配，或与请求的第一个 contextType 不同，则返回 null。

示例

给定此<canvas> 元素

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

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

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

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

规范

规范
HTML 标准
# dom-canvas-getcontext-dev

浏览器兼容性

BCD 表格仅在启用了 JavaScript 的浏览器中加载。

另请参阅