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(option: [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,number,number,number,number,number,number,number,number,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 private matrix2 = this.matrix1.copy().scale({ x: 2 }) 153 154 build() { 155 Column() { 156 Image($r("app.media.bg1")) 157 .width("40%") 158 .height(100) 159 .transform(this.matrix1) 160 Image($r("app.media.bg2")) 161 .width("40%") 162 .height(100) 163 .margin({ top: 50 }) 164 .transform(this.matrix2) 165 } 166 } 167} 168``` 169 170 171 172 173## Matrix4Transit 174 175 176### combine 177 178combine(option: Matrix4Transit): Matrix4Transit 179 180 181Matrix的叠加函数，可以将两个矩阵的效果叠加起来生成一个新的矩阵对象。 182 183**系统能力：** SystemCapability.ArkUI.ArkUI.Full 184 185**参数：** 186 187| 参数名 | 类型 | 必填 | 说明 | 188| ------ | --------------------------------- | ---- | ------------------ | 189| option | [Matrix4Transit](#matrix4transit) | 是 | 待叠加的矩阵对象。 | 190 191**返回值：** 192 193| 类型 | 说明 | 194| --------------------------------- | ------------------ | 195| [Matrix4Transit](#matrix4transit) | 矩阵叠加后的对象。 | 196 197**示例：** 198 199```ts 200// xxx.ets 201import matrix4 from '@ohos.matrix4' 202@Entry 203@Component 204struct Test { 205 private matrix1 = matrix4.identity().translate({ x: 200 }).copy() 206 private matrix2 = matrix4.identity().scale({ x: 2 }).copy() 207 208 build() { 209 Column() { 210 // 矩阵变换前 211 Image($r("app.media.icon")) 212 .width("40%") 213 .height(100) 214 .margin({ top: 50 }) 215 // 先平移x轴200px，再缩放两倍x轴，得到矩阵变换后的效果图 216 Image($r("app.media.icon")) 217 .transform(this.matrix1.combine(this.matrix2)) 218 .width("40%") 219 .height(100) 220 .margin({ top: 50 }) 221 } 222 } 223} 224``` 225 226 227 228 229### invert 230 231invert(): Matrix4Transit 232 233Matrix的逆函数，可以返回一个当前矩阵对象的逆矩阵，即效果正好相反。 234 235**系统能力：** SystemCapability.ArkUI.ArkUI.Full 236 237**返回值：** 238 239| 类型 | 说明 | 240| --------------------------------- | ---------------------- | 241| [Matrix4Transit](#matrix4transit) | 当前矩阵的逆矩阵对象。 | 242 243**示例：** 244 245```ts 246import matrix4 from '@ohos.matrix4' 247// matrix1(宽放大2倍) 和 matrix2(宽缩小2倍) 效果相反 248let matrix1 = matrix4.identity().scale({ x: 2 }) 249let matrix2 = matrix1.invert() 250@Entry 251@Component 252struct Tests { 253 build() { 254 Column() { 255 Image($r("app.media.zh")) 256 .width(200) 257 .height(100) 258 .transform(matrix1) 259 .margin({ top: 100 }) 260 Image($r("app.media.zh")) 261 .width(200) 262 .height(100) 263 .margin({ top: 150 }) 264 .transform(matrix2) 265 } 266 } 267} 268``` 269 270 271### translate 272 273translate(option: TranslateOption): Matrix4Transit 274 275Matrix的平移函数，可以为当前矩阵增加x轴/y轴/z轴平移效果。 276 277**系统能力：** SystemCapability.ArkUI.ArkUI.Full 278 279**参数：** 280 281| 参数名 | 类型 | 必填 | 说明 | 282| ------ | ----------------------------------- | ---- | -------------- | 283| option | [TranslateOption](#translateoption) | 是 | 设置平移参数。 | 284 285**返回值：** 286 287| 类型 | 说明 | 288| --------------------------------- | ---------------------------- | 289| [Matrix4Transit](#matrix4transit) | 增加好平移效果后的矩阵对象。 | 290 291**示例：** 292 293```ts 294// xxx.ets 295import matrix4 from '@ohos.matrix4' 296@Entry 297@Component 298struct Test { 299 private matrix1 = matrix4.identity().translate({ x: 100, y: 200, z: 30 }) 300 301 build() { 302 Column() { 303 Image($r("app.media.bg1")).transform(this.matrix1) 304 .width("40%") 305 .height(100) 306 } 307 } 308} 309``` 310 311 312 313 314### scale 315 316scale(option: ScaleOption): Matrix4Transit 317 318 319Matrix的缩放函数，可以为当前矩阵增加x轴/y轴/z轴缩放效果。 320 321**系统能力：** SystemCapability.ArkUI.ArkUI.Full 322 323**参数：** 324 325| 参数名 | 类型 | 必填 | 说明 | 326| ------ | --------------------------- | ---- | -------------- | 327| option | [ScaleOption](#scaleoption) | 是 | 设置缩放参数。 | 328 329**返回值：** 330 331| 类型 | 说明 | 332| --------------------------------- | ---------------------------- | 333| [Matrix4Transit](#matrix4transit) | 增加好平移效果后的矩阵对象。 | 334 335**返回值：** 336 337| 类型 | 说明 | 338| --------------------------------- | ---------------------------- | 339| [Matrix4Transit](#matrix4transit) | 增加好缩放效果后的矩阵对象。 | 340 341**示例：** 342 343```ts 344// xxx.ets 345import matrix4 from '@ohos.matrix4' 346@Entry 347@Component 348struct Test { 349 private matrix1 = matrix4.identity().scale({ x:2, y:3, z:4, centerX:50, centerY:50 }) 350 351 build() { 352 Column() { 353 Image($r("app.media.bg1")).transform(this.matrix1) 354 .width("40%") 355 .height(100) 356 } 357 } 358} 359``` 360 361 362 363 364### rotate 365 366rotate(option: RotateOption): Matrix4Transit 367 368 369Matrix的旋转函数，可以为当前矩阵增加x轴/y轴/z轴旋转效果。 370 371**系统能力：** SystemCapability.ArkUI.ArkUI.Full 372 373**参数：** 374 375| 参数名 | 类型 | 必填 | 说明 | 376| ------ | ----------------------------- | ---- | -------------- | 377| option | [RotateOption](#rotateoption) | 是 | 设置旋转参数。 | 378 379**返回值：** 380 381| 类型 | 说明 | 382| --------------------------------- | ---------------------------- | 383| [Matrix4Transit](#matrix4transit) | 增加好平移效果后的矩阵对象。 | 384 385**返回值：** 386 387| 类型 | 说明 | 388| --------------------------------- | ---------------------------- | 389| [Matrix4Transit](#matrix4transit) | 增加好旋转效果后的矩阵对象。 | 390 391**示例：** 392 393```ts 394// xxx.ets 395import matrix4 from '@ohos.matrix4' 396@Entry 397@Component 398struct Test { 399 private matrix1 = matrix4.identity().rotate({ x: 1, y: 1, z: 2, angle: 30 }) 400 401 build() { 402 Column() { 403 Image($r("app.media.bg1")).transform(this.matrix1) 404 .width("40%") 405 .height(100) 406 }.width("100%").margin({ top: 50 }) 407 } 408} 409``` 410 411 412 413 414### transformPoint 415 416transformPoint(option: [number, number]): [number, number] 417 418 419Matrix的坐标点转换函数，可以将当前的变换效果作用到一个坐标点上。 420 421**系统能力：** SystemCapability.ArkUI.ArkUI.Full 422 423**参数：** 424 425| 参数名 | 类型 | 必填 | 说明 | 426| ------ | ---------------- | ---- | ------------------ | 427| option | [number, number] | 是 | 需要转换的坐标点。 | 428 429**返回值：** 430 431| 类型 | 说明 | 432| ---------------- | --------------------------- | 433| [number, number] | 返回矩阵变换后的Point对象。 | 434 435**示例：** 436 437```ts 438// xxx.ets 439import matrix4 from '@ohos.matrix4' 440 441@Entry 442@Component 443struct Test { 444 private originPoint: [number, number] = [50, 50] 445 private matrix_1 = matrix4.identity().translate({ x: 150, y: -50 }) 446 private transformPoint = this.matrix_1.transformPoint(this.originPoint) 447 private matrix_2 = matrix4.identity().translate({ x: this.transformPoint[0], y: this.transformPoint[1] }) 448 449 build() { 450 Column() { 451 Text(`矩阵变换前的坐标：[${this.originPoint}]`) 452 .fontSize(16) 453 Image($r("app.media.image")) 454 .width('600px') 455 .height('300px') 456 .margin({ top: 50 }) 457 Text(`矩阵变换后的坐标：[${this.transformPoint}]`) 458 .fontSize(16) 459 .margin({ top: 100 }) 460 Image($r("app.media.image")) 461 .width('600px') 462 .height('300px') 463 .margin({ top: 50 }) 464 .transform(this.matrix_2) 465 }.width("100%").padding(50) 466 } 467} 468``` 469 470 471 472## TranslateOption 473 474| 参数名 | 类型 | 必填 | 说明 | 475| ------ | ------ | ---- | ----------------------------------------------------------- | 476| x | number | 否 | x轴的平移距离，单位px。<br/>默认值：0<br/>取值范围 (-∞, +∞) | 477| y | number | 否 | y轴的平移距离，单位px。<br/>默认值：0<br/>取值范围 (-∞, +∞) | 478| z | number | 否 | z轴的平移距离，单位px。<br/>默认值：0<br/>取值范围 (-∞, +∞) | 479 480## ScaleOption 481 482| 参数名 | 类型 | 必填 | 说明 | 483| ------- | ------ | ---- | ------------------------------------------------------------ | 484| x | number | 否 | x轴的缩放倍数。x>1时以x轴方向放大，x<1时以x轴方向缩小。<br/>默认值：1<br/>取值范围 [0, +∞)<br/>**说明：** <br/>设置小于0的值时，按照默认值处理。 | 485| y | number | 否 | y轴的缩放倍数。y>1时以y轴方向放大，y<1时以y轴方向缩小。<br/>默认值：1<br/>取值范围 [0, +∞)<br/>**说明：** <br/>设置小于0的值时，按照默认值处理。 | 486| z | number | 否 | z轴的缩放倍数。z>1时以z轴方向放大，z<1时以z轴方向缩小。<br/>默认值：1<br/>取值范围 [0, +∞)<br/>**说明：** <br/>设置小于0的值时，按照默认值处理。 | 487| centerX | number | 否 | 变换中心点x轴坐标。<br/>默认值：0。<br/>取值范围 (-∞, +∞) | 488| centerY | number | 否 | 变换中心点y轴坐标。<br/>默认值：0。<br/>取值范围 (-∞, +∞) | 489 490## RotateOption 491 492| 参数名 | 类型 | 必填 | 说明 | 493| ------- | ------ | ---- | ------------------------------------------------------- | 494| x | number | 否 | 旋转轴向量x坐标。<br/>默认值：1。<br/>取值范围 (-∞, +∞) | 495| y | number | 否 | 旋转轴向量y坐标。<br/>默认值：1。<br/>取值范围 (-∞, +∞) | 496| z | number | 否 | 旋转轴向量z坐标。<br/>默认值：1。<br/>取值范围 (-∞, +∞) | 497| angle | number | 否 | 旋转角度。<br/>默认值：0 | 498| centerX | number | 否 | 变换中心点x轴坐标。<br/>默认值：0 | 499| centerY | number | 否 | 变换中心点y轴坐标。<br/>默认值：0 | 500
