openharmony 鸿蒙 arkts-apis-graphics-drawing-Region

2026-08-25 浏览 (1)

Class (Region)

区域对象,用于描述所绘制图形的区域信息。

说明:

  • 本模块首批接口从API version 11开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

  • 本Class首批接口从API version 12开始支持。

  • 本模块使用屏幕物理像素单位px。

  • 本模块为单线程模型策略,需要调用方自行管理线程安全和上下文状态的切换。

导入模块

import { drawing } from '@kit.ArkGraphics2D';

constructor20+

constructor()

构造一个区域对象。

系统能力: SystemCapability.Graphics.Drawing

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context: DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setColor({
      alpha: 255,
      red: 255,
      green: 0,
      blue: 0
    });
    pen.setStrokeWidth(10);
    canvas.attachPen(pen);
    let region = new drawing.Region();
    region.setRect(200, 200, 400, 400);
    canvas.drawRegion(region);
    canvas.detachPen();
  }
}

constructor20+

constructor(region: Region)

拷贝一个区域对象。

系统能力: SystemCapability.Graphics.Drawing

参数:

参数名类型必填说明
regionRegion用于拷贝的区域。

示例:

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context: DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setColor({
      alpha: 255,
      red: 255,
      green: 0,
      blue: 0
    });
    pen.setStrokeWidth(10);
    canvas.attachPen(pen);
    let region = new drawing.Region();
    region.setRect(200, 200, 400, 400);
    let region2 = new drawing.Region(region);
    canvas.drawRegion(region2);
    canvas.detachPen();
  }
}

constructor20+

constructor(left: number, top: number, right: number, bottom: number)

构造矩形区域。

系统能力: SystemCapability.Graphics.Drawing

参数:

参数名类型必填说明
leftnumber矩形区域的左侧位置(矩形左上角横坐标)。该参数必须为整数。0表示坐标原点,负数表示位于坐标原点左侧,正数表示位于坐标原点右侧。单位为物理像素px。
topnumber矩形区域的顶部位置(矩形左上角纵坐标)。该参数必须为整数。0表示坐标原点,负数表示位于坐标原点上侧,正数表示位于坐标原点下侧。单位为物理像素px。
rightnumber矩形区域的右侧位置(矩形右下角横坐标)。该参数必须为整数。0表示坐标原点,负数表示位于坐标原点左侧,正数表示位于坐标原点右侧。单位为物理像素px。
bottomnumber矩形区域的底部位置(矩形右下角纵坐标)。该参数必须为整数。0表示坐标原点,负数表示位于坐标原点上侧,正数表示位于坐标原点下侧。单位为物理像素px。

示例:

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context: DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setColor({
      alpha: 255,
      red: 255,
      green: 0,
      blue: 0
    });
    pen.setStrokeWidth(10);
    canvas.attachPen(pen);
    let region = new drawing.Region(100, 100, 200, 200);
    canvas.drawRegion(region);
    canvas.detachPen();
  }
}

isEqual20+

isEqual(other: Region): boolean

用于判断其他区域是否与当前区域相等。

系统能力: SystemCapability.Graphics.Drawing

参数:

参数名类型必填说明
otherRegion区域对象。

返回值:

类型说明
boolean返回其他区域是否与当前区域相等的结果。true表示相等,false表示不相等。

示例:

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context: DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setColor({
      alpha: 255,
      red: 255,
      green: 0,
      blue: 0
    });
    pen.setStrokeWidth(10);
    canvas.attachPen(pen);
    let region = new drawing.Region();
    let other = new drawing.Region();
    region.setRect(100, 100, 400, 400);
    other.setRect(150, 150, 250, 250);
    let flag: boolean = false;
    flag = region.isEqual(other);
    console.info('flag: ', flag);
    canvas.drawRegion(region);
    canvas.drawRegion(other);
    canvas.detachPen();
  }
}

isComplex20+

isComplex(): boolean

判断当前区域是否包含多个矩形。

系统能力: SystemCapability.Graphics.Drawing

返回值:

类型说明
boolean返回当前区域是否包含多个矩形的结果。true表示当前区域包含多个矩形,false表示当前区域不包含多个矩形。

示例:

import { drawing } from '@kit.ArkGraphics2D';
import { RenderNode } from '@kit.ArkUI';

class DrawingRenderNode extends RenderNode {
  draw(context: DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setColor({
      alpha: 255,
      red: 255,
      green: 0,
      blue: 0
    });
    pen.setStrokeWidth(10);
    canvas.attachPen(pen);
    let region = new drawing.Region();
    let other = new drawing.Region();
    region.setRect(100, 100, 200, 200);
    region.op(new drawing.Region(220, 200, 280, 280), drawing.RegionOp.UNION);
    let flag: boolean = false;
    flag = region.isComplex();
    console.info('flag :', flag);
    canvas.drawRegion(region);
    canvas.drawRegion(other);
    canvas.detachPen();
  }
}

isEmpty20+

isEmpty(): boolean

判断当前区域是否为空。

系统能力: SystemCapability.Graphics.Drawing

返回值:

类型说明
boolean返回当前区域是否为空。true表示当前区域为空,false表示当前区域不为空。

示例:

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context: DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setColor({
      alpha: 255,
      red: 255,
      green: 0,
      blue: 0
    });
    pen.setStrokeWidth(10);
    canvas.attachPen(pen);
    let region = new drawing.Region();
    let flag: boolean = region.isEmpty();
    console.info('flag: ', flag);
    region.setRect(100, 100, 400, 400);
    flag = region.isEmpty();
    console.info('flag: ', flag);
    canvas.drawRegion(region);
    canvas.detachPen();
  }
}

getBounds20+

getBounds(): common2D.Rect

获取区域的边界。

系统能力: SystemCapability.Graphics.Drawing

返回值:

类型说明
common2D.Rect返回当前区域的边界矩形。

示例:

import { drawing } from '@kit.ArkGraphics2D';

let region = new drawing.Region();
let rect = region.getBounds();

getBoundaryPath20+

getBoundaryPath(): Path

返回一个新路径,该路径取自当前区域的边界。

系统能力: SystemCapability.Graphics.Drawing

返回值:

类型说明
Path返回当前区域边界的路径。

示例:

import { drawing } from '@kit.ArkGraphics2D';

let region = new drawing.Region();
let path = region.getBoundaryPath();

isPointContained12+

isPointContained(x: number, y: number) : boolean

判断测试点是否在区域内。

系统能力: SystemCapability.Graphics.Drawing

参数:

参数名类型必填说明
xnumber测试点的x轴坐标。该参数必须为整数。如果输入的数字包含小数部分,小数部分将被舍去。单位为物理像素px。
ynumber测试点的y轴坐标。该参数必须为整数。如果输入的数字包含小数部分,小数部分将被舍去。单位为物理像素px。

返回值:

类型说明
boolean返回测试点是否在区域内的结果。true表示测试点在区域内,false表示测试点不在区域内。

错误码:

以下错误码的详细介绍请参见通用错误码

错误码ID错误信息
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例:

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context: DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setColor({
      alpha: 255,
      red: 255,
      green: 0,
      blue: 0
    });
    pen.setStrokeWidth(10);
    canvas.attachPen(pen);
    let region = new drawing.Region();
    region.setRect(100, 100, 400, 400);
    let flag: boolean = false;
    flag = region.isPointContained(200, 200);
    console.info("region isPointContained : " + flag);
    canvas.drawPoint(200, 200);
    canvas.drawRegion(region);
    canvas.detachPen();
  }
}

offset20+

offset(dx: number, dy: number): void

对区域进行平移。

系统能力: SystemCapability.Graphics.Drawing

参数:

参数名类型必填说明
dxnumberx轴方向平移量,正数往x轴正方向平移,负数往x轴负方向平移,该参数为整数。单位为物理像素px。
dynumbery轴方向平移量,正数往y轴正方向平移,负数往y轴负方向平移,该参数为整数。单位为物理像素px。

示例:

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context: DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setColor({
      alpha: 255,
      red: 255,
      green: 0,
      blue: 0
    });
    pen.setStrokeWidth(10);
    canvas.attachPen(pen);
    let region = new drawing.Region();
    region.setRect(100, 100, 400, 400);
    region.offset(10, 20);
    canvas.drawPoint(200, 200);
    canvas.drawRegion(region);
    canvas.detachPen();
  }
}

isRegionContained12+

isRegionContained(other: Region) : boolean

判断其他区域是否在当前区域内。

系统能力: SystemCapability.Graphics.Drawing

参数:

参数名类型必填说明
otherRegion区域对象。

返回值:

类型说明
boolean返回其他区域是否在当前区域内的结果。true表示其他区域在当前区域内,false表示其他区域不在当前区域内。

错误码:

以下错误码的详细介绍请参见通用错误码

错误码ID错误信息
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例:

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context: DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setColor({
      alpha: 255,
      red: 255,
      green: 0,
      blue: 0
    });
    pen.setStrokeWidth(10);
    canvas.attachPen(pen);
    let region = new drawing.Region();
    let other = new drawing.Region();
    region.setRect(100, 100, 400, 400);
    other.setRect(150, 150, 250, 250);
    let flag: boolean = false;
    flag = region.isRegionContained(other);
    console.info("region isRegionContained : " + flag);
    canvas.drawRegion(region);
    canvas.drawRegion(other);
    canvas.detachPen();
  }
}

op12+

op(region: Region, regionOp: RegionOp) : boolean

将当前区域与指定区域进行运算,并替换为运算结果。

系统能力: SystemCapability.Graphics.Drawing

参数:

参数名类型必填说明
regionRegion区域对象。
regionOpRegionOp区域合并操作类型。

返回值:

类型说明
boolean返回区域运算结果是否成功替换当前区域。true表示区域运算结果替换当前区域成功,false表示区域运算结果替换当前区域失败。

错误码:

以下错误码的详细介绍请参见通用错误码

错误码ID错误信息
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例:

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context: DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setColor({
      alpha: 255,
      red: 255,
      green: 0,
      blue: 0
    });
    pen.setStrokeWidth(10);
    canvas.attachPen(pen);
    let region = new drawing.Region();
    region.setRect(200, 200, 400, 400);
    let othregion = new drawing.Region();
    othregion.setRect(110, 110, 240, 240);
    let flag: boolean = false;
    flag = region.op(othregion, drawing.RegionOp.REPLACE);
    console.info("region op : " + flag);
    canvas.drawRegion(region);
    canvas.detachPen();
  }
}

quickReject12+

quickReject(left: number, top: number, right: number, bottom: number) : boolean

快速判断矩形和区域是否不相交,实际上比较的是矩形和区域的外接矩形是否不相交,因此会有误差。

系统能力: SystemCapability.Graphics.Drawing

参数:

参数名类型必填说明
leftnumber矩形区域的左侧位置。该参数必须为整数。当输入的数字带小数时,小数部分会被舍去。单位为物理像素px。
topnumber矩形区域的顶部位置。该参数必须为整数。当输入的数字带小数时,小数部分会被舍去。单位为物理像素px。
rightnumber矩形区域的右侧位置。该参数必须为整数。当输入的数字带小数时,小数部分会被舍去。单位为物理像素px。
bottomnumber矩形区域的底部位置。该参数必须为整数。当输入的数字带小数时,小数部分会被舍去。单位为物理像素px。

返回值:

类型说明
boolean返回矩形是否与区域不相交的结果。true表示矩形与区域不相交,false表示矩形与区域相交。

错误码:

以下错误码的详细介绍请参见通用错误码

错误码ID错误信息
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例:

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context: DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setColor({
      alpha: 255,
      red: 255,
      green: 0,
      blue: 0
    });
    pen.setStrokeWidth(10);
    canvas.attachPen(pen);
    let region = new drawing.Region();
    region.setRect(100, 100, 400, 400);
    let flag: boolean = false;
    flag = region.quickReject(50, 50, 70, 70);
    console.info("region quickReject : " + flag);
    canvas.drawRegion(region);
    canvas.detachPen();
  }
}

quickRejectRegion20+

quickRejectRegion(region: Region): boolean

判断当前区域是否与另一个区域不相交。实际上比较的是两个区域的外接矩形是否不相交,因此会有误差。

系统能力: SystemCapability.Graphics.Drawing

参数:

参数名类型必填说明
regionRegion指定的区域对象。

返回值:

类型说明
boolean返回是否当前区域与另外的区域不相交的结果。true表示不相交,false表示相交。仅点和边相交返回true。

示例:

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context: DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setColor({
      alpha: 255,
      red: 255,
      green: 0,
      blue: 0
    });
    pen.setStrokeWidth(10);
    canvas.attachPen(pen);
    let region = new drawing.Region();
    let region2 = new drawing.Region();
    region2.setRect(100, 100, 400, 400);
    let flag: boolean = false;
    flag = region.quickRejectRegion(region2);
    console.info("region quickRejectRegion: " + flag);
    canvas.drawRegion(region);
    canvas.detachPen();
  }
}

setPath12+

setPath(path: Path, clip: Region) : boolean

设置一个与裁剪区域内路径轮廓相匹配的区域。

系统能力: SystemCapability.Graphics.Drawing

参数:

参数名类型必填说明
pathPath路径对象。
clipRegion区域对象。

返回值:

类型说明
boolean返回设置一个与裁剪区域内路径轮廓相匹配的区域是否成功。true表示设置成功,false表示设置失败。

错误码:

以下错误码的详细介绍请参见通用错误码

错误码ID错误信息
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例:

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context: DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setColor({
      alpha: 255,
      red: 255,
      green: 0,
      blue: 0
    });
    pen.setStrokeWidth(10);
    canvas.attachPen(pen);
    let region = new drawing.Region();
    let path = new drawing.Path();
    region.setRect(100, 100, 400, 400);
    path.arcTo(50, 50, 300, 300, 0, 359);
    let flag: boolean = false;
    flag = region.setPath(path, region);
    console.info("region setPath : " + flag);
    canvas.drawRegion(region);
    canvas.detachPen();
  }
}

setRegion20+

setRegion(region: Region): void

设置当前区域为另一块区域。

系统能力: SystemCapability.Graphics.Drawing

参数:

参数名类型必填说明
regionRegion用于赋值的区域。

示例:

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context: DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setColor({
      alpha: 255,
      red: 255,
      green: 0,
      blue: 0
    });
    pen.setStrokeWidth(10);
    canvas.attachPen(pen);
    let region = new drawing.Region();
    region.setRect(100, 100, 200, 200);
    let region2 = new drawing.Region();
    region2.setRegion(region);
    canvas.drawRegion(region2);
    canvas.detachPen();
  }
}

setEmpty20+

setEmpty(): void

设置当前区域为空。

系统能力: SystemCapability.Graphics.Drawing

示例:

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context: DrawContext) {
    let region = new drawing.Region();
    region.setRect(100, 100, 200, 200);
    let isEmpty = region.isEmpty();
    console.info("isEmpty :" + isEmpty);
    region.setEmpty();
    isEmpty = region.isEmpty();
    console.info("isEmpty :" + isEmpty);
  }
}

setRect12+

setRect(left: number, top: number, right: number, bottom: number) : boolean

设置一个矩形区域。

系统能力: SystemCapability.Graphics.Drawing

参数:

参数名类型必填说明
leftnumber矩形区域的左侧位置。该参数必须为整数。当输入的数字带小数时,小数部分会被舍去。单位为物理像素px。
topnumber矩形区域的顶部位置。该参数必须为整数。当输入的数字带小数时,小数部分会被舍去。单位为物理像素px。
rightnumber矩形区域的右侧位置。该参数必须为整数。当输入的数字带小数时,小数部分会被舍去。单位为物理像素px。
bottomnumber矩形区域的底部位置。该参数必须为整数。当输入的数字带小数时,小数部分会被舍去。单位为物理像素px。

返回值:

类型说明
boolean返回设置矩形区域是否成功的结果。true表示设置矩形区域成功,false表示设置矩形区域失败。

错误码:

以下错误码的详细介绍请参见通用错误码

错误码ID错误信息
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例:

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context: DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setColor({
      alpha: 255,
      red: 255,
      green: 0,
      blue: 0
    });
    pen.setStrokeWidth(10);
    canvas.attachPen(pen);
    let region = new drawing.Region();
    let flag: boolean = false;
    flag = region.setRect(50, 50, 300, 300);
    console.info("region setRect : " + flag);
    canvas.drawRegion(region);
    canvas.detachPen();
  }
}

isRect23+

isRect(): boolean

判断当前区域是否等同于单个矩形。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Graphics.Drawing

返回值:

类型说明
boolean返回当前区域是否等同于单个矩形的结果。true表示当前区域等同于单个矩形,false表示当前区域不等同于单个矩形。

示例:

import { drawing } from '@kit.ArkGraphics2D';
import { RenderNode } from '@kit.ArkUI';

class DrawingRenderNode extends RenderNode {
  draw(context: DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setColor({
      alpha: 255,
      red: 255,
      green: 0,
      blue: 0
    });
    pen.setStrokeWidth(10);
    canvas.attachPen(pen);
    let region = new drawing.Region();
    let flag: boolean = false;
    flag = region.isRect();
    console.info('flag :', flag);
    region.setRect(100, 100, 200, 200);
    flag = region.isRect();
    console.info('flag :', flag);
    let other = new drawing.Region(220, 200, 280, 280);
    region.op(other, drawing.RegionOp.UNION);
    flag = region.isRect();
    console.info('flag :', flag);
    canvas.drawRegion(region);
    canvas.detachPen();
  }
}

quickContains23+

quickContains(left: number, top: number, right: number, bottom: number): boolean

判断当前区域是否等同于单个矩形并且包含指定矩形。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Graphics.Drawing

参数:

参数名类型必填说明
leftnumber矩形区域的左侧位置。该参数必须为整数。当输入的数字带小数时,小数部分会被舍去。单位为物理像素px。
topnumber矩形区域的顶部位置。该参数必须为整数。当输入的数字带小数时,小数部分会被舍去。单位为物理像素px。
rightnumber矩形区域的右侧位置。该参数必须为整数。当输入的数字带小数时,小数部分会被舍去。单位为物理像素px。
bottomnumber矩形区域的底部位置。该参数必须为整数。当输入的数字带小数时,小数部分会被舍去。单位为物理像素px。

返回值:

类型说明
boolean返回当前区域是否等同于单个矩形并且包含指定矩形的结果。true表示当前区域等同于单个矩形并且包含指定矩形,false表示当前区域不等同于单个矩形或不包含指定矩形。

示例:

import { drawing } from '@kit.ArkGraphics2D';
import { RenderNode } from '@kit.ArkUI';

class DrawingRenderNode extends RenderNode {
  draw(context: DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setColor({
      alpha: 255,
      red: 255,
      green: 0,
      blue: 0
    });
    pen.setStrokeWidth(10);
    canvas.attachPen(pen);
    let region = new drawing.Region();
    let flag: boolean = false;
    flag = region.quickContains(10, 10, 100, 100);
    console.info('flag :', flag);
    let other = new drawing.Region();
    other.setRect(100, 100, 200, 200);
    flag = other.quickContains(10, 10, 100, 100);
    console.info('flag :', flag);
    canvas.drawRegion(region);
    canvas.drawRegion(other);
    canvas.detachPen();
  }
}

你可能感兴趣的鸿蒙文章

openharmony 鸿蒙 capi-drawing-gpu-context-h

openharmony 鸿蒙 capi-drawing-nativepixelmap-

openharmony 鸿蒙 capi-nativevsync-oh-nativevsync-expectedraterange

openharmony 鸿蒙 capi-drawing-oh-drawing-brush

openharmony 鸿蒙 capi-drawing-oh-drawing-image-info

openharmony 鸿蒙 capi-drawing-text-linetypography-h

openharmony 鸿蒙 capi-oh-nativeimage-oh-nativeimage

openharmony 鸿蒙 capi-drawing-typeface-h

openharmony 鸿蒙 capi-drawing-brush-h

openharmony 鸿蒙 capi-nativewindow

  • 所属分类: 后端技术
  • 本文标签: 鸿蒙 软件
  • 版权声明: 本文链接 https://seaxiang.com/blog/28YFMnZ7