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 128## matrix4.copy 129 130copy(): Matrix4Transit 131 132 133Matrix的拷贝函数，可以拷贝一份当前的矩阵对象。 134 135**系统能力：** SystemCapability.ArkUI.ArkUI.Full 136 137**返回值：** 138 139| 类型 | 说明 | 140| --------------------------------- | -------------------- | 141| [Matrix4Transit](#matrix4transit) | 当前矩阵的拷贝对象。 | 142 143**示例：** 144 145```ts 146// xxx.ets 147import matrix4 from '@ohos.matrix4' 148@Entry 149@Component 150struct Test { 151 private matrix1 = matrix4.identity().translate({ x: 100 }) 152 // 对matrix1的拷贝矩阵做scale操作，不影响到matrix1 153 private matrix2 = this.matrix1.copy().scale({ x: 2 }) 154 155 build() { 156 Column() { 157 Image($r("app.media.bg1")) 158 .width("40%") 159 .height(100) 160 .transform(this.matrix1) 161 Image($r("app.media.bg2")) 162 .width("40%") 163 .height(100) 164 .margin({ top: 50 }) 165 .transform(this.matrix2) 166 } 167 } 168} 169``` 170 171 172 173## matrix4.invert 174 175invert(): Matrix4Transit 176 177Matrix的逆函数，可以返回一个当前矩阵对象的逆矩阵，即效果正好相反。 178 179**系统能力：** SystemCapability.ArkUI.ArkUI.Full 180 181**返回值：** 182 183| 类型 | 说明 | 184| --------------------------------- | ---------------------- | 185| [Matrix4Transit](#matrix4transit) | 当前矩阵的逆矩阵对象。 | 186 187## matrix4.combine 188 189combine(options: Matrix4Transit): Matrix4Transit 190 191Matrix的叠加函数，可以将两个矩阵的效果叠加起来生成一个新的矩阵对象。 192 193**系统能力：** SystemCapability.ArkUI.ArkUI.Full 194 195**参数：** 196 197| 参数名 | 类型 | 必填 | 说明 | 198| ------ | --------------------------------- | ---- | ------------------ | 199| option | [Matrix4Transit](#matrix4transit) | 是 | 待叠加的矩阵对象。 | 200 201**返回值：** 202 203| 类型 | 说明 | 204| --------------------------------- | ---------------------- | 205| [Matrix4Transit](#matrix4transit) | 当前矩阵的逆矩阵对象。 | 206 207## matrix4.translate 208 209translate(options: TranslateOption): Matrix4Transit 210 211Matrix的平移函数，可以为当前矩阵增加x轴/y轴/z轴平移效果。 212 213**系统能力：** SystemCapability.ArkUI.ArkUI.Full 214 215**参数：** 216 217| 参数名 | 类型 | 必填 | 说明 | 218| ------ | ----------------------------------- | ---- | -------------- | 219| option | [TranslateOption](#translateoption) | 是 | 设置平移参数。 | 220 221**返回值：** 222 223| 类型 | 说明 | 224| --------------------------------- | ---------------------- | 225| [Matrix4Transit](#matrix4transit) | 当前矩阵的逆矩阵对象。 | 226 227## matrix4.scale 228 229scale(options: ScaleOption): Matrix4Transit 230 231Matrix的缩放函数，可以为当前矩阵增加x轴/y轴/z轴缩放效果。 232 233**系统能力：** SystemCapability.ArkUI.ArkUI.Full 234 235**参数：** 236 237| 参数名 | 类型 | 必填 | 说明 | 238| ------ | --------------------------- | ---- | -------------- | 239| option | [ScaleOption](#scaleoption) | 是 | 设置缩放参数。 | 240 241**返回值：** 242 243| 类型 | 说明 | 244| --------------------------------- | ---------------------- | 245| [Matrix4Transit](#matrix4transit) | 当前矩阵的逆矩阵对象。 | 246 247## matrix4.rotate 248 249rotate(options: RotateOption): Matrix4Transit 250 251Matrix的旋转函数，可以为当前矩阵增加x轴/y轴/z轴旋转效果。 252 253**系统能力：** SystemCapability.ArkUI.ArkUI.Full 254 255**参数：** 256 257| 参数名 | 类型 | 必填 | 说明 | 258| ------ | ----------------------------- | ---- | -------------- | 259| option | [RotateOption](#rotateoption) | 是 | 设置旋转参数。 | 260 261**返回值：** 262 263| 类型 | 说明 | 264| --------------------------------- | ---------------------- | 265| [Matrix4Transit](#matrix4transit) | 当前矩阵的逆矩阵对象。 | 266 267## matrix4.transformPoint 268 269transformPoint(options: [number, number]): [number, number] 270 271Matrix的坐标点转换函数，可以将当前的变换效果作用到一个坐标点上。 272 273**系统能力：** SystemCapability.ArkUI.ArkUI.Full 274 275**参数：** 276 277| 参数名 | 类型 | 必填 | 说明 | 278| ------ | ---------------- | ---- | ------------------ | 279| option | [number, number] | 是 | 需要转换的坐标点。 | 280 281**返回值：** 282 283| 类型 | 说明 | 284| ---------------- | --------------------------- | 285| [number, number] | 返回矩阵变换后的Point对象。 | 286 287 288## Matrix4Transit 289 290 291### combine 292 293combine(options: Matrix4Transit): Matrix4Transit 294 295 296Matrix的叠加函数，可以将两个矩阵的效果叠加起来生成一个新的矩阵对象。会改变调用该函数的原始矩阵。 297 298**系统能力：** SystemCapability.ArkUI.ArkUI.Full 299 300**参数：** 301 302| 参数名 | 类型 | 必填 | 说明 | 303| ------ | --------------------------------- | ---- | ------------------ | 304| option | [Matrix4Transit](#matrix4transit) | 是 | 待叠加的矩阵对象。 | 305 306**返回值：** 307 308| 类型 | 说明 | 309| --------------------------------- | ------------------ | 310| [Matrix4Transit](#matrix4transit) | 矩阵叠加后的对象。 | 311 312**示例：** 313 314```ts 315// xxx.ets 316import matrix4 from '@ohos.matrix4' 317@Entry 318@Component 319struct Test { 320 private matrix1 = matrix4.identity().translate({ x: 200 }) 321 private matrix2 = matrix4.identity().scale({ x: 2 }) 322 323 build() { 324 Column() { 325 // 矩阵变换前 326 Image($r("app.media.icon")) 327 .width("40%") 328 .height(100) 329 .margin({ top: 50 }) 330 // 先平移x轴200px，再缩放两倍x轴，得到矩阵变换后的效果图 331 Image($r("app.media.icon")) 332 .transform(this.matrix1.copy().combine(this.matrix2)) 333 .width("40%") 334 .height(100) 335 .margin({ top: 50 }) 336 } 337 } 338} 339``` 340 341 342 343 344### invert 345 346invert(): Matrix4Transit 347 348Matrix的逆函数，可以返回一个当前矩阵对象的逆矩阵，即效果正好相反。会改变调用该函数的原始矩阵。 349 350**系统能力：** SystemCapability.ArkUI.ArkUI.Full 351 352**返回值：** 353 354| 类型 | 说明 | 355| --------------------------------- | ---------------------- | 356| [Matrix4Transit](#matrix4transit) | 当前矩阵的逆矩阵对象。 | 357 358**示例：** 359 360```ts 361import matrix4 from '@ohos.matrix4' 362// matrix1(宽放大2倍) 和 matrix2(宽缩小2倍) 效果相反 363let matrix1 = matrix4.identity().scale({ x: 2 }) 364let matrix2 = matrix1.copy().invert() 365@Entry 366@Component 367struct Tests { 368 build() { 369 Column() { 370 Image($r("app.media.zh")) 371 .width(200) 372 .height(100) 373 .transform(matrix1) 374 .margin({ top: 100 }) 375 Image($r("app.media.zh")) 376 .width(200) 377 .height(100) 378 .margin({ top: 150 }) 379 .transform(matrix2) 380 } 381 } 382} 383``` 384 385 386### translate 387 388translate(options: TranslateOption): Matrix4Transit 389 390Matrix的平移函数，可以为当前矩阵增加x轴/y轴/z轴平移效果。会改变调用该函数的原始矩阵。 391 392**系统能力：** SystemCapability.ArkUI.ArkUI.Full 393 394**参数：** 395 396| 参数名 | 类型 | 必填 | 说明 | 397| ------ | ----------------------------------- | ---- | -------------- | 398| option | [TranslateOption](#translateoption) | 是 | 设置平移参数。 | 399 400**返回值：** 401 402| 类型 | 说明 | 403| --------------------------------- | ---------------------------- | 404| [Matrix4Transit](#matrix4transit) | 平移效果后的矩阵对象。 | 405 406**示例：** 407 408```ts 409// xxx.ets 410import matrix4 from '@ohos.matrix4' 411@Entry 412@Component 413struct Test { 414 private matrix1 = matrix4.identity().translate({ x: 100, y: 200, z: 30 }) 415 416 build() { 417 Column() { 418 Image($r("app.media.bg1")).transform(this.matrix1) 419 .width("40%") 420 .height(100) 421 } 422 } 423} 424``` 425 426 427 428 429### scale 430 431scale(options: ScaleOption): Matrix4Transit 432 433 434Matrix的缩放函数，可以为当前矩阵增加x轴/y轴/z轴缩放效果。会改变调用该函数的原始矩阵。 435 436**系统能力：** SystemCapability.ArkUI.ArkUI.Full 437 438**参数：** 439 440| 参数名 | 类型 | 必填 | 说明 | 441| ------ | --------------------------- | ---- | -------------- | 442| option | [ScaleOption](#scaleoption) | 是 | 设置缩放参数。 | 443 444**返回值：** 445 446| 类型 | 说明 | 447| --------------------------------- | ---------------------------- | 448| [Matrix4Transit](#matrix4transit) |缩放效果后的矩阵对象。 | 449 450**示例：** 451 452```ts 453// xxx.ets 454import matrix4 from '@ohos.matrix4' 455@Entry 456@Component 457struct Test { 458 private matrix1 = matrix4.identity().scale({ x:2, y:3, z:4, centerX:50, centerY:50 }) 459 460 build() { 461 Column() { 462 Image($r("app.media.bg1")).transform(this.matrix1) 463 .width("40%") 464 .height(100) 465 } 466 } 467} 468``` 469 470 471 472 473### rotate 474 475rotate(options: RotateOption): Matrix4Transit 476 477 478Matrix的旋转函数，可以为当前矩阵增加x轴/y轴/z轴旋转效果。会改变调用该函数的原始矩阵。 479 480**系统能力：** SystemCapability.ArkUI.ArkUI.Full 481 482**参数：** 483 484| 参数名 | 类型 | 必填 | 说明 | 485| ------ | ----------------------------- | ---- | -------------- | 486| option | [RotateOption](#rotateoption) | 是 | 设置旋转参数。 | 487 488**返回值：** 489 490| 类型 | 说明 | 491| --------------------------------- | ---------------------------- | 492| [Matrix4Transit](#matrix4transit) | 旋转效果后的矩阵对象。 | 493 494**示例：** 495 496```ts 497// xxx.ets 498import matrix4 from '@ohos.matrix4' 499@Entry 500@Component 501struct Test { 502 private matrix1 = matrix4.identity().rotate({ x: 1, y: 1, z: 2, angle: 30 }) 503 504 build() { 505 Column() { 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 521 522Matrix的坐标点转换函数，可以将当前的变换效果作用到一个坐标点上。 523 524**系统能力：** SystemCapability.ArkUI.ArkUI.Full 525 526**参数：** 527 528| 参数名 | 类型 | 必填 | 说明 | 529| ------ | ---------------- | ---- | ------------------ | 530| option | [number, number] | 是 | 需要转换的坐标点。 | 531 532**返回值：** 533 534| 类型 | 说明 | 535| ---------------- | --------------------------- | 536| [number, number] | 返回矩阵变换后的Point对象。 | 537 538**示例：** 539 540```ts 541// xxx.ets 542import matrix4 from '@ohos.matrix4' 543 544@Entry 545@Component 546struct Test { 547 private originPoint: [number, number] = [50, 50] 548 private matrix_1 = matrix4.identity().translate({ x: 150, y: -50 }) 549 private transformPoint = this.matrix_1.transformPoint(this.originPoint) 550 private matrix_2 = matrix4.identity().translate({ x: this.transformPoint[0], y: this.transformPoint[1] }) 551 552 build() { 553 Column() { 554 Text(`矩阵变换前的坐标：[${this.originPoint}]`) 555 .fontSize(16) 556 Image($r("app.media.image")) 557 .width('600px') 558 .height('300px') 559 .margin({ top: 50 }) 560 Text(`矩阵变换后的坐标：[${this.transformPoint}]`) 561 .fontSize(16) 562 .margin({ top: 100 }) 563 Image($r("app.media.image")) 564 .width('600px') 565 .height('300px') 566 .margin({ top: 50 }) 567 .transform(this.matrix_2) 568 }.width("100%").padding(50) 569 } 570} 571``` 572 573 574 575## TranslateOption 576 577**系统能力：** SystemCapability.ArkUI.ArkUI.Full 578 579| 名称 | 类型 | 必填 | 说明 | 580| ---- | ------ | ---- | ----------------------------------------------------------- | 581| x | number | 否 | x轴的平移距离，单位px。<br/>默认值：0<br/>取值范围 (-∞, +∞) | 582| y | number | 否 | y轴的平移距离，单位px。<br/>默认值：0<br/>取值范围 (-∞, +∞) | 583| z | number | 否 | z轴的平移距离，单位px。<br/>默认值：0<br/>取值范围 (-∞, +∞) | 584 585## ScaleOption 586 587**系统能力：** SystemCapability.ArkUI.ArkUI.Full 588 589| 名称 | 类型 | 必填 | 说明 | 590| ------- | ------ | ---- | ------------------------------------------------------------ | 591| x | number | 否 | x轴的缩放倍数。x>1时以x轴方向放大，0<x<1时以x轴方向缩小，x<0时沿x轴反向并缩放。<br/>默认值：1<br/>取值范围 (-∞, +∞) | 592| y | number | 否 | y轴的缩放倍数。y>1时以y轴方向放大，0<y<1时以y轴方向缩小，y<0时沿y轴反向并缩放。<br/>默认值：1<br/>取值范围 (-∞, +∞) | 593| z | number | 否 | z轴的缩放倍数。z>1时以z轴方向放大，0<z<1时以z轴方向缩小，z<0时沿z轴反向并缩放。<br/>默认值：1<br/>取值范围 (-∞, +∞) | 594| centerX | number | 否 | 变换中心点x轴坐标。<br/>默认值：0。<br/>取值范围 (-∞, +∞) | 595| centerY | number | 否 | 变换中心点y轴坐标。<br/>默认值：0。<br/>取值范围 (-∞, +∞) | 596 597## RotateOption 598 599**系统能力：** SystemCapability.ArkUI.ArkUI.Full 600 601| 名称 | 类型 | 必填 | 说明 | 602| ------- | ------ | ---- | ------------------------------------------------------- | 603| x | number | 否 | 旋转轴向量x坐标。<br/>默认值：0。<br/>取值范围 (-∞, +∞) | 604| y | number | 否 | 旋转轴向量y坐标。<br/>默认值：0。<br/>取值范围 (-∞, +∞) | 605| z | number | 否 | 旋转轴向量z坐标。<br/>默认值：0。<br/>取值范围 (-∞, +∞)<br/>**说明：** 旋转向量中x、y、z至少有一个不为0才有意义。 | 606| angle | number | 否 | 旋转角度。<br/>默认值：0 | 607| centerX | number | 否 | 变换中心点x轴坐标。<br/>默认值：0 | 608| centerY | number | 否 | 变换中心点y轴坐标。<br/>默认值：0 | 609
