CanvasRenderingContext2D

Baseline 廣泛可用 *

此特性已相當成熟，可在許多裝置和瀏覽器版本上使用。自 ⁨2015 年 7 月⁩以來，各瀏覽器均已提供此特性。

* 此特性的某些部分可能存在不同級別的支援。

CanvasRenderingContext2D 介面是 Canvas API 的一部分，它為 <canvas> 元素的繪圖表面提供了 2D 渲染上下文。它用於繪製形狀、文字、影像和其他物件。

此頁面的參考部分描述了該介面的屬性和方法。Canvas 教程中也提供了更多解釋、示例和資源。

對於 OffscreenCanvas，存在一個提供渲染上下文的等效介面。離屏渲染上下文繼承了 CanvasRenderingContext2D 的大部分相同屬性和方法，並在 OffscreenCanvasRenderingContext2D 參考頁面中進行了更詳細的描述。

基本示例

要獲取 CanvasRenderingContext2D 例項，你必須首先有一個 HTML <canvas> 元素可供操作。

html

<canvas id="my-house" width="300" height="300"></canvas>

要獲取 canvas 的 2D 渲染上下文，請在 <canvas> 元素上呼叫 getContext()，並提供 '2d' 作為引數。

const canvas = document.getElementById("my-house");
const ctx = canvas.getContext("2d");

有了上下文，你就可以繪製任何你喜歡的東西。這段程式碼繪製了一個房子。

// Set line width
ctx.lineWidth = 10;

// Wall
ctx.strokeRect(75, 140, 150, 110);

// Door
ctx.fillRect(130, 190, 40, 60);

// Roof
ctx.beginPath();
ctx.moveTo(50, 140);
ctx.lineTo(150, 60);
ctx.lineTo(250, 140);
ctx.closePath();
ctx.stroke();

最終的繪圖結果如下：

參考

上下文

CanvasRenderingContext2D.getContextAttributes(): 返回一個包含瀏覽器使用的上下文屬性的物件。在使用 HTMLCanvasElement.getContext() 建立 2D 上下文時可以請求上下文屬性。
CanvasRenderingContext2D.isContextLost(): 如果渲染上下文丟失，則返回 true。

繪製矩形

有三種方法可以直接在畫布上繪製矩形。

CanvasRenderingContext2D.clearRect(): 將由起始點 (x, y) 和大小 (width, height) 定義的矩形中的所有畫素設定為透明黑色，擦除任何以前繪製的內容。
CanvasRenderingContext2D.fillRect(): 在 (x, y) 位置繪製一個填充矩形，其大小由 width 和 height 確定。
CanvasRenderingContext2D.strokeRect(): 使用當前描邊樣式在畫布上繪製一個矩形，其起始點為 (x, y)，寬度為 w，高度為 h。

繪製文字

以下方法繪製文字。另請參閱用於文字屬性的 TextMetrics 物件。

CanvasRenderingContext2D.fillText(): 在給定的 (x, y) 位置繪製（填充）給定的文字。
CanvasRenderingContext2D.strokeText(): 在給定的 (x, y) 位置繪製（描邊）給定的文字。
CanvasRenderingContext2D.measureText(): 返回一個 TextMetrics 物件。

線條樣式

以下方法和屬性控制線條的繪製方式。

CanvasRenderingContext2D.lineWidth: 線條寬度。預設值 1.0。
CanvasRenderingContext2D.lineCap: 線條末端的樣式。可能的值：butt（預設）、round、square。
CanvasRenderingContext2D.lineJoin: 定義兩條線相交處的角點型別。可能的值：round、bevel、miter（預設）。
CanvasRenderingContext2D.miterLimit: 斜接限制比。預設值 10。
CanvasRenderingContext2D.getLineDash(): 返回當前線條虛線圖案陣列，其中包含偶數個非負數。
CanvasRenderingContext2D.setLineDash(): 設定當前線條虛線圖案。
CanvasRenderingContext2D.lineDashOffset: 指定虛線陣列在一條線上開始的位置。

文字樣式

以下屬性控制文字的佈局方式。

CanvasRenderingContext2D.font: 字型設定。預設值 "10px sans-serif"。
CanvasRenderingContext2D.textAlign: 文字對齊設定。可能的值：start（預設）、end、left、right、center。
CanvasRenderingContext2D.textBaseline: 基線對齊設定。可能的值：top、hanging、middle、alphabetic（預設）、ideographic、bottom。
CanvasRenderingContext2D.direction: 方向性。可能的值：ltr、rtl、inherit（預設）。
CanvasRenderingContext2D.letterSpacing: 字母間距。預設值：0px。
CanvasRenderingContext2D.fontKerning: 字型字偶距。可能的值：auto（預設）、normal、none。
CanvasRenderingContext2D.fontStretch: 字型拉伸。可能的值：ultra-condensed、extra-condensed、condensed、semi-condensed、normal（預設）、semi-expanded、expanded、extra-expanded、ultra-expanded。
CanvasRenderingContext2D.fontVariantCaps: 字型大寫樣式。可能的值：normal（預設）、small-caps、all-small-caps、petite-caps、all-petite-caps、unicase、titling-caps。
CanvasRenderingContext2D.textRendering: 文字渲染。可能的值：auto（預設）、optimizeSpeed、optimizeLegibility、geometricPrecision。
CanvasRenderingContext2D.wordSpacing: 單詞間距。預設值：0px
CanvasRenderingContext2D.lang 實驗性: 獲取或設定 canvas 繪圖上下文的語言。

填充和描邊樣式

填充樣式用於形狀內部的顏色和樣式，描邊樣式用於形狀周圍的線條。

CanvasRenderingContext2D.fillStyle: 用於形狀內部的顏色或樣式。預設值為 black。
CanvasRenderingContext2D.strokeStyle: 用於形狀周圍線條的顏色或樣式。預設值為 black。

漸變和圖案

CanvasRenderingContext2D.createConicGradient(): 圍繞由引數表示的座標點建立一個錐形漸變。
CanvasRenderingContext2D.createLinearGradient(): 沿由引數表示的座標線建立一個線性漸變。
CanvasRenderingContext2D.createRadialGradient(): 根據引數表示的兩個圓的座標建立一個徑向漸變。
CanvasRenderingContext2D.createPattern(): 使用指定的影像建立圖案。它按照重複引數指定的方向重複源。此方法返回一個 CanvasPattern。

陰影

CanvasRenderingContext2D.shadowBlur: 指定模糊效果。預設值：0。
CanvasRenderingContext2D.shadowColor: 陰影顏色。預設值：完全透明的黑色。
CanvasRenderingContext2D.shadowOffsetX: 陰影的水平偏移距離。預設值：0。
CanvasRenderingContext2D.shadowOffsetY: 陰影的垂直偏移距離。預設值：0。

路徑

以下方法可用於操作物件的路徑。

CanvasRenderingContext2D.beginPath(): 透過清空子路徑列表來開始新路徑。當你想要建立新路徑時呼叫此方法。
CanvasRenderingContext2D.closePath(): 使畫筆點移回到當前子路徑的起點。它嘗試從當前點到起點繪製一條直線。如果形狀已關閉或只有一個點，此函式不執行任何操作。
CanvasRenderingContext2D.moveTo(): 將新子路徑的起始點移動到 (x, y) 座標。
CanvasRenderingContext2D.lineTo(): 用一條直線將當前子路徑中的最後一個點連線到指定的 (x, y) 座標。
CanvasRenderingContext2D.bezierCurveTo(): 向當前路徑新增一條三次貝塞爾曲線。
CanvasRenderingContext2D.quadraticCurveTo(): 向當前路徑新增一條二次貝塞爾曲線。
CanvasRenderingContext2D.arc(): 向當前路徑新增一個圓弧。
CanvasRenderingContext2D.arcTo(): 根據給定的控制點和半徑向當前路徑新增一個圓弧，並用一條直線連線到前一個點。
CanvasRenderingContext2D.ellipse(): 向當前路徑新增一個橢圓弧。
CanvasRenderingContext2D.rect(): 在 (x, y) 位置建立一個矩形路徑，其大小由 width 和 height 確定。
CanvasRenderingContext2D.roundRect(): 建立一個具有指定位置、寬度、高度和圓角半徑的圓角矩形路徑。

繪製路徑

CanvasRenderingContext2D.fill(): 使用當前填充樣式填充當前子路徑。
CanvasRenderingContext2D.stroke(): 使用當前描邊樣式描繪當前子路徑。
CanvasRenderingContext2D.drawFocusIfNeeded(): 如果給定元素獲得焦點，此方法會在當前路徑周圍繪製一個焦點環。
CanvasRenderingContext2D.clip(): 從當前子路徑建立裁剪路徑。呼叫 clip() 後繪製的所有內容都只顯示在裁剪路徑內。有關示例，請參閱 Canvas 教程中的裁剪路徑。
CanvasRenderingContext2D.isPointInPath(): 報告指定的點是否包含在當前路徑中。
CanvasRenderingContext2D.isPointInStroke(): 報告指定的點是否在路徑描邊所包含的區域內。

轉換

CanvasRenderingContext2D 渲染上下文中的物件具有當前的變換矩陣和操作它的方法。變換矩陣在建立當前預設路徑、繪製文字、形狀和 Path2D 物件時應用。以下列出的方法是出於歷史和相容性原因保留的，因為現在 API 的大部分都使用 DOMMatrix 物件，並且將來也將繼續使用。

CanvasRenderingContext2D.getTransform(): 檢索當前應用於上下文的變換矩陣。
CanvasRenderingContext2D.rotate(): 向變換矩陣新增旋轉。角度引數表示順時針旋轉角度，以弧度表示。
CanvasRenderingContext2D.scale(): 透過 x 水平方向和 y 垂直方向對 canvas 單位新增縮放變換。
CanvasRenderingContext2D.translate(): 透過將 canvas 及其原點在網格上水平移動 x 和垂直移動 y 來新增平移變換。
CanvasRenderingContext2D.transform(): 將當前變換矩陣與其引數描述的矩陣相乘。
CanvasRenderingContext2D.setTransform(): 將當前變換重置為單位矩陣，然後使用相同的引數呼叫 transform() 方法。
CanvasRenderingContext2D.resetTransform(): 透過單位矩陣重置當前變換。

合成

CanvasRenderingContext2D.globalAlpha: 在形狀和影像合成到畫布上之前應用的 Alpha 值。預設值 1.0（不透明）。
CanvasRenderingContext2D.globalCompositeOperation: 在應用 globalAlpha 後，這會設定如何將形狀和影像繪製到現有點陣圖上。

繪製圖像

CanvasRenderingContext2D.drawImage(): 繪製指定的影像。此方法有多種格式，提供了很大的使用靈活性。

畫素操作

另請參閱 ImageData 物件。

CanvasRenderingContext2D.createImageData(): 建立具有指定尺寸的新空白 ImageData 物件。新物件中的所有畫素都是透明黑色。
CanvasRenderingContext2D.getImageData(): 返回一個 ImageData 物件，表示畫布區域的底層畫素資料，該區域由從 (sx, sy) 開始、寬度為 sw、高度為 sh 的矩形表示。
CanvasRenderingContext2D.putImageData(): 將給定 ImageData 物件中的資料繪製到點陣圖上。如果提供了髒矩形，則只繪製該矩形中的畫素。

影像平滑

CanvasRenderingContext2D.imageSmoothingEnabled: 影像平滑模式；如果停用，影像在縮放時將不會進行平滑處理。
CanvasRenderingContext2D.imageSmoothingQuality: 允許你設定影像平滑的質量。

Canvas 狀態

CanvasRenderingContext2D 渲染上下文包含各種繪圖樣式狀態（線條樣式、填充樣式、陰影樣式、文字樣式的屬性）。以下方法可幫助你處理該狀態。

CanvasRenderingContext2D.save(): 使用堆疊儲存當前繪圖樣式狀態，以便你可以使用 restore() 恢復對其所做的任何更改。
CanvasRenderingContext2D.restore(): 將繪圖樣式狀態恢復到由 save() 儲存的“狀態堆疊”上的最後一個元素。
CanvasRenderingContext2D.canvas: 對 HTMLCanvasElement 的只讀反向引用。如果未與 <canvas> 元素關聯，則可能為 null。
CanvasRenderingContext2D.getContextAttributes(): 返回一個包含瀏覽器使用的上下文屬性的物件。在使用 HTMLCanvasElement.getContext() 建立 2D 上下文時可以請求上下文屬性。
CanvasRenderingContext2D.reset(): 重置渲染上下文，包括後臺緩衝區、繪圖狀態堆疊、路徑和樣式。
CanvasRenderingContext2D.isContextLost() 實驗性: 如果渲染上下文丟失，則返回 true。

過濾器

CanvasRenderingContext2D.filter: 對 canvas 應用 CSS 或 SVG 濾鏡，例如，更改其亮度或模糊度。

規範

規範
HTML # 2dcontext

瀏覽器相容性

另見

幫助改進 MDN

瞭解如何貢獻

此頁面由 MDN 貢獻者於 2025 年 9 月 25 日最後修改。

在 GitHub 上檢視此頁面 • 報告此內容的問題