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 顏色空間