1# @ohos.matrix4 (矩阵变换) 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @CCFFWW--> 5<!--Designer: @yangfan229--> 6<!--Tester: @lxl007--> 7<!--Adviser: @HelloCrease--> 8 9本模块提供矩阵变换功能，支持对图形进行平移、旋转和缩放等。 10 11> **说明：** 12> 13> 本模块首批接口从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14 15 16## 导入模块 17 18```ts 19import { matrix4 } from '@kit.ArkUI'; 20``` 21 22 23## matrix4.init 24 25init(options: [number,number,number,number,number,number,number,number,number,number,number,number,number,number,number,number]): Matrix4Transit 26 27Matrix的构造函数，可以通过传入的参数创建一个四阶矩阵，矩阵为列优先。 28 29**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 30 31**系统能力：** SystemCapability.ArkUI.ArkUI.Full 32 33**参数：** 34 35| 参数名 | 类型 | 必填 | 说明 | 36| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 37| options | [number,number,number,number,<br/>number,number,number,number,<br/>number,number,number,number,<br/>number,number,number,number] | 是 | 参数为长度为16（4\*4）的number数组, 详情见四阶矩阵说明。<br/>各number取值范围：(-∞, +∞)<br/>默认值：<br/>[1, 0, 0, 0,<br/>0, 1, 0, 0,<br/>0, 0, 1, 0,<br/>0, 0, 0, 1] | 38 39**返回值：** 40 41| 类型 | 说明 | 42| --------------------------------- | ---------------------------- | 43| [Matrix4Transit](#matrix4transit) | 根据入参创建的四阶矩阵对象。 | 44 45**四阶矩阵说明：** 46 47| 参数名 | 类型 | 必填 | 说明 | 48| ---- | ------ | ---- | -------------------- | 49| m00 | number | 是 | x轴缩放值，单位矩阵默认为1。 | 50| m01 | number | 是 | 第2个值，xyz轴旋转或倾斜会影响这个值。 | 51| m02 | number | 是 | 第3个值，xyz轴旋转会影响这个值。 | 52| m03 | number | 是 | 第4个值，透视投影会影响这个值。 | 53| m10 | number | 是 | 第5个值，xyz轴旋转或倾斜会影响这个值。 | 54| m11 | number | 是 | y轴缩放值，单位矩阵默认为1。 | 55| m12 | number | 是 | 第7个值，xyz轴旋转会影响这个值。 | 56| m13 | number | 是 | 第8个值，透视投影会影响这个值。 | 57| m20 | number | 是 | 第9个值，xyz轴旋转会影响这个值。 | 58| m21 | number | 是 | 第10个值，xyz轴旋转会影响这个值。 | 59| m22 | number | 是 | z轴缩放值，单位矩阵默认为1。 | 60| m23 | number | 是 | 第12个值，透视投影会影响这个值。 | 61| m30 | number | 是 | x轴平移值，单位px，单位矩阵默认为0。 | 62| m31 | number | 是 | y轴平移值，单位px，单位矩阵默认为0。 | 63| m32 | number | 是 | z轴平移值，单位px，单位矩阵默认为0。 | 64| m33 | number | 是 | 齐次坐标下生效，产生透视投影效果。 | 65 66**示例** 67 68```ts 69import { matrix4 } from '@kit.ArkUI'; 70 71// 创建一个四阶矩阵 72let matrix = matrix4.init( 73 [1.0, 0.0, 0.0, 0.0, 74 0.0, 1.0, 0.0, 0.0, 75 0.0, 0.0, 1.0, 0.0, 76 0.0, 0.0, 0.0, 1.0]); 77 78@Entry 79@Component 80struct Tests { 81 build() { 82 Column() { 83 // $r("app.media.zh")需要替换为开发者所需的图像资源文件。 84 Image($r("app.media.zh")) 85 .width("40%") 86 .height(100) 87 .transform(matrix) 88 } 89 } 90} 91``` 92 93 94## matrix4.identity 95 96identity(): Matrix4Transit 97 98Matrix的初始化函数，可以返回一个单位矩阵对象。 99 100**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 101 102**系统能力：** SystemCapability.ArkUI.ArkUI.Full 103 104**返回值：** 105 106| 类型 | 说明 | 107| --------------------------------- | -------------- | 108| [Matrix4Transit](#matrix4transit) | 单位矩阵对象。 | 109 110**示例：** 111 112```ts 113// matrix1 和 matrix2 效果一致 114import { matrix4 } from '@kit.ArkUI'; 115 116let matrix1 = matrix4.init( 117 [1.0, 0.0, 0.0, 0.0, 118 0.0, 1.0, 0.0, 0.0, 119 0.0, 0.0, 1.0, 0.0, 120 0.0, 0.0, 0.0, 1.0]); 121let matrix2 = matrix4.identity(); 122 123@Entry 124@Component 125struct Tests { 126 build() { 127 Column() { 128 // $r("app.media.zh")需要替换为开发者所需的图像资源文件。 129 Image($r("app.media.zh")) 130 .width("40%") 131 .height(100) 132 .transform(matrix1) 133 // $r("app.media.zh")需要替换为开发者所需的图像资源文件。 134 Image($r("app.media.zh")) 135 .width("40%") 136 .height(100) 137 .margin({ top: 150 }) 138 .transform(matrix2) 139 } 140 } 141} 142``` 143 144## Matrix4Transit 145 146矩阵对象。 147 148**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 149 150**系统能力：** SystemCapability.ArkUI.ArkUI.Full 151 152### copy 153 154copy(): Matrix4Transit 155 156Matrix的拷贝函数，可以拷贝一份当前的矩阵对象。 157 158**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 159 160**系统能力：** SystemCapability.ArkUI.ArkUI.Full 161 162**返回值：** 163 164| 类型 | 说明 | 165| --------------------------------- | -------------------- | 166| [Matrix4Transit](#matrix4transit) | 当前矩阵的拷贝对象。 | 167 168 169**示例：** 170 171```ts 172// xxx.ets 173import { matrix4 } from '@kit.ArkUI'; 174 175@Entry 176@Component 177struct Test { 178 private matrix1 = matrix4.identity().scale({ x: 1.5 }); 179 private matrix2 = this.matrix1.copy().translate({ x: 200 }); 180 imageSize: Length = '300px'; 181 182 build() { 183 Column({ space: "50px" }) { 184 // $r("app.media.testImage")需要替换为开发者所需的图像资源文件。 185 Image($r("app.media.testImage")) 186 .width(this.imageSize) 187 .height(this.imageSize) 188 // $r("app.media.testImage")需要替换为开发者所需的图像资源文件。 189 Image($r("app.media.testImage")) 190 .width(this.imageSize) 191 .height(this.imageSize) 192 .transform(this.matrix1) 193 // $r("app.media.testImage")需要替换为开发者所需的图像资源文件。 194 Image($r("app.media.testImage")) 195 .width(this.imageSize) 196 .height(this.imageSize) 197 .transform(this.matrix2) 198 }.alignItems(HorizontalAlign.Center) 199 .height('100%').width("100%") 200 .justifyContent(FlexAlign.Center) 201 } 202} 203``` 204 205 206### combine 207 208combine(options: Matrix4Transit): Matrix4Transit 209 210Matrix的叠加函数，可以将两个矩阵的效果叠加起来生成一个新的矩阵对象。会改变调用该函数的原始矩阵。 211 212**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 213 214**系统能力：** SystemCapability.ArkUI.ArkUI.Full 215 216**参数：** 217 218| 参数名 | 类型 | 必填 | 说明 | 219| ------ | --------------------------------- | ---- | ------------------ | 220| options | [Matrix4Transit](#matrix4transit) | 是 | 待叠加的矩阵对象。 | 221 222**返回值：** 223 224| 类型 | 说明 | 225| --------------------------------- | ------------------ | 226| [Matrix4Transit](#matrix4transit) | 矩阵叠加后的对象。 | 227 228**示例：** 229 230```ts 231// xxx.ets 232import { matrix4 } from '@kit.ArkUI'; 233 234@Entry 235@Component 236struct Test { 237 private matrix1 = matrix4.identity().translate({ x: 200 }); 238 private matrix2 = matrix4.identity().scale({ x: 2 }); 239 240 build() { 241 Column() { 242 // 矩阵变换前 243 // $r("app.media.icon")需要替换为开发者所需的图像资源文件。 244 Image($r("app.media.icon")) 245 .width("40%") 246 .height(100) 247 .margin({ top: 50 }) 248 // 先平移x轴200px，再缩放两倍x轴，得到矩阵变换后的效果图 249 // $r("app.media.icon")需要替换为开发者所需的图像资源文件。 250 Image($r("app.media.icon")) 251 .transform(this.matrix1.copy().combine(this.matrix2)) 252 .width("40%") 253 .height(100) 254 .margin({ top: 50 }) 255 } 256 } 257} 258``` 259 260 261 262 263### invert 264 265invert(): Matrix4Transit 266 267Matrix的逆函数，可以返回一个当前矩阵对象的逆矩阵，即效果正好相反。会改变调用该函数的原始矩阵。 268 269**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 270 271**系统能力：** SystemCapability.ArkUI.ArkUI.Full 272 273**返回值：** 274 275| 类型 | 说明 | 276| --------------------------------- | ---------------------- | 277| [Matrix4Transit](#matrix4transit) | 当前矩阵的逆矩阵对象。 | 278 279**示例：** 280 281```ts 282import { matrix4 } from '@kit.ArkUI'; 283 284// matrix1(宽放大2倍) 和 matrix2(宽缩小2倍) 效果相反 285let matrix1 = matrix4.identity().scale({ x: 2 }); 286let matrix2 = matrix1.copy().invert(); 287 288@Entry 289@Component 290struct Tests { 291 build() { 292 Column() { 293 // $r("app.media.zh")需要替换为开发者所需的图像资源文件。 294 Image($r("app.media.zh")) 295 .width(200) 296 .height(100) 297 .transform(matrix1) 298 .margin({ top: 100 }) 299 // $r("app.media.zh")需要替换为开发者所需的图像资源文件。 300 Image($r("app.media.zh")) 301 .width(200) 302 .height(100) 303 .margin({ top: 150 }) 304 .transform(matrix2) 305 } 306 } 307} 308``` 309 310 311### translate 312 313translate(options: TranslateOption): Matrix4Transit 314 315Matrix的平移函数，可以为当前矩阵增加x轴/y轴/z轴平移效果。会改变调用该函数的原始矩阵。 316 317**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 318 319**系统能力：** SystemCapability.ArkUI.ArkUI.Full 320 321**参数：** 322 323| 参数名 | 类型 | 必填 | 说明 | 324| ------ | ----------------------------------- | ---- | -------------- | 325| options | [TranslateOption](#translateoption) | 是 | 设置平移参数。 | 326 327**返回值：** 328 329| 类型 | 说明 | 330| --------------------------------- | ---------------------------- | 331| [Matrix4Transit](#matrix4transit) | 平移效果后的矩阵对象。 | 332 333**示例：** 334 335```ts 336// xxx.ets 337import { matrix4 } from '@kit.ArkUI'; 338 339@Entry 340@Component 341struct Test { 342 private matrix1 = matrix4.identity().translate({ x: 100, y: 200, z: 30 }); 343 344 build() { 345 Column() { 346 // $r("app.media.bg1")需要替换为开发者所需的图像资源文件。 347 Image($r("app.media.bg1")).transform(this.matrix1) 348 .width("40%") 349 .height(100) 350 } 351 } 352} 353``` 354 355 356 357 358### scale 359 360scale(options: ScaleOption): Matrix4Transit 361 362Matrix的缩放函数，可以为当前矩阵增加x轴/y轴/z轴缩放效果。会改变调用该函数的原始矩阵。 363 364**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 365 366**系统能力：** SystemCapability.ArkUI.ArkUI.Full 367 368**参数：** 369 370| 参数名 | 类型 | 必填 | 说明 | 371| ------ | --------------------------- | ---- | -------------- | 372| options | [ScaleOption](#scaleoption) | 是 | 设置缩放参数。 | 373 374**返回值：** 375 376| 类型 | 说明 | 377| --------------------------------- | ---------------------------- | 378| [Matrix4Transit](#matrix4transit) | 缩放效果后的矩阵对象。 | 379 380**示例：** 381 382```ts 383// xxx.ets 384import { matrix4 } from '@kit.ArkUI'; 385 386@Entry 387@Component 388struct Test { 389 private matrix1 = matrix4.identity() 390 .scale({ 391 x: 2, 392 y: 3, 393 z: 4, 394 centerX: 50, 395 centerY: 50 396 }); 397 398 build() { 399 Column() { 400 // $r("app.media.testImage")需要替换为开发者所需的图像资源文件。 401 Image($r("app.media.testImage")).transform(this.matrix1) 402 .width("300px") 403 .height("300px") 404 }.width("100%").height("100%").justifyContent(FlexAlign.Center) 405 } 406} 407``` 408 409 410 411 412### skew<sup>12+</sup> 413 414skew(x: number, y: number): Matrix4Transit 415 416Matrix的倾斜函数，可以为当前矩阵增加x轴/y轴倾斜效果。会改变调用该函数的原始矩阵。 417 418**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 419 420**系统能力：** SystemCapability.ArkUI.ArkUI.Full 421 422**参数：** 423 424| 参数名 | 类型 | 必填 | 说明 | 425| ------ | --------------------------- | ---- | -------------- | 426| x | number | 是 | 设置x轴倾斜参数。 | 427| y | number | 是 | 设置y轴倾斜参数。 | 428 429**返回值：** 430 431| 类型 | 说明 | 432| --------------------------------- | ---------------------------- | 433| [Matrix4Transit](#matrix4transit) | 倾斜效果后的矩阵对象。 | 434 435**示例：** 436 437```ts 438// xxx.ets 439import { matrix4 } from '@kit.ArkUI'; 440 441@Entry 442@Component 443struct Test { 444 private matrix1 = matrix4.identity().skew(2, 3); 445 446 build() { 447 Column() { 448 // $r("app.media.bg1")需要替换为开发者所需的图像资源文件。 449 Image($r("app.media.bg1")).transform(this.matrix1) 450 .height(100) 451 .margin({ 452 top: 300 453 }) 454 } 455 .width("100%") 456 .height("100%") 457 } 458} 459``` 460 461 462 463 464### rotate 465 466rotate(options: RotateOption): Matrix4Transit 467 468Matrix的旋转函数，可以为当前矩阵增加x轴/y轴/z轴旋转效果。会改变调用该函数的原始矩阵。 469 470**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 471 472**系统能力：** SystemCapability.ArkUI.ArkUI.Full 473 474**参数：** 475 476| 参数名 | 类型 | 必填 | 说明 | 477| ------ | ----------------------------- | ---- | -------------- | 478| options | [RotateOption](#rotateoption) | 是 | 设置旋转参数。 | 479 480**返回值：** 481 482| 类型 | 说明 | 483| --------------------------------- | ---------------------------- | 484| [Matrix4Transit](#matrix4transit) | 旋转效果后的矩阵对象。 | 485 486**示例：** 487 488```ts 489// xxx.ets 490import { matrix4 } from '@kit.ArkUI'; 491 492@Entry 493@Component 494struct Test { 495 private matrix1 = matrix4.identity() 496 .rotate({ 497 x: 1, 498 y: 1, 499 z: 2, 500 angle: 30 501 }); 502 503 build() { 504 Column() { 505 // $r("app.media.bg1")需要替换为开发者所需的图像资源文件。 506 Image($r("app.media.bg1")).transform(this.matrix1) 507 .width("40%") 508 .height(100) 509 }.width("100%").margin({ top: 50 }) 510 } 511} 512``` 513 514 515 516 517### transformPoint 518 519transformPoint(options: [number, number]): [number, number] 520 521Matrix的坐标点转换函数，可以将当前的变换效果作用到一个坐标点上。 522 523**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 524 525**系统能力：** SystemCapability.ArkUI.ArkUI.Full 526 527**参数：** 528 529| 参数名 | 类型 | 必填 | 说明 | 530| ------- | ---------------- | ---- | ------------------ | 531| options | [number, number] | 是 | 需要转换的坐标点。 | 532 533**返回值：** 534 535| 类型 | 说明 | 536| ---------------- | --------------------------- | 537| [number, number] | 返回矩阵变换后的Point对象。 | 538 539**示例：** 540 541```ts 542// xxx.ets 543import { matrix4 } from '@kit.ArkUI'; 544 545@Entry 546@Component 547struct Test { 548 private originPoint: number[] = [50, 50]; 549 private matrix_1 = matrix4.identity().translate({ x: 150, y: -50 }); 550 private transformPoint = this.matrix_1.transformPoint([this.originPoint[0], this.originPoint[1]]); 551 private matrix_2 = matrix4.identity().translate({ x: this.transformPoint[0], y: this.transformPoint[1] }); 552 553 build() { 554 Column() { 555 Text(`矩阵变换前的坐标：[${this.originPoint}]`) 556 .fontSize(16) 557 // $r("app.media.image")需要替换为开发者所需的图像资源文件。 558 Image($r("app.media.image")) 559 .width('600px') 560 .height('300px') 561 .margin({ top: 50 }) 562 Text(`矩阵变换后的坐标：[${this.transformPoint}]`) 563 .fontSize(16) 564 .margin({ top: 100 }) 565 // $r("app.media.image")需要替换为开发者所需的图像资源文件。 566 Image($r("app.media.image")) 567 .width('600px') 568 .height('300px') 569 .margin({ top: 50 }) 570 .transform(this.matrix_2) 571 }.width("100%").padding(50) 572 } 573} 574``` 575 576 577 578### setPolyToPoly<sup>12+</sup> 579 580setPolyToPoly(options: PolyToPolyOptions): Matrix4Transit 581 582将一个多边形的顶点坐标映射到另外一个多边形的顶点坐标。 583 584**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 585 586**系统能力：** SystemCapability.ArkUI.ArkUI.Full 587 588**参数：** 589 590| 参数名 | 类型 | 必填 | 说明 | 591| ------ | ---------------- | ---- | ------------------ | 592| options | [PolyToPolyOptions](#polytopolyoptions12) | 是 | 映射相关的参数。 | 593 594**返回值：** 595 596| 类型 | 说明 | 597| --------------------------------- | -------------------- | 598| [Matrix4Transit](#matrix4transit) | 当前矩阵变换后的对象。 | 599 600> **说明：** 601> 需要配合scale({centerX:0,centerY:0,x:1})保证变换的中心点是组件左上角。 602 603**示例：** 604 605```ts 606import { matrix4 } from '@kit.ArkUI'; 607 608@Entry 609@Component 610struct Index { 611 private matrix1 = matrix4.identity().setPolyToPoly({ 612 src: [{ x: 0, y: 0 }, { x: 500, y: 0 }, { x: 0, y: 500 }, { x: 500, y: 500 }], 613 dst: [{ x: 0, y: 0 }, { x: 500, y: 0 }, { x: 0, y: 500 }, { x: 750, y: 1000 }], pointCount: 4 614 }); 615 616 build() { 617 Stack() { 618 Column().backgroundColor(Color.Blue) 619 .width('500px') 620 .height('500px') 621 // $r("app.media.transition_image1")需要替换为开发者所需的图像资源文件。 622 Image($r('app.media.transition_image1')) 623 .scale({ centerX: 0, centerY: 0, x: 1 }) 624 .transform(this.matrix1) 625 .width('500px') 626 .height('500px') 627 }.width("100%").height("100%").opacity(0.5) 628 } 629} 630``` 631 632## TranslateOption 633 634平移参数。 635 636**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 637 638**系统能力：** SystemCapability.ArkUI.ArkUI.Full 639 640| 名称 | 类型 | 必填 | 说明 | 641| ---- | ------ | ---- | ----------------------------------------------------------- | 642| x | number | 否 | x轴的平移距离。<br/>单位：px<br/>默认值：0<br/>取值范围 (-∞, +∞) | 643| y | number | 否 | y轴的平移距离。<br/>单位：px<br/>默认值：0<br/>取值范围 (-∞, +∞) | 644| z | number | 否 | z轴的平移距离。<br/>单位：px<br/>默认值：0<br/>取值范围 (-∞, +∞) | 645 646## ScaleOption 647 648缩放参数。 649 650**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 651 652**系统能力：** SystemCapability.ArkUI.ArkUI.Full 653 654| 名称 | 类型 | 必填 | 说明 | 655| ------- | ------ | ---- | ------------------------------------------------------------ | 656| x | number | 否 | x轴的缩放倍数。x>1时以x轴方向放大，0<x<1时以x轴方向缩小，x<0时沿x轴反向并缩放。<br/>默认值：1<br/>取值范围 (-∞, +∞) | 657| y | number | 否 | y轴的缩放倍数。y>1时以y轴方向放大，0<y<1时以y轴方向缩小，y<0时沿y轴反向并缩放。<br/>默认值：1<br/>取值范围 (-∞, +∞) | 658| z | number | 否 | z轴的缩放倍数。z>1时以z轴方向放大，0<z<1时以z轴方向缩小，z<0时沿z轴反向并缩放。<br/>默认值：1<br/>取值范围 (-∞, +∞) | 659| centerX | number | 否 | 变换中心点x轴坐标。<br/>单位：px<br/>默认值：组件中心点x轴坐标。<br/>取值范围 (-∞, +∞) | 660| centerY | number | 否 | 变换中心点y轴坐标。<br/>单位：px<br/>默认值：组件中心点y轴坐标。<br/>取值范围 (-∞, +∞) | 661 662## RotateOption 663 664旋转参数。 665 666**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 667 668**系统能力：** SystemCapability.ArkUI.ArkUI.Full 669 670| 名称 | 类型 | 必填 | 说明 | 671| ------- | ------ | ---- | ------------------------------------------------------------ | 672| x | number | 否 | 旋转轴向量x坐标。<br/>默认值：0。<br/>取值范围 (-∞, +∞) | 673| y | number | 否 | 旋转轴向量y坐标。<br/>默认值：0。<br/>取值范围 (-∞, +∞) | 674| z | number | 否 | 旋转轴向量z坐标。<br/>默认值：0。<br/>取值范围 (-∞, +∞)。<br/>**说明：** 旋转向量中x、y、z至少有一个不为0才有意义。 | 675| angle | number | 否 | 旋转角度。<br/>默认值：0 | 676| centerX | number | 否 | 单次矩阵变换中心点相对于组件变换中心点（锚点）的额外x轴偏移值。<br/>单位：px<br/>默认值：0<br/>**说明：** <br/>为0时表示x方向的矩阵变换中心恰好为组件x方向锚点，取值表示相对组件x方向锚点的额外偏移量。具体实现可参考[示例3（按中心点旋转）](arkui-ts/ts-universal-attributes-transformation.md#示例3按中心点旋转)。 | 677| centerY | number | 否 | 单次矩阵变换中心点相对于组件变换中心点（锚点）的额外y轴偏移值。<br/>单位：px<br/>默认值：0<br/>**说明：** <br/>为0时表示y方向的矩阵变换中心恰好为组件y方向锚点，取值表示相对组件y方向锚点的额外偏移量。具体实现可参考[示例3（按中心点旋转）](arkui-ts/ts-universal-attributes-transformation.md#示例3按中心点旋转)。 | 678 679## PolyToPolyOptions<sup>12+</sup> 680 681多边形到多边形的映射选项。 682 683**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 684 685**系统能力：** SystemCapability.ArkUI.ArkUI.Full 686 687| 名称 | 类型 | 必填 | 说明 | 688| ---- | ------ | ---- | ----------------------------------------------------------- | 689| src | Array<[Point](#point12)> | 是 | 源点坐标。 | 690| srcIndex | number | 否 | 源点坐标起始索引。<br>默认值:0 <br/> 取值范围：[0, +∞)| 691| dst | Array<[Point](#point12)> | 是 | 目标点坐标。 | 692| dstIndex | number | 否 | 目标坐标起始索引。<br>默认值: src.length/2 <br/> 取值范围：[0, +∞) | 693| pointCount | number | 否 | 使用到的点数量。要使用的点的数量如果为0，则返回单位矩阵。如果为1，则返回一个将两个点改变之前的平移矩阵。如果为2-4，则返回一个变换矩阵。<br>默认值: 0 <br/> 取值范围：[0, +∞)| 694 695## Point<sup>12+</sup> 696 697坐标点的数据结构。 698 699**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 700 701**系统能力：** SystemCapability.ArkUI.ArkUI.Full 702 703| 名称 | 类型 | 必填 | 说明 | 704| ---- | ------ | ---- | ----------------------------------------------------------- | 705| x | number | 是 | x轴坐标。<br/>取值范围：(-∞, +∞) | 706| y | number | 是 | y轴坐标。<br/>取值范围：(-∞, +∞) | 707 708## matrix4.copy<sup>(deprecated)</sup> 709 710copy(): Matrix4Transit 711 712 713Matrix的拷贝函数，可以拷贝一份当前的矩阵对象。 714 715> **说明：** 716> 717> 从API version 10开始废弃。建议使用[Matrix4Transit.copy](#copy)替代。 718 719 720**系统能力：** SystemCapability.ArkUI.ArkUI.Full 721 722**返回值：** 723 724| 类型 | 说明 | 725| --------------------------------- | -------------------- | 726| [Matrix4Transit](#matrix4transit) | 当前矩阵的拷贝对象。 | 727 728**示例：** 729 730```ts 731// xxx.ets 732import { matrix4 } from '@kit.ArkUI'; 733 734@Entry 735@Component 736struct Test { 737 private matrix1 = matrix4.identity().translate({ x: 100 }); 738 // 对matrix1的拷贝矩阵做scale操作，不影响到matrix1 739 private matrix2 = this.matrix1.copy().scale({ x: 2 }); 740 741 build() { 742 Column() { 743 // $r("app.media.bg1")需要替换为开发者所需的图像资源文件。 744 Image($r("app.media.bg1")) 745 .width("40%") 746 .height(100) 747 .transform(this.matrix1) 748 // $r("app.media.bg2")需要替换为开发者所需的图像资源文件。 749 Image($r("app.media.bg2")) 750 .width("40%") 751 .height(100) 752 .margin({ top: 50 }) 753 .transform(this.matrix2) 754 } 755 } 756} 757``` 758 759 760 761## matrix4.invert<sup>(deprecated)</sup> 762 763invert(): Matrix4Transit 764 765Matrix的逆函数，可以返回一个当前矩阵对象的逆矩阵，即效果正好相反。 766 767> **说明：** 768> 769> 从API version 10开始废弃。建议使用[Matrix4Transit.invert](#invert)替代。 770 771**系统能力：** SystemCapability.ArkUI.ArkUI.Full 772 773**返回值：** 774 775| 类型 | 说明 | 776| --------------------------------- | ---------------------- | 777| [Matrix4Transit](#matrix4transit) | 当前矩阵的逆矩阵对象。 | 778 779## matrix4.combine<sup>(deprecated)</sup> 780 781combine(options: Matrix4Transit): Matrix4Transit 782 783Matrix的叠加函数，可以将两个矩阵的效果叠加起来生成一个新的矩阵对象。 784 785> **说明：** 786> 787> 从API version 10开始废弃。建议使用[Matrix4Transit.combine](#combine)替代。 788 789**系统能力：** SystemCapability.ArkUI.ArkUI.Full 790 791**参数：** 792 793| 参数名 | 类型 | 必填 | 说明 | 794| ------- | --------------------------------- | ---- | ------------------ | 795| options | [Matrix4Transit](#matrix4transit) | 是 | 待叠加的矩阵对象。 | 796 797**返回值：** 798 799| 类型 | 说明 | 800| --------------------------------- | ---------------------- | 801| [Matrix4Transit](#matrix4transit) | 叠加后的矩阵对象。 | 802 803## matrix4.translate<sup>(deprecated)</sup> 804 805translate(options: TranslateOption): Matrix4Transit 806 807Matrix的平移函数，可以为当前矩阵增加x轴/y轴/z轴平移效果。 808 809> **说明：** 810> 811> 从API version 10开始废弃。建议使用[Matrix4Transit.translate](#translate)替代。 812 813**系统能力：** SystemCapability.ArkUI.ArkUI.Full 814 815**参数：** 816 817| 参数名 | 类型 | 必填 | 说明 | 818| ------- | ----------------------------------- | ---- | -------------- | 819| options | [TranslateOption](#translateoption) | 是 | 设置平移参数。 | 820 821**返回值：** 822 823| 类型 | 说明 | 824| --------------------------------- | ---------------------- | 825| [Matrix4Transit](#matrix4transit) | 平移后的矩阵对象。 | 826 827## matrix4.scale<sup>(deprecated)</sup> 828 829scale(options: ScaleOption): Matrix4Transit 830 831Matrix的缩放函数，可以为当前矩阵增加x轴/y轴/z轴缩放效果。 832 833> **说明：** 834> 835> 从API version 10开始废弃。建议使用[Matrix4Transit.scale](#scale)替代。 836 837**系统能力：** SystemCapability.ArkUI.ArkUI.Full 838 839**参数：** 840 841| 参数名 | 类型 | 必填 | 说明 | 842| ------- | --------------------------- | ---- | -------------- | 843| options | [ScaleOption](#scaleoption) | 是 | 设置缩放参数。 | 844 845**返回值：** 846 847| 类型 | 说明 | 848| --------------------------------- | ---------------------- | 849| [Matrix4Transit](#matrix4transit) | 缩放后的矩阵对象。 | 850 851## matrix4.rotate<sup>(deprecated)</sup> 852 853rotate(options: RotateOption): Matrix4Transit 854 855Matrix的旋转函数，可以为当前矩阵增加x轴/y轴/z轴旋转效果。 856 857> **说明：** 858> 859> 从API version 10开始废弃。建议使用[Matrix4Transit.rotate](#rotate)替代。 860 861**系统能力：** SystemCapability.ArkUI.ArkUI.Full 862 863**参数：** 864 865| 参数名 | 类型 | 必填 | 说明 | 866| ------- | ----------------------------- | ---- | -------------- | 867| options | [RotateOption](#rotateoption) | 是 | 设置旋转参数。 | 868 869**返回值：** 870 871| 类型 | 说明 | 872| --------------------------------- | ---------------------- | 873| [Matrix4Transit](#matrix4transit) | 旋转后的矩阵对象。 | 874 875## matrix4.transformPoint<sup>(deprecated)</sup> 876 877transformPoint(options: [number, number]): [number, number] 878 879Matrix的坐标点转换函数，可以将当前的变换效果作用到一个坐标点上。 880 881> **说明：** 882> 883> 从API version 10开始废弃。建议使用[Matrix4Transit.transformPoint](#transformpoint)替代。 884 885**系统能力：** SystemCapability.ArkUI.ArkUI.Full 886 887**参数：** 888 889| 参数名 | 类型 | 必填 | 说明 | 890| ------- | ---------------- | ---- | ------------------ | 891| options | [number, number] | 是 | 需要转换的坐标点。 | 892 893**返回值：** 894 895| 类型 | 说明 | 896| ---------------- | --------------------------- | 897| [number, number] | 返回矩阵变换后的Point对象。 |
