CanvasRenderingContext2D:roundRect() 方法

Baseline 2023
Newly available

Since April 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

Canvas 2D API 的 CanvasRenderingContext2D.roundRect() 方法用于在当前路径中添加一个圆角矩形。

角的半径可以像 CSS border-radius 属性一样指定。

像其他修改当前路径的方法一样,此方法不会直接渲染任何内容。要将圆角矩形绘制到画布上,你可以使用 fill()stroke() 方法。

语法

js
roundRect(x, y, width, height, radii)

参数

x

矩形起点的 x 轴坐标,以像素为单位。

y

矩形起点的 y 轴坐标,以像素为单位。

width

矩形的宽度。正值向右,负值向左。

height

矩形的高度。正值向下,负值向上。

radii

指定用于矩形角的圆弧半径的数字或列表。其数量和顺序与 widthheight 为正值时的 border-radius CSS 属性相同:

  • all-corners
  • [all-corners]
  • [top-left-and-bottom-right, top-right-and-bottom-left]
  • [top-left, top-right-and-bottom-left, bottom-right]
  • [top-left, top-right, bottom-right, bottom-left]

如果 width 为负,圆角矩形水平翻转,因此通常适用于左角的半径值用于右角,反之亦然。同样,当 height 为负时,圆角矩形垂直翻转。如果任何边缘短于两个顶点的组合半径,则指定的半径可能会缩小(缩减)。

radii 参数也可以是 DOMPointDOMPointReadOnly 实例,或者包含相同属性的对象({x: 0, y: 0}),或这些对象的列表,或混合数字和这些对象的列表。

返回值

无 (undefined)。

异常

RangeError

如果 radii 是零个或多个元素的列表,或其值之一为负数。

示例

绘制矩形

此示例使用 roundRect() 方法创建多个圆角矩形路径,然后使用 stroke() 方法渲染这些路径。

HTML

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

JavaScript

首先,我们创建一个用于绘制圆角矩形的上下文。

js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

下面的代码绘制了两个矩形,都从点 (10, 20) 开始,宽度为 150,高度为 100。第一个矩形用红色绘制,并使用数字作为参数指定所有角的半径为零。第二个用蓝色绘制,并使用单个列表元素来指定半径为 40px。

js
// 半径为零的圆角矩形(指定为数字)
ctx.strokeStyle = "red";
ctx.beginPath();
ctx.roundRect(10, 20, 150, 100, 0);
ctx.stroke();

// 半径为 40px 的圆角矩形(单元素列表)
ctx.strokeStyle = "blue";
ctx.beginPath();
ctx.roundRect(10, 20, 150, 100, [40]);
ctx.stroke();

在前一个矩形下面,我们绘制了另一个橙色的矩形,该矩形指定了对角的半径值。

js
// 具有两个不同半径的圆角矩形
ctx.strokeStyle = "orange";
ctx.beginPath();
ctx.roundRect(10, 150, 150, 100, [10, 40]);
ctx.stroke();

最后,我们绘制了两个具有四个不同半径值且起点相同的圆角矩形。这里的区别在于第二个矩形是用负宽度绘制的。

js
// 具有四个不同半径的圆角矩形
ctx.strokeStyle = "green";
ctx.beginPath();
ctx.roundRect(400, 20, 200, 100, [0, 30, 50, 60]);
ctx.stroke();

// 向后绘制的相同矩形
ctx.strokeStyle = "magenta";
ctx.beginPath();
ctx.roundRect(400, 150, -200, 100, [0, 30, 50, 60]);
ctx.stroke();

结果

结果如下图所示。对于右侧的两个矩形,请注意底部矩形是如何用负宽度绘制的,以及矩形是如何水平翻转的。

规范

Specification
HTML
# dom-context-2d-roundrect

浏览器兼容性

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
roundRect

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support

参见