1# @ohos.matrix4 (矩阵变换) 2 3本模块提供矩阵变换功能，可对图形进行平移、旋转和缩放等。 4 5> **说明：** 6> 7> 本模块首批接口从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9 10## 导入模块 11 12```ts 13import matrix4 from '@ohos.matrix4' 14``` 15 16 17## matrix4.init 18 19init(options: [number,number,number,number,number,number,number,number,number,number,number,number,number,number,number,number]): Matrix4Transit 20 21 22Matrix的构造函数，可以通过传入的参数创建一个四阶矩阵，矩阵为列优先。 23 24**系统能力：** SystemCapability.ArkUI.ArkUI.Full 25 26**参数：** 27 28| 参数名 | 类型 | 必填 | 说明 | 29| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 30| option | [number,number,number,number,<br/>number,number,number,number,<br/>number,number,number,number,<br/>number,number,number,number] | 是 | 参数为长度为16（4\*4）的number数组, 详情见四阶矩阵说明。<br/>默认值：<br/>[1, 0, 0, 0,<br/>0, 1, 0, 0,<br/>0, 0, 1, 0,<br/>0, 0, 0, 1] | 31 32**返回值：** 33 34| 类型 | 说明 | 35| --------------------------------- | ---------------------------- | 36| [Matrix4Transit](#matrix4transit) | 根据入参创建的四阶矩阵对象。 | 37 38**四阶矩阵说明：** 39 40| 参数名 | 类型 | 必填 | 说明 | 41| ---- | ------ | ---- | -------------------- | 42| m00 | number | 是 | x轴缩放值，单位矩阵默认为1。 | 43| m01 | number | 是 | 第2个值，xyz轴旋转会影响这个值。 | 44| m02 | number | 是 | 第3个值，xyz轴旋转会影响这个值。 | 45| m03 | number | 是 | 无实际意义。 | 46| m10 | number | 是 | 第5个值，xyz轴旋转会影响这个值。 | 47| m11 | number | 是 | y轴缩放值，单位矩阵默认为1。 | 48| m12 | number | 是 | 第7个值，xyz轴旋转会影响这个值。 | 49| m13 | number | 是 | 无实际意义。 | 50| m20 | number | 是 | 第9个值，xyz轴旋转会影响这个值。 | 51| m21 | number | 是 | 第10个值，xyz轴旋转会影响这个值。 | 52| m22 | number | 是 | z轴缩放值，单位矩阵默认为1。 | 53| m23 | number | 是 | 无实际意义。 | 54| m30 | number | 是 | x轴平移值，单位px，单位矩阵默认为0。 | 55| m31 | number | 是 | y轴平移值，单位px，单位矩阵默认为0。 | 56| m32 | number | 是 | z轴平移值，单位px，单位矩阵默认为0。 | 57| m33 | number | 是 | 齐次坐标下生效，产生透视投影效果。 | 58 59**示例** 60 61```ts 62import matrix4 from '@ohos.matrix4' 63// 创建一个四阶矩阵 64let matrix = matrix4.init([1.0, 0.0, 0.0, 0.0, 65 0.0, 1.0, 0.0, 0.0, 66 0.0, 0.0, 1.0, 0.0, 67 0.0, 0.0, 0.0, 1.0]) 68@Entry 69@Component 70struct Tests { 71 build() { 72 Column() { 73 Image($r("app.media.zh")) 74 .width("40%") 75 .height(100) 76 .transform(matrix) 77 } 78 } 79} 80``` 81 82 83## matrix4.identity 84 85identity(): Matrix4Transit 86 87 88Matrix的初始化函数，可以返回一个单位矩阵对象。 89 90**系统能力：** SystemCapability.ArkUI.ArkUI.Full 91 92**返回值：** 93 94| 类型 | 说明 | 95| --------------------------------- | -------------- | 96| [Matrix4Transit](#matrix4transit) | 单位矩阵对象。 | 97 98**示例：** 99 100```ts 101// matrix1 和 matrix2 效果一致 102import matrix4 from '@ohos.matrix4' 103let matrix1 = matrix4.init([1.0, 0.0, 0.0, 0.0, 104 0.0, 1.0, 0.0, 0.0, 105 0.0, 0.0, 1.0, 0.0, 106 0.0, 0.0, 0.0, 1.0]) 107let matrix2 = matrix4.identity() 108@Entry 109@Component 110struct Tests { 111 build() { 112 Column() { 113 Image($r("app.media.zh")) 114 .width("40%") 115 .height(100) 116 .transform(matrix1) 117 Image($r("app.media.zh")) 118 .width("40%") 119 .height(100) 120 .margin({ top: 150 }) 121 .transform(matrix2) 122 } 123 } 124} 125``` 126 127## Matrix4Transit 128 129### copy 130 131copy(): Matrix4Transit 132 133 134Matrix的拷贝函数，可以拷贝一份当前的矩阵对象。 135 136**系统能力：** SystemCapability.ArkUI.ArkUI.Full 137 138**返回值：** 139 140| 类型 | 说明 | 141| --------------------------------- | -------------------- | 142| [Matrix4Transit](#matrix4transit) | 当前矩阵的拷贝对象。 | 143 144 145**示例：** 146 147```ts 148// xxx.ets 149import matrix4 from '@ohos.matrix4' 150 151@Entry 152@Component 153struct Test { 154 private matrix1 = matrix4.identity().translate({ x: 200 }) 155 // 对matrix1的拷贝矩阵做scale操作，不影响到matrix1 156 private matrix2 = this.matrix1.copy().scale({ x: 1.5 }) 157 158 build() { 159 Column() { 160 Image($r("app.media.test")) 161 .width("40%") 162 .height(100) 163 .transform(this.matrix1) 164 Image($r("app.media.test")) 165 .width("40%") 166 .height(100) 167 .margin({ top: 50 }) 168 .transform(this.matrix2) 169 }.alignItems(HorizontalAlign.Center) 170 .height('100%') 171 .justifyContent(FlexAlign.Center) 172 } 173} 174``` 175 176 177### combine 178 179combine(options: Matrix4Transit): Matrix4Transit 180 181 182Matrix的叠加函数，可以将两个矩阵的效果叠加起来生成一个新的矩阵对象。会改变调用该函数的原始矩阵。 183 184**系统能力：** SystemCapability.ArkUI.ArkUI.Full 185 186**参数：** 187 188| 参数名 | 类型 | 必填 | 说明 | 189| ------ | --------------------------------- | ---- | ------------------ | 190| option | [Matrix4Transit](#matrix4transit) | 是 | 待叠加的矩阵对象。 | 191 192**返回值：** 193 194| 类型 | 说明 | 195| --------------------------------- | ------------------ | 196| [Matrix4Transit](#matrix4transit) | 矩阵叠加后的对象。 | 197 198**示例：** 199 200```ts 201// xxx.ets 202import matrix4 from '@ohos.matrix4' 203 204@Entry 205@Component 206struct Test { 207 private matrix1 = matrix4.identity().translate({ x: 200 }) 208 private matrix2 = matrix4.identity().scale({ x: 2 }) 209 210 build() { 211 Column() { 212 // 矩阵变换前 213 Image($r("app.media.icon")) 214 .width("40%") 215 .height(100) 216 .margin({ top: 50 }) 217 // 先平移x轴200px，再缩放两倍x轴，得到矩阵变换后的效果图 218 Image($r("app.media.icon")) 219 .transform(this.matrix1.copy().combine(this.matrix2)) 220 .width("40%") 221 .height(100) 222 .margin({ top: 50 }) 223 } 224 } 225} 226``` 227 228 229 230 231### invert 232 233invert(): Matrix4Transit 234 235Matrix的逆函数，可以返回一个当前矩阵对象的逆矩阵，即效果正好相反。会改变调用该函数的原始矩阵。 236 237**系统能力：** SystemCapability.ArkUI.ArkUI.Full 238 239**返回值：** 240 241| 类型 | 说明 | 242| --------------------------------- | ---------------------- | 243| [Matrix4Transit](#matrix4transit) | 当前矩阵的逆矩阵对象。 | 244 245**示例：** 246 247```ts 248import matrix4 from '@ohos.matrix4' 249// matrix1(宽放大2倍) 和 matrix2(宽缩小2倍) 效果相反 250let matrix1 = matrix4.identity().scale({ x: 2 }) 251let matrix2 = matrix1.copy().invert() 252 253@Entry 254@Component 255struct Tests { 256 build() { 257 Column() { 258 Image($r("app.media.zh")) 259 .width(200) 260 .height(100) 261 .transform(matrix1) 262 .margin({ top: 100 }) 263 Image($r("app.media.zh")) 264 .width(200) 265 .height(100) 266 .margin({ top: 150 }) 267 .transform(matrix2) 268 } 269 } 270} 271``` 272 273 274### translate 275 276translate(options: TranslateOption): Matrix4Transit 277 278Matrix的平移函数，可以为当前矩阵增加x轴/y轴/z轴平移效果。会改变调用该函数的原始矩阵。 279 280**系统能力：** SystemCapability.ArkUI.ArkUI.Full 281 282**参数：** 283 284| 参数名 | 类型 | 必填 | 说明 | 285| ------ | ----------------------------------- | ---- | -------------- | 286| option | [TranslateOption](#translateoption) | 是 | 设置平移参数。 | 287 288**返回值：** 289 290| 类型 | 说明 | 291| --------------------------------- | ---------------------------- | 292| [Matrix4Transit](#matrix4transit) | 平移效果后的矩阵对象。 | 293 294**示例：** 295 296```ts 297// xxx.ets 298import matrix4 from '@ohos.matrix4' 299 300@Entry 301@Component 302struct Test { 303 private matrix1 = matrix4.identity().translate({ x: 100, y: 200, z: 30 }) 304 305 build() { 306 Column() { 307 Image($r("app.media.bg1")).transform(this.matrix1) 308 .width("40%") 309 .height(100) 310 } 311 } 312} 313``` 314 315 316 317 318### scale 319 320scale(options: ScaleOption): Matrix4Transit 321 322 323Matrix的缩放函数，可以为当前矩阵增加x轴/y轴/z轴缩放效果。会改变调用该函数的原始矩阵。 324 325**系统能力：** SystemCapability.ArkUI.ArkUI.Full 326 327**参数：** 328 329| 参数名 | 类型 | 必填 | 说明 | 330| ------ | --------------------------- | ---- | -------------- | 331| option | [ScaleOption](#scaleoption) | 是 | 设置缩放参数。 | 332 333**返回值：** 334 335| 类型 | 说明 | 336| --------------------------------- | ---------------------------- | 337| [Matrix4Transit](#matrix4transit) | 缩放效果后的矩阵对象。 | 338 339**示例：** 340 341```ts 342// xxx.ets 343import matrix4 from '@ohos.matrix4' 344@Entry 345@Component 346struct Test { 347 private matrix1 = matrix4.identity().scale({ x:2, y:3, z:4, centerX:50, centerY:50 }) 348 349 build() { 350 Column() { 351 Image($r("app.media.bg1")).transform(this.matrix1) 352 .width("40%") 353 .height(100) 354 } 355 } 356} 357``` 358 359 360 361 362### rotate 363 364rotate(options: RotateOption): Matrix4Transit 365 366 367Matrix的旋转函数，可以为当前矩阵增加x轴/y轴/z轴旋转效果。会改变调用该函数的原始矩阵。 368 369**系统能力：** SystemCapability.ArkUI.ArkUI.Full 370 371**参数：** 372 373| 参数名 | 类型 | 必填 | 说明 | 374| ------ | ----------------------------- | ---- | -------------- | 375| option | [RotateOption](#rotateoption) | 是 | 设置旋转参数。 | 376 377**返回值：** 378 379| 类型 | 说明 | 380| --------------------------------- | ---------------------------- | 381| [Matrix4Transit](#matrix4transit) | 旋转效果后的矩阵对象。 | 382 383**示例：** 384 385```ts 386// xxx.ets 387import matrix4 from '@ohos.matrix4' 388 389@Entry 390@Component 391struct Test { 392 private matrix1 = matrix4.identity().rotate({ x: 1, y: 1, z: 2, angle: 30 }) 393 394 build() { 395 Column() { 396 Image($r("app.media.bg1")).transform(this.matrix1) 397 .width("40%") 398 .height(100) 399 }.width("100%").margin({ top: 50 }) 400 } 401} 402``` 403 404 405 406 407### transformPoint 408 409transformPoint(options: [number, number]): [number, number] 410 411 412Matrix的坐标点转换函数，可以将当前的变换效果作用到一个坐标点上。 413 414**系统能力：** SystemCapability.ArkUI.ArkUI.Full 415 416**参数：** 417 418| 参数名 | 类型 | 必填 | 说明 | 419| ------ | ---------------- | ---- | ------------------ | 420| option | [number, number] | 是 | 需要转换的坐标点。 | 421 422**返回值：** 423 424| 类型 | 说明 | 425| ---------------- | --------------------------- | 426| [number, number] | 返回矩阵变换后的Point对象。 | 427 428**示例：** 429 430```ts 431// xxx.ets 432import matrix4 from '@ohos.matrix4' 433 434@Entry 435@Component 436struct Test { 437 private originPoint: number[] = [50, 50] 438 private matrix_1 = matrix4.identity().translate({ x: 150, y: -50 }) 439 private transformPoint = this.matrix_1.transformPoint([this.originPoint[0], this.originPoint[1]]) 440 private matrix_2 = matrix4.identity().translate({ x: this.transformPoint[0], y: this.transformPoint[1] }) 441 442 build() { 443 Column() { 444 Text(`矩阵变换前的坐标：[${this.originPoint}]`) 445 .fontSize(16) 446 Image($r("app.media.image")) 447 .width('600px') 448 .height('300px') 449 .margin({ top: 50 }) 450 Text(`矩阵变换后的坐标：[${this.transformPoint}]`) 451 .fontSize(16) 452 .margin({ top: 100 }) 453 Image($r("app.media.image")) 454 .width('600px') 455 .height('300px') 456 .margin({ top: 50 }) 457 .transform(this.matrix_2) 458 }.width("100%").padding(50) 459 } 460} 461``` 462 463 464 465## TranslateOption 466 467**系统能力：** SystemCapability.ArkUI.ArkUI.Full 468 469| 名称 | 类型 | 必填 | 说明 | 470| ---- | ------ | ---- | ----------------------------------------------------------- | 471| x | number | 否 | x轴的平移距离，单位px。<br/>默认值：0<br/>取值范围 (-∞, +∞) | 472| y | number | 否 | y轴的平移距离，单位px。<br/>默认值：0<br/>取值范围 (-∞, +∞) | 473| z | number | 否 | z轴的平移距离，单位px。<br/>默认值：0<br/>取值范围 (-∞, +∞) | 474 475## ScaleOption 476 477**系统能力：** SystemCapability.ArkUI.ArkUI.Full 478 479| 名称 | 类型 | 必填 | 说明 | 480| ------- | ------ | ---- | ------------------------------------------------------------ | 481| x | number | 否 | x轴的缩放倍数。x>1时以x轴方向放大，0<x<1时以x轴方向缩小，x<0时沿x轴反向并缩放。<br/>默认值：1<br/>取值范围 (-∞, +∞) | 482| y | number | 否 | y轴的缩放倍数。y>1时以y轴方向放大，0<y<1时以y轴方向缩小，y<0时沿y轴反向并缩放。<br/>默认值：1<br/>取值范围 (-∞, +∞) | 483| z | number | 否 | z轴的缩放倍数。z>1时以z轴方向放大，0<z<1时以z轴方向缩小，z<0时沿z轴反向并缩放。<br/>默认值：1<br/>取值范围 (-∞, +∞) | 484| centerX | number | 否 | 变换中心点x轴坐标。<br/>默认值：0。<br/>取值范围 (-∞, +∞) | 485| centerY | number | 否 | 变换中心点y轴坐标。<br/>默认值：0。<br/>取值范围 (-∞, +∞) | 486 487## RotateOption 488 489**系统能力：** SystemCapability.ArkUI.ArkUI.Full 490 491| 名称 | 类型 | 必填 | 说明 | 492| ------- | ------ | ---- | ------------------------------------------------------- | 493| x | number | 否 | 旋转轴向量x坐标。<br/>默认值：0。<br/>取值范围 (-∞, +∞) | 494| y | number | 否 | 旋转轴向量y坐标。<br/>默认值：0。<br/>取值范围 (-∞, +∞) | 495| z | number | 否 | 旋转轴向量z坐标。<br/>默认值：0。<br/>取值范围 (-∞, +∞)。<br/>**说明：** 旋转向量中x、y、z至少有一个不为0才有意义。 | 496| angle | number | 否 | 旋转角度。<br/>默认值：0 | 497| centerX | number | 否 | 变换中心点x轴坐标。<br/>默认值：0 | 498| centerY | number | 否 | 变换中心点y轴坐标。<br/>默认值：0 | 499 500 501 502 503## matrix4.copy<sup>(deprecated)</sup> 504 505copy(): Matrix4Transit 506 507 508Matrix的拷贝函数，可以拷贝一份当前的矩阵对象。 509 510> **说明：** 511> 512> 从API version 10开始废弃。建议使用[Matrix4Transit.copy](#copy)替代。 513 514 515**系统能力：** SystemCapability.ArkUI.ArkUI.Full 516 517**返回值：** 518 519| 类型 | 说明 | 520| --------------------------------- | -------------------- | 521| [Matrix4Transit](#matrix4transit) | 当前矩阵的拷贝对象。 | 522 523**示例：** 524 525```ts 526// xxx.ets 527import matrix4 from '@ohos.matrix4' 528 529@Entry 530@Component 531struct Test { 532 private matrix1 = matrix4.identity().translate({ x: 100 }) 533 // 对matrix1的拷贝矩阵做scale操作，不影响到matrix1 534 private matrix2 = this.matrix1.copy().scale({ x: 2 }) 535 536 build() { 537 Column() { 538 Image($r("app.media.bg1")) 539 .width("40%") 540 .height(100) 541 .transform(this.matrix1) 542 Image($r("app.media.bg2")) 543 .width("40%") 544 .height(100) 545 .margin({ top: 50 }) 546 .transform(this.matrix2) 547 } 548 } 549} 550``` 551 552 553 554## matrix4.invert<sup>(deprecated)</sup> 555 556invert(): Matrix4Transit 557 558Matrix的逆函数，可以返回一个当前矩阵对象的逆矩阵，即效果正好相反。 559 560> **说明：** 561> 562> 从API version 10开始废弃。建议使用[Matrix4Transit.invert](#invert)替代。 563 564**系统能力：** SystemCapability.ArkUI.ArkUI.Full 565 566**返回值：** 567 568| 类型 | 说明 | 569| --------------------------------- | ---------------------- | 570| [Matrix4Transit](#matrix4transit) | 当前矩阵的逆矩阵对象。 | 571 572## matrix4.combine<sup>(deprecated)</sup> 573 574combine(options: Matrix4Transit): Matrix4Transit 575 576Matrix的叠加函数，可以将两个矩阵的效果叠加起来生成一个新的矩阵对象。 577 578> **说明：** 579> 580> 从API version 10开始废弃。建议使用[Matrix4Transit.combine](#combine)替代。 581 582**系统能力：** SystemCapability.ArkUI.ArkUI.Full 583 584**参数：** 585 586| 参数名 | 类型 | 必填 | 说明 | 587| ------ | --------------------------------- | ---- | ------------------ | 588| option | [Matrix4Transit](#matrix4transit) | 是 | 待叠加的矩阵对象。 | 589 590**返回值：** 591 592| 类型 | 说明 | 593| --------------------------------- | ---------------------- | 594| [Matrix4Transit](#matrix4transit) | 叠加后的矩阵对象。 | 595 596## matrix4.translate<sup>(deprecated)</sup> 597 598translate(options: TranslateOption): Matrix4Transit 599 600Matrix的平移函数，可以为当前矩阵增加x轴/y轴/z轴平移效果。 601 602> **说明：** 603> 604> 从API version 10开始废弃。建议使用[Matrix4Transit.translate](#translate)替代。 605 606**系统能力：** SystemCapability.ArkUI.ArkUI.Full 607 608**参数：** 609 610| 参数名 | 类型 | 必填 | 说明 | 611| ------ | ----------------------------------- | ---- | -------------- | 612| option | [TranslateOption](#translateoption) | 是 | 设置平移参数。 | 613 614**返回值：** 615 616| 类型 | 说明 | 617| --------------------------------- | ---------------------- | 618| [Matrix4Transit](#matrix4transit) | 平移后的矩阵对象。 | 619 620## matrix4.scale<sup>(deprecated)</sup> 621 622scale(options: ScaleOption): Matrix4Transit 623 624Matrix的缩放函数，可以为当前矩阵增加x轴/y轴/z轴缩放效果。 625 626> **说明：** 627> 628> 从API version 10开始废弃。建议使用[Matrix4Transit.scale](#scale)替代。 629 630**系统能力：** SystemCapability.ArkUI.ArkUI.Full 631 632**参数：** 633 634| 参数名 | 类型 | 必填 | 说明 | 635| ------ | --------------------------- | ---- | -------------- | 636| option | [ScaleOption](#scaleoption) | 是 | 设置缩放参数。 | 637 638**返回值：** 639 640| 类型 | 说明 | 641| --------------------------------- | ---------------------- | 642| [Matrix4Transit](#matrix4transit) | 缩放后的矩阵对象。 | 643 644## matrix4.rotate<sup>(deprecated)</sup> 645 646rotate(options: RotateOption): Matrix4Transit 647 648Matrix的旋转函数，可以为当前矩阵增加x轴/y轴/z轴旋转效果。 649 650> **说明：** 651> 652> 从API version 10开始废弃。建议使用[Matrix4Transit.rotate](#rotate)替代。 653 654**系统能力：** SystemCapability.ArkUI.ArkUI.Full 655 656**参数：** 657 658| 参数名 | 类型 | 必填 | 说明 | 659| ------ | ----------------------------- | ---- | -------------- | 660| option | [RotateOption](#rotateoption) | 是 | 设置旋转参数。 | 661 662**返回值：** 663 664| 类型 | 说明 | 665| --------------------------------- | ---------------------- | 666| [Matrix4Transit](#matrix4transit) | 旋转后的矩阵对象。 | 667 668## matrix4.transformPoint<sup>(deprecated)</sup> 669 670transformPoint(options: [number, number]): [number, number] 671 672Matrix的坐标点转换函数，可以将当前的变换效果作用到一个坐标点上。 673 674> **说明：** 675> 676> 从API version 10开始废弃。建议使用[Matrix4Transit.transformPoint](#transformpoint)替代。 677 678**系统能力：** SystemCapability.ArkUI.ArkUI.Full 679 680**参数：** 681 682| 参数名 | 类型 | 必填 | 说明 | 683| ------ | ---------------- | ---- | ------------------ | 684| option | [number, number] | 是 | 需要转换的坐标点。 | 685 686**返回值：** 687 688| 类型 | 说明 | 689| ---------------- | --------------------------- | 690| [number, number] | 返回矩阵变换后的Point对象。 |
