1# Class (Matrix) 2 3<!--Kit: ArkGraphics 2D--> 4<!--Subsystem: Graphics--> 5<!--Owner: @hangmengxin--> 6<!--Designer: @wangyanglan--> 7<!--Tester: @nobuggers--> 8<!--Adviser: @ge-yafang--> 9 10> **说明：** 11> 12> - 本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 13> 14> - 本Class首批接口从API version 12开始支持。 15> 16> - 本模块使用屏幕物理像素单位px。 17> 18> - 本模块为单线程模型策略，需要调用方自行管理线程安全和上下文状态的切换。 19 20矩阵对象。 21 22表示为3*3的矩阵，如下图所示： 23 24 25 26矩阵中的元素从左到右，从上到下分别表示水平缩放系数、水平倾斜系数、水平位移系数、垂直倾斜系数、垂直缩放系数、垂直位移系数、X轴透视系数、Y轴透视系数、透视缩放系数。 27设(x<sub>1</sub>, y<sub>1</sub>)为源坐标点，(x<sub>2</sub>, y<sub>2</sub>)为源坐标点通过矩阵变换后的坐标点，则两个坐标点的关系如下： 28 29 30 31## 导入模块 32 33```ts 34import { drawing } from '@kit.ArkGraphics2D'; 35``` 36 37## constructor<sup>12+</sup> 38 39constructor() 40 41构造一个矩阵对象。 42 43**系统能力：** SystemCapability.Graphics.Drawing 44 45**示例：** 46 47```ts 48import { drawing } from '@kit.ArkGraphics2D'; 49 50let matrix = new drawing.Matrix(); 51``` 52 53## constructor<sup>20+</sup> 54 55constructor(matrix: Matrix) 56 57拷贝一个矩阵。 58 59**系统能力：** SystemCapability.Graphics.Drawing 60 61**参数：** 62 63| 参数名 | 类型 | 必填 | 说明 | 64| ----------- | ---------------------------------------- | ---- | ------------------- | 65| matrix | [Matrix](arkts-apis-graphics-drawing-Matrix.md) | 是 | 被拷贝的矩阵。| 66 67**示例：** 68 69```ts 70import { drawing } from '@kit.ArkGraphics2D'; 71 72let matrix = new drawing.Matrix(); 73let matrix2 = new drawing.Matrix(matrix); 74``` 75 76## isAffine<sup>20+</sup> 77 78isAffine(): boolean 79 80判断当前矩阵是否为仿射矩阵。仿射矩阵是一种包括平移、旋转、缩放等变换的矩阵。 81 82**系统能力：** SystemCapability.Graphics.Drawing 83 84**返回值：** 85 86| 类型 | 说明 | 87| --------------------------- | -------------------- | 88| boolean | 返回当前矩阵是否为仿射矩阵。true表示是仿射矩阵，false表示不是仿射矩阵。 | 89 90**示例：** 91 92```ts 93import { drawing } from '@kit.ArkGraphics2D'; 94 95let matrix = new drawing.Matrix(); 96matrix.setMatrix([1, 0.5, 1, 0.5, 1, 1, 1, 1, 1]); 97let isAff = matrix.isAffine(); 98console.info('isAff :', isAff); 99``` 100 101## rectStaysRect<sup>20+</sup> 102 103rectStaysRect(): boolean 104 105判断经过该矩阵映射后的矩形的形状是否仍为矩形。 106 107**系统能力：** SystemCapability.Graphics.Drawing 108 109**返回值：** 110 111| 类型 | 说明 | 112| --------------------------- | -------------------- | 113| boolean | 返回经过该矩阵映射后的矩形的形状是否仍为矩形。true表示仍是矩形，false表示不是矩形。 | 114 115**示例：** 116 117```ts 118import { drawing } from '@kit.ArkGraphics2D'; 119 120let matrix = new drawing.Matrix(); 121matrix.setMatrix([1, 0.5, 1, 0.5, 1, 1, 1, 1, 1]); 122let matrix2 = new drawing.Matrix(matrix); 123let isRect = matrix2.rectStaysRect(); 124console.info('isRect :', isRect); 125``` 126 127## setSkew<sup>20+</sup> 128 129setSkew(kx: number, ky: number, px: number, py: number): void 130 131设置矩阵的倾斜系数。 132 133**系统能力：** SystemCapability.Graphics.Drawing 134 135**参数：** 136 137| 参数名 | 类型 | 必填 | 说明 | 138| ----------- | ---------------------------------------- | ---- | ------------------- | 139| kx | number | 是 | x轴上的倾斜量，该参数为浮点数。正值会使绘制沿y轴增量方向向右倾斜；负值会使绘制沿y轴增量方向向左倾斜。 | 140| ky | number | 是 | y轴上的倾斜量，该参数为浮点数。正值会使绘制沿x轴增量方向向下倾斜；负值会使绘制沿x轴增量方向向上倾斜。 | 141| px | number | 是 | 倾斜中心点的x轴坐标，该参数为浮点数。0表示坐标原点，正数表示位于坐标原点右侧，负数表示位于坐标原点左侧。 | 142| py | number | 是 | 倾斜中心点的y轴坐标，该参数为浮点数。0表示坐标原点，正数表示位于坐标原点下侧，负数表示位于坐标原点上侧。 | 143 144**示例：** 145 146```ts 147import { drawing } from '@kit.ArkGraphics2D'; 148 149let matrix = new drawing.Matrix(); 150matrix.setMatrix([1, 0.5, 1, 0.5, 1, 1, 1, 1, 1]); 151matrix.setSkew(2, 0.5, 0.5, 2); 152``` 153 154## setSinCos<sup>20+</sup> 155 156setSinCos(sinValue: number, cosValue: number, px: number, py: number): void 157 158设置矩阵，使其围绕旋转中心(px, py)以指定的正弦值和余弦值旋转。 159 160**系统能力：** SystemCapability.Graphics.Drawing 161 162**参数：** 163 164| 参数名 | 类型 | 必填 | 说明 | 165| ----------- | ---------------------------------------- | ---- | ------------------- | 166| sinValue | number | 是 | 旋转角度的正弦值。仅当正弦值和余弦值的平方和为1时，为旋转变换，否则矩阵可能包含平移缩放等其他变换。 | 167| cosValue | number | 是 | 旋转角度的余弦值。仅当正弦值和余弦值的平方和为1时，为旋转变换，否则矩阵可能包含平移缩放等其他变换。 | 168| px | number | 是 | 旋转中心的x轴坐标，该参数为浮点数。0表示坐标原点，正数表示位于坐标原点右侧，负数表示位于坐标原点左侧。 | 169| py | number | 是 | 旋转中心的y轴坐标，该参数为浮点数。0表示坐标原点，正数表示位于坐标原点下侧，负数表示位于坐标原点上侧。 | 170 171**示例：** 172 173```ts 174import { drawing } from '@kit.ArkGraphics2D'; 175 176let matrix = new drawing.Matrix(); 177matrix.setMatrix([1, 0.5, 1, 0.5, 1, 1, 1, 1, 1]); 178matrix.setSinCos(0, 1, 1, 0); 179``` 180## setRotation<sup>12+</sup> 181 182setRotation(degree: number, px: number, py: number): void 183 184设置矩阵为单位矩阵，并围绕位于(px, py)的旋转轴点进行旋转。 185 186**系统能力：** SystemCapability.Graphics.Drawing 187 188**参数：** 189 190| 参数名 | 类型 | 必填 | 说明 | 191| ----------- | ---------------------------------------- | ---- | ------------------- | 192| degree | number | 是 | 角度，单位为度。正数表示顺时针旋转，负数表示逆时针旋转，该参数为浮点数。| 193| px | number | 是 | 旋转轴点的横坐标，该参数为浮点数。 | 194| py | number | 是 | 旋转轴点的纵坐标，该参数为浮点数。 | 195 196**错误码：** 197 198以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 199 200| 错误码ID | 错误信息 | 201| ------- | --------------------------------------------| 202| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 203 204**示例：** 205 206```ts 207import { drawing } from '@kit.ArkGraphics2D'; 208 209let matrix = new drawing.Matrix(); 210matrix.setRotation(90, 100, 100); 211``` 212 213## setScale<sup>12+</sup> 214 215setScale(sx: number, sy: number, px: number, py: number): void 216 217设置矩阵为单位矩阵围绕位于(px, py)的中心点，以sx和sy进行缩放后的结果。 218 219**系统能力：** SystemCapability.Graphics.Drawing 220 221**参数：** 222 223| 参数名 | 类型 | 必填 | 说明 | 224| ----------- | ---------------------------------------- | ---- | ------------------- | 225| sx | number | 是 | x轴方向缩放系数，为负数时可看作是先关于y = px作镜像翻转后再进行缩放，该参数为浮点数。 | 226| sy | number | 是 | y轴方向缩放系数，为负数时可看作是先关于x = py作镜像翻转后再进行缩放，该参数为浮点数。 | 227| px | number | 是 | 缩放中心点的横坐标，该参数为浮点数。 | 228| py | number | 是 | 缩放中心点的纵坐标，该参数为浮点数。 | 229 230**错误码：** 231 232以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 233 234| 错误码ID | 错误信息 | 235| ------- | --------------------------------------------| 236| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 237 238**示例：** 239 240```ts 241import { drawing } from '@kit.ArkGraphics2D'; 242 243let matrix = new drawing.Matrix(); 244matrix.setScale(100, 100, 150, 150); 245``` 246 247## setTranslation<sup>12+</sup> 248 249setTranslation(dx: number, dy: number): void 250 251设置矩阵为单位矩阵平移(dx, dy)后的结果。 252 253**系统能力：** SystemCapability.Graphics.Drawing 254 255**参数：** 256 257| 参数名 | 类型 | 必填 | 说明 | 258| ----------- | ---------------------------------------- | ---- | ------------------- | 259| dx | number | 是 | x轴方向平移距离，正数表示往x轴正方向平移，负数表示往x轴负方向平移，该参数为浮点数。 | 260| dy | number | 是 | y轴方向平移距离，正数表示往y轴正方向平移，负数表示往y轴负方向平移，该参数为浮点数。 | 261 262**错误码：** 263 264以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 265 266| 错误码ID | 错误信息 | 267| ------- | --------------------------------------------| 268| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 269 270**示例：** 271 272```ts 273import { drawing } from '@kit.ArkGraphics2D'; 274 275let matrix = new drawing.Matrix(); 276matrix.setTranslation(100, 100); 277``` 278 279## setMatrix<sup>12+</sup> 280 281setMatrix(values: Array\<number>): void 282 283设置矩阵对象的各项参数。 284 285**系统能力：** SystemCapability.Graphics.Drawing 286 287**参数：** 288 289| 参数名 | 类型 | 必填 | 说明 | 290| ------ | ---------------------------------------------------- | ---- | ---------------- | 291| values | Array\<number> | 是 | 长度为9的浮点数组，表示矩阵对象参数。数组中的值按下标从小，到大分别表示水平缩放系数、水平倾斜系数、水平位移系数、垂直倾斜系数、垂直缩放系数、垂直位移系数、X轴透视系数、Y轴透视系数、透视缩放系数。 | 292 293**错误码：** 294 295以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 296 297| 错误码ID | 错误信息 | 298| ------- | --------------------------------------------| 299| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types; 3. Parameter verification failed. | 300 301**示例：** 302 303```ts 304import { drawing } from '@kit.ArkGraphics2D'; 305 306let matrix = new drawing.Matrix(); 307let value : Array<number> = [2, 2, 2, 2, 2, 2, 2, 2, 2]; 308matrix.setMatrix(value); 309``` 310 311## preConcat<sup>12+</sup> 312 313preConcat(matrix: Matrix): void 314 315将当前矩阵设置为当前矩阵左乘matrix的结果。 316 317**系统能力：** SystemCapability.Graphics.Drawing 318 319**参数：** 320 321| 参数名 | 类型 | 必填 | 说明 | 322| ------ | ---------------------------------------------------- | ---- | ---------------- | 323| matrix | [Matrix](arkts-apis-graphics-drawing-Matrix.md) | 是 | 表示矩阵对象，位于乘法表达式右侧。 | 324 325**错误码：** 326 327以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 328 329| 错误码ID | 错误信息 | 330| ------- | --------------------------------------------| 331| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 332 333**示例：** 334 335```ts 336import { drawing } from '@kit.ArkGraphics2D'; 337 338let matrix1 = new drawing.Matrix(); 339matrix1.setMatrix([2, 1, 3, 1, 2, 1, 3, 1, 2]); 340let matrix2 = new drawing.Matrix(); 341matrix2.setMatrix([-2, 1, 3, 1, 0, -1, 3, -1, 2]); 342matrix1.preConcat(matrix2); 343``` 344 345## setMatrix<sup>20+</sup> 346 347setMatrix(matrix: Array\<number\> \| Matrix): void 348 349用一个矩阵对当前矩阵进行更新。 350 351**系统能力：** SystemCapability.Graphics.Drawing 352 353**参数：** 354 355| 参数名 | 类型 | 必填 | 说明 | 356| ------ | ---------------------------------------------------- | ---- | ---------------- | 357| matrix | Array\<number\> \| [Matrix](arkts-apis-graphics-drawing-Matrix.md) | 是 | 用于更新的数组或矩阵。 | 358 359**示例：** 360 361```ts 362import { drawing } from '@kit.ArkGraphics2D'; 363 364let matrix1 = new drawing.Matrix(); 365matrix1.setMatrix([2, 1, 3, 1, 2, 1, 3, 1, 2]); 366let matrix2 = new drawing.Matrix(); 367matrix1.setMatrix(matrix2); 368``` 369 370## setConcat<sup>20+</sup> 371 372setConcat(matrixA: Matrix, matrixB: Matrix): void 373 374用两个矩阵的乘积更新当前矩阵。 375 376**系统能力：** SystemCapability.Graphics.Drawing 377 378**参数：** 379 380| 参数名 | 类型 | 必填 | 说明 | 381| ------ | ---------------------------------------------------- | ---- | ---------------- | 382| matrixA | [Matrix](arkts-apis-graphics-drawing-Matrix.md) | 是 | 用于运算的矩阵A。 | 383| matrixB | [Matrix](arkts-apis-graphics-drawing-Matrix.md) | 是 | 用于运算的矩阵B。 | 384 385**示例：** 386 387```ts 388import { drawing } from '@kit.ArkGraphics2D'; 389 390let matrix1 = new drawing.Matrix(); 391matrix1.setMatrix([2, 1, 3, 1, 2, 1, 3, 1, 2]); 392let matrix2 = new drawing.Matrix(); 393matrix2.setMatrix([-2, 1, 3, 1, 0, -1, 3, -1, 2]); 394matrix1.setConcat(matrix2, matrix1); 395``` 396 397## postConcat<sup>20+</sup> 398 399postConcat(matrix: Matrix): void 400 401用当前矩阵右乘一个矩阵。 402 403**系统能力：** SystemCapability.Graphics.Drawing 404 405**参数：** 406 407| 参数名 | 类型 | 必填 | 说明 | 408| ------ | ---------------------------------------------------- | ---- | ---------------- | 409| matrix | [Matrix](arkts-apis-graphics-drawing-Matrix.md) | 是 | 用于运算的矩阵。 | 410 411**示例：** 412 413```ts 414import { drawing } from '@kit.ArkGraphics2D'; 415 416let matrix = new drawing.Matrix(); 417if (matrix.isIdentity()) { 418 console.info("matrix is identity."); 419} else { 420 console.info("matrix is not identity."); 421} 422let matrix1 = new drawing.Matrix(); 423matrix1.setMatrix([2, 1, 3, 1, 2, 1, 3, 1, 2]); 424let matrix2 = new drawing.Matrix(); 425matrix2.setMatrix([-2, 1, 3, 1, 0, -1, 3, -1, 2]); 426matrix1.postConcat(matrix2); 427``` 428 429## isEqual<sup>12+</sup> 430 431isEqual(matrix: Matrix): Boolean 432 433判断两个矩阵是否相等。 434 435**系统能力：** SystemCapability.Graphics.Drawing 436 437**参数：** 438 439| 参数名 | 类型 | 必填 | 说明 | 440| ------ | ---------------------------------------------------- | ---- | ---------------- | 441| matrix | [Matrix](arkts-apis-graphics-drawing-Matrix.md) | 是 | 另一个矩阵。 | 442 443**返回值：** 444 445| 类型 | 说明 | 446| --------------------------- | -------------------- | 447| Boolean | 返回两个矩阵的比较结果。true表示两个矩阵相等，false表示两个矩阵不相等。 | 448 449**错误码：** 450 451以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 452 453| 错误码ID | 错误信息 | 454| ------- | --------------------------------------------| 455| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 456 457**示例：** 458 459```ts 460import { drawing } from '@kit.ArkGraphics2D'; 461 462let matrix1 = new drawing.Matrix(); 463matrix1.setMatrix([2, 1, 3, 1, 2, 1, 3, 1, 2]); 464let matrix2 = new drawing.Matrix(); 465matrix2.setMatrix([-2, 1, 3, 1, 0, -1, 3, -1, 2]); 466if (matrix1.isEqual(matrix2)) { 467 console.info("matrix1 and matrix2 are equal."); 468} else { 469 console.info("matrix1 and matrix2 are not equal."); 470} 471``` 472 473## invert<sup>12+</sup> 474 475invert(matrix: Matrix): Boolean 476 477将矩阵matrix设置为当前矩阵的逆矩阵，并返回是否设置成功的结果。 478 479**系统能力：** SystemCapability.Graphics.Drawing 480 481**参数：** 482 483| 参数名 | 类型 | 必填 | 说明 | 484| ------ | ---------------------------------------------------- | ---- | ---------------- | 485| matrix | [Matrix](arkts-apis-graphics-drawing-Matrix.md) | 是 | 矩阵对象，用于存储获取到的逆矩阵。 | 486 487**返回值：** 488 489| 类型 | 说明 | 490| --------------------------- | -------------------- | 491| Boolean | 返回matrix是否被设置为逆矩阵的结果。true表示当前矩阵可逆，matrix被设置为逆矩阵，false表示当前矩阵不可逆，matrix不被设置。 | 492 493**错误码：** 494 495以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 496 497| 错误码ID | 错误信息 | 498| ------- | --------------------------------------------| 499| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 500 501**示例：** 502 503```ts 504import { drawing } from '@kit.ArkGraphics2D'; 505 506let matrix1 = new drawing.Matrix(); 507matrix1.setMatrix([2, 1, 3, 1, 2, 1, 3, 1, 2]); 508let matrix2 = new drawing.Matrix(); 509matrix2.setMatrix([-2, 1, 3, 1, 0, -1, 3, -1, 2]); 510if (matrix1.invert(matrix2)) { 511 console.info("matrix1 is invertible and matrix2 is set as an inverse matrix of the matrix1."); 512} else { 513 console.info("matrix1 is not invertible and matrix2 is not changed."); 514} 515``` 516 517## isIdentity<sup>12+</sup> 518 519isIdentity(): Boolean 520 521判断矩阵是否是单位矩阵。 522 523**系统能力：** SystemCapability.Graphics.Drawing 524 525**返回值：** 526 527| 类型 | 说明 | 528| --------------------------- | -------------------- | 529| Boolean | 返回矩阵是否是单位矩阵。true表示矩阵是单位矩阵，false表示矩阵不是单位矩阵。 | 530 531**示例：** 532 533```ts 534import { drawing } from '@kit.ArkGraphics2D'; 535 536let matrix = new drawing.Matrix(); 537if (matrix.isIdentity()) { 538 console.info("matrix is identity."); 539} else { 540 console.info("matrix is not identity."); 541} 542``` 543 544## getValue<sup>12+</sup> 545 546getValue(index: number): number 547 548获取矩阵给定索引位的值。索引范围0-8。 549 550**系统能力：** SystemCapability.Graphics.Drawing 551 552**参数：** 553 554| 参数名 | 类型 | 必填 | 说明 | 555| --------------- | ------- | ---- | ----------------------------------------------------------- | 556| index | number | 是 | 索引位置，范围0-8，该参数为整数。 | 557 558**返回值：** 559 560| 类型 | 说明 | 561| --------------------- | -------------- | 562| number | 函数返回矩阵给定索引位对应的值，该返回值为整数。 | 563 564**错误码：** 565 566以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 567 568| 错误码ID | 错误信息 | 569| ------- | --------------------------------------------| 570| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed.| 571 572**示例：** 573 574```ts 575import {drawing} from "@kit.ArkGraphics2D"; 576 577let matrix = new drawing.Matrix(); 578for (let i = 0; i < 9; i++) { 579 console.info("matrix "+matrix.getValue(i).toString()); 580} 581``` 582 583## postRotate<sup>12+</sup> 584 585postRotate(degree: number, px: number, py: number): void 586 587将矩阵设置为矩阵右乘围绕轴心点旋转一定角度的单位矩阵后得到的矩阵。 588 589**系统能力：** SystemCapability.Graphics.Drawing 590 591**参数：** 592 593| 参数名 | 类型 | 必填 | 说明 | 594| --------------- | ------- | ---- | ----------------------------------------------------------- | 595| degree | number | 是 | 旋转角度，单位为度。正数表示顺时针旋转，负数表示逆时针旋转，该参数为浮点数。 | 596| px | number | 是 | 旋转中心点的横坐标，该参数为浮点数。 | 597| py | number | 是 | 旋转中心点的纵坐标，该参数为浮点数。 | 598 599**错误码：** 600 601以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 602 603| 错误码ID | 错误信息 | 604| ------- | --------------------------------------------| 605| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 606 607**示例：** 608 609```ts 610import {drawing} from "@kit.ArkGraphics2D"; 611 612let matrix = new drawing.Matrix(); 613let degree: number = 2; 614let px: number = 3; 615let py: number = 4; 616matrix.postRotate(degree, px, py); 617console.info("matrix= "+matrix.getAll().toString()); 618``` 619 620## postScale<sup>12+</sup> 621 622postScale(sx: number, sy: number, px: number, py: number): void 623 624将矩阵设置为矩阵右乘围绕轴心点按一定缩放系数缩放后的单位矩阵后得到的矩阵。 625 626**系统能力：** SystemCapability.Graphics.Drawing 627 628**参数：** 629 630| 参数名 | 类型 | 必填 | 说明 | 631| --------------- | ------- | ---- | ----------------------------------------------------------- | 632| sx | number | 是 | x轴方向缩放系数，负数表示先关于y = px作镜像翻转后再进行缩放，该参数为浮点数。 | 633| sy | number | 是 | y轴方向缩放系数，负数表示先关于x = py作镜像翻转后再进行缩放，该参数为浮点数。 | 634| px | number | 是 | 缩放中心点的横坐标，该参数为浮点数。 | 635| py | number | 是 | 缩放中心点的纵坐标，该参数为浮点数。 | 636 637**错误码：** 638 639以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 640 641| 错误码ID | 错误信息 | 642| ------- | --------------------------------------------| 643| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 644 645**示例：** 646 647```ts 648import {drawing} from "@kit.ArkGraphics2D"; 649 650let matrix = new drawing.Matrix(); 651let sx: number = 2; 652let sy: number = 0.5; 653let px: number = 1; 654let py: number = 1; 655matrix.postScale(sx, sy, px, py); 656console.info("matrix= "+matrix.getAll().toString()); 657``` 658 659## postTranslate<sup>12+</sup> 660 661postTranslate(dx: number, dy: number): void 662 663将矩阵设置为矩阵右乘平移一定距离后的单位矩阵后得到的矩阵。 664 665**系统能力：** SystemCapability.Graphics.Drawing 666 667**参数：** 668 669| 参数名 | 类型 | 必填 | 说明 | 670| --------------- | ------- | ---- | ----------------------------------------------------------- | 671| dx | number | 是 | x轴方向平移距离，正数表示往x轴正方向平移，负数表示往x轴负方向平移，该参数为浮点数。 | 672| dy | number | 是 | y轴方向平移距离，正数表示往y轴正方向平移，负数表示往y轴负方向平移，该参数为浮点数。 | 673 674**错误码：** 675 676以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 677 678| 错误码ID | 错误信息 | 679| ------- | --------------------------------------------| 680| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 681 682**示例：** 683 684```ts 685import {drawing} from "@kit.ArkGraphics2D"; 686 687let matrix = new drawing.Matrix(); 688let dx: number = 3; 689let dy: number = 4; 690matrix.postTranslate(dx, dy); 691console.info("matrix= "+matrix.getAll().toString()); 692``` 693 694## preRotate<sup>12+</sup> 695 696preRotate(degree: number, px: number, py: number): void 697 698将矩阵设置为矩阵左乘围绕轴心点旋转一定角度的单位矩阵后得到的矩阵。 699 700**系统能力：** SystemCapability.Graphics.Drawing 701 702**参数：** 703 704| 参数名 | 类型 | 必填 | 说明 | 705| --------------- | ------- | ---- | ----------------------------------------------------------- | 706| degree | number | 是 | 旋转角度，单位为度。正数表示顺时针旋转，负数表示逆时针旋转，该参数为浮点数。 | 707| px | number | 是 | 旋转中心点的横坐标，该参数为浮点数。 | 708| py | number | 是 | 旋转中心点的纵坐标，该参数为浮点数。 | 709 710**错误码：** 711 712以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 713 714| 错误码ID | 错误信息 | 715| ------- | --------------------------------------------| 716| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 717 718**示例：** 719 720```ts 721import {drawing} from "@kit.ArkGraphics2D"; 722 723let matrix = new drawing.Matrix(); 724let degree: number = 2; 725let px: number = 3; 726let py: number = 4; 727matrix.preRotate(degree, px, py); 728console.info("matrix= "+matrix.getAll().toString()); 729``` 730 731## postSkew<sup>20+</sup> 732 733postSkew(kx: number, ky: number, px: number, py: number): void 734 735当前矩阵右乘一个倾斜变换矩阵。 736 737**系统能力：** SystemCapability.Graphics.Drawing 738 739**参数：** 740 741| 参数名 | 类型 | 必填 | 说明 | 742| ----------- | ---------------------------------------- | ---- | ------------------- | 743| kx | number | 是 | x轴上的倾斜量，该参数为浮点数。正值会使绘制沿y轴增量方向向右倾斜；负值会使绘制沿y轴增量方向向左倾斜。 | 744| ky | number | 是 | y轴上的倾斜量，该参数为浮点数。正值会使绘制沿x轴增量方向向下倾斜；负值会使绘制沿x轴增量方向向上倾斜。 | 745| px | number | 是 | 倾斜中心点的x轴坐标，该参数为浮点数。0表示坐标原点，正数表示位于坐标原点右侧，负数表示位于坐标原点左侧。 | 746| py | number | 是 | 倾斜中心点的y轴坐标，该参数为浮点数。0表示坐标原点，正数表示位于坐标原点下侧，负数表示位于坐标原点上侧。 | 747 748**示例：** 749 750```ts 751import {drawing} from "@kit.ArkGraphics2D" 752let matrix = new drawing.Matrix(); 753matrix.postSkew(2.0, 1.0, 2.0, 1.0); 754``` 755 756## preSkew<sup>20+</sup> 757 758 preSkew(kx: number, ky: number, px: number, py: number): void 759 760当前矩阵左乘一个倾斜变换矩阵。 761 762**系统能力：** SystemCapability.Graphics.Drawing 763 764**参数：** 765 766| 参数名 | 类型 | 必填 | 说明 | 767| ----------- | ---------------------------------------- | ---- | ------------------- | 768| kx | number | 是 | x轴上的倾斜量，该参数为浮点数。正值会使绘制沿y轴增量方向向右倾斜；负值会使绘制沿y轴增量方向向左倾斜。 | 769| ky | number | 是 | y轴上的倾斜量，该参数为浮点数。正值会使绘制沿x轴增量方向向下倾斜；负值会使绘制沿x轴增量方向向上倾斜。 | 770| px | number | 是 | 倾斜中心点的x轴坐标，该参数为浮点数。0表示坐标原点，正数表示位于坐标原点右侧，负数表示位于坐标原点左侧。 | 771| py | number | 是 | 倾斜中心点的y轴坐标，该参数为浮点数。0表示坐标原点，正数表示位于坐标原点下侧，负数表示位于坐标原点上侧。 | 772 773**示例：** 774 775```ts 776import {drawing} from "@kit.ArkGraphics2D" 777let matrix = new drawing.Matrix(); 778matrix.preSkew(2.0, 1.0, 2.0, 1.0); 779``` 780 781## mapRadius<sup>20+</sup> 782 783mapRadius(radius: number): number 784 785返回半径为radius的圆经过当前矩阵映射形成的椭圆的平均半径。平均半径的平方为椭圆长轴长度和短轴长度的乘积。若当前矩阵包含透视变换，则该结果无意义。 786 787**系统能力：** SystemCapability.Graphics.Drawing 788 789**参数：** 790 791| 参数名 | 类型 | 必填 | 说明 | 792| ------ | ---------------------------------------------------- | ---- | ---------------- | 793| radius | number | 是 | 用于计算的圆的半径，浮点数。如果是负数，则按照绝对值进行计算。 | 794 795**返回值：** 796 797| 类型 | 说明 | 798| --------------------------- | -------------------- | 799| number | 返回经过变换之后的平均半径。 | 800 801**示例：** 802 803```ts 804import {drawing} from "@kit.ArkGraphics2D" 805 806let matrix = new drawing.Matrix(); 807matrix.setMatrix([2, 1, 3, 1, 2, 1, 3, 1, 2]); 808let radius = matrix.mapRadius(10); 809console.info('radius', radius); 810``` 811 812## preScale<sup>12+</sup> 813 814preScale(sx: number, sy: number, px: number, py: number): void 815 816将矩阵设置为矩阵左乘围绕轴心点按一定缩放系数缩放后的单位矩阵后得到的矩阵。 817 818**系统能力：** SystemCapability.Graphics.Drawing 819 820**参数：** 821 822| 参数名 | 类型 | 必填 | 说明 | 823| --------------- | ------- | ---- | ----------------------------------------------------------- | 824| sx | number | 是 | x轴方向缩放系数，为负数时可看作是先关于y = px作镜像翻转后再进行缩放，该参数为浮点数。 | 825| sy | number | 是 | y轴方向缩放系数，为负数时可看作是先关于x = py作镜像翻转后再进行缩放，该参数为浮点数。 | 826| px | number | 是 | 轴心点横坐标，该参数为浮点数。 | 827| py | number | 是 | 轴心点纵坐标，该参数为浮点数。 | 828 829**错误码：** 830 831以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 832 833| 错误码ID | 错误信息 | 834| ------- | --------------------------------------------| 835| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 836 837**示例：** 838 839```ts 840import {drawing} from "@kit.ArkGraphics2D"; 841 842let matrix = new drawing.Matrix(); 843let sx: number = 2; 844let sy: number = 0.5; 845let px: number = 1; 846let py: number = 1; 847matrix.preScale(sx, sy, px, py); 848console.info("matrix"+matrix.getAll().toString()); 849``` 850 851## preTranslate<sup>12+</sup> 852 853preTranslate(dx: number, dy: number): void 854 855将矩阵设置为矩阵左乘平移一定距离后的单位矩阵后得到的矩阵。 856 857**系统能力：** SystemCapability.Graphics.Drawing 858 859**参数：** 860 861| 参数名 | 类型 | 必填 | 说明 | 862| --------------- | ------- | ---- | ----------------------------------------------------------- | 863| dx | number | 是 | x轴方向平移距离，正数表示往x轴正方向平移，负数表示往x轴负方向平移，该参数为浮点数。 | 864| dy | number | 是 | y轴方向平移距离，正数表示往y轴正方向平移，负数表示往y轴负方向平移，该参数为浮点数。 | 865 866**错误码：** 867 868以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 869 870| 错误码ID | 错误信息 | 871| ------- | --------------------------------------------| 872| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 873 874**示例：** 875 876```ts 877import {drawing} from "@kit.ArkGraphics2D"; 878 879let matrix = new drawing.Matrix(); 880let dx: number = 3; 881let dy: number = 4; 882matrix.preTranslate(dx, dy); 883console.info("matrix"+matrix.getAll().toString()); 884``` 885 886## reset<sup>12+</sup> 887 888reset(): void 889 890重置当前矩阵为单位矩阵。 891 892**系统能力：** SystemCapability.Graphics.Drawing 893 894**示例：** 895 896```ts 897import {drawing} from "@kit.ArkGraphics2D"; 898 899let matrix = new drawing.Matrix(); 900matrix.postScale(2, 3, 4, 5); 901matrix.reset(); 902console.info("matrix= "+matrix.getAll().toString()); 903``` 904 905## mapPoints<sup>12+</sup> 906 907mapPoints(src: Array\<common2D.Point>): Array\<common2D.Point> 908 909通过矩阵变换将源点数组映射到目标点数组。 910 911**系统能力：** SystemCapability.Graphics.Drawing 912 913**参数：** 914 915| 参数名 | 类型 | 必填 | 说明 | 916| --------------- | ------- | ---- | ----------------------------------------------------------- | 917| src | Array\<[common2D.Point](js-apis-graphics-common2D.md#point12)> | 是 | 源点数组。 | 918 919**返回值：** 920 921| 类型 | 说明 | 922| --------------------- | -------------- | 923| Array\<[common2D.Point](js-apis-graphics-common2D.md#point12)> | 源点数组经矩阵变换后的点数组。 | 924 925**错误码：** 926 927以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 928 929| 错误码ID | 错误信息 | 930| ------- | --------------------------------------------| 931| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 932 933**示例：** 934 935```ts 936import {drawing,common2D} from "@kit.ArkGraphics2D"; 937 938let src: Array<common2D.Point> = []; 939src.push({x: 15, y: 20}); 940src.push({x: 20, y: 15}); 941src.push({x: 30, y: 10}); 942let matrix = new drawing.Matrix(); 943let dst: Array<common2D.Point> = matrix.mapPoints(src); 944console.info("matrix= src: "+JSON.stringify(src)); 945console.info("matrix= dst: "+JSON.stringify(dst)); 946``` 947 948## getAll<sup>12+</sup> 949 950getAll(): Array\<number> 951 952获取矩阵的所有元素值。 953 954**系统能力：** SystemCapability.Graphics.Drawing 955 956**返回值：** 957 958| 类型 | 说明 | 959| --------------------- | -------------- | 960| Array\<number> | 存储矩阵元素值的浮点数组，长度为9。 | 961 962**示例：** 963 964```ts 965import {drawing} from "@kit.ArkGraphics2D"; 966 967let matrix = new drawing.Matrix(); 968console.info("matrix "+ matrix.getAll()); 969``` 970 971## mapRect<sup>12+</sup> 972 973mapRect(dst: common2D.Rect, src: common2D.Rect): boolean 974 975将目标矩形设置为源矩形通过矩阵变换后的图形的外接矩形。如下图所示，蓝色矩形为源矩形，假设黄色矩形为源矩形通过矩阵变换形成的图形，此时黄色矩形的边不与坐标轴平行，无法使用矩形对象表示，因此，将目标矩形设置为黄色矩形的外接矩形，即黑色矩形。 976 977 978 979**系统能力：** SystemCapability.Graphics.Drawing 980 981**参数：** 982 983| 参数名 | 类型 | 必填 | 说明 | 984| --------------- | ------- | ---- | ----------------------------------------------------------- | 985| dst | [common2D.Rect](js-apis-graphics-common2D.md#rect) | 是 | 目标矩形对象，用于存储源矩形经矩阵变换后的图形的外接矩形。 | 986| src |[common2D.Rect](js-apis-graphics-common2D.md#rect) | 是 | 源矩形对象。 | 987 988**返回值：** 989 990| 类型 | 说明 | 991| --------------------- | -------------- | 992| boolean | 返回源矩形经过矩阵变换后的图形是否仍然是矩形，true表示是矩形，false表示不是矩形。 | 993 994**错误码：** 995 996以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 997 998| 错误码ID | 错误信息 | 999| ------- | --------------------------------------------| 1000| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 1001 1002**示例：** 1003 1004```ts 1005import {drawing,common2D} from "@kit.ArkGraphics2D"; 1006 1007let dst: common2D.Rect = { left: 100, top: 20, right: 130, bottom: 60 }; 1008let src: common2D.Rect = { left: 100, top: 80, right: 130, bottom: 120 }; 1009let matrix = new drawing.Matrix(); 1010if (matrix.mapRect(dst, src)) { 1011 console.info("matrix= dst "+JSON.stringify(dst)); 1012} 1013``` 1014 1015## setRectToRect<sup>12+</sup> 1016 1017setRectToRect(src: common2D.Rect, dst: common2D.Rect, scaleToFit: ScaleToFit): boolean 1018 1019将当前矩阵设置为能使源矩形映射到目标矩形的变换矩阵。 1020 1021**系统能力：** SystemCapability.Graphics.Drawing 1022 1023**参数：** 1024 1025| 参数名 | 类型 | 必填 | 说明 | 1026| --------------- | ------- | ---- | ----------------------------------------------------------- | 1027| src | [common2D.Rect](js-apis-graphics-common2D.md#rect) | 是 | 源矩形。 | 1028| dst | [common2D.Rect](js-apis-graphics-common2D.md#rect) | 是 | 目标矩形。 | 1029| scaleToFit | [ScaleToFit](arkts-apis-graphics-drawing-e.md#scaletofit12) | 是 | 源矩形到目标矩形的映射方式。 | 1030 1031**返回值：** 1032 1033| 类型 | 说明 | 1034| --------------------- | -------------- | 1035| boolean | 返回矩阵是否可以表示矩形之间的映射，true表示可以，false表示不可以。如果源矩形的宽高任意一个小于等于0，则返回false，并将矩阵设置为单位矩阵；如果目标矩形的宽高任意一个小于等于0，则返回true，并将矩阵设置为除透视缩放系数为1外其余值皆为0的矩阵。 | 1036 1037**错误码：** 1038 1039以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1040 1041| 错误码ID | 错误信息 | 1042| ------- | --------------------------------------------| 1043| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. | 1044 1045**示例：** 1046 1047```ts 1048import {drawing,common2D} from "@kit.ArkGraphics2D"; 1049 1050let src: common2D.Rect = { left: 100, top: 100, right: 300, bottom: 300 }; 1051let dst: common2D.Rect = { left: 200, top: 200, right: 600, bottom: 600 }; 1052let scaleToFit: drawing.ScaleToFit = drawing.ScaleToFit.FILL_SCALE_TO_FIT 1053let matrix = new drawing.Matrix(); 1054if (matrix.setRectToRect(src, dst, scaleToFit)) { 1055 console.info("matrix"+matrix.getAll().toString()); 1056} 1057``` 1058 1059## setPolyToPoly<sup>12+</sup> 1060 1061setPolyToPoly(src: Array\<common2D.Point>, dst: Array\<common2D.Point>, count: number): boolean 1062 1063将当前矩阵设置为能够将源点数组映射到目标点数组的变换矩阵。源点和目标点的个数必须大于等于0，小于等于4。 1064 1065**系统能力：** SystemCapability.Graphics.Drawing 1066 1067**参数：** 1068 1069| 参数名 | 类型 | 必填 | 说明 | 1070| --------------- | ------- | ---- | ----------------------------------------------------------- | 1071| src | Array\<[common2D.Point](js-apis-graphics-common2D.md#point12)> | 是 | 源点数组，长度必须为count。 | 1072| dst | Array\<[common2D.Point](js-apis-graphics-common2D.md#point12)> | 是 | 目标点数组，长度必须为count。 | 1073| count | number | 是 | 在src和dst点的数量，该参数为整数。 | 1074 1075**返回值：** 1076 1077| 类型 | 说明 | 1078| --------------------- | -------------- | 1079| boolean | 返回设置矩阵是否成功的结果，true表示设置成功，false表示设置失败。 | 1080 1081**错误码：** 1082 1083以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1084 1085| 错误码ID | 错误信息 | 1086| ------- | --------------------------------------------| 1087| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 1088 1089**示例：** 1090 1091```ts 1092import {drawing,common2D} from "@kit.ArkGraphics2D"; 1093 1094let srcPoints: Array<common2D.Point> = [ {x: 10, y: 20}, {x: 200, y: 150} ]; 1095let dstPoints: Array<common2D.Point> = [{ x:0, y: 10 }, { x:300, y: 600 }]; 1096let matrix = new drawing.Matrix(); 1097if (matrix.setPolyToPoly(srcPoints, dstPoints, 2)) { 1098 console.info("matrix"+matrix.getAll().toString()); 1099} 1100```
