1# Matrix2D 2 3矩阵对象，可以对矩阵进行缩放、旋转、平移等变换。 4 5> **说明：** 6> 7> 从 API Version 8 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9## 接口 10 11Matrix2D(unit?: LengthMetricsUnit) 12 13**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 14 15**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 16 17**系统能力：** SystemCapability.ArkUI.ArkUI.Full 18 19**参数：** 20 21| 参数名 | 类型 | 必填 | 说明 | 22| ------ | -------- | ---- | ------------------------------------- | 23| unit<sup>12+</sup> | [LengthMetricsUnit](../js-apis-arkui-graphics.md#lengthmetricsunit12) | 否 | 用来配置Matrix2D对象的单位模式，配置后无法动态更改，配置方法同[CanvasRenderingContext2D](ts-canvasrenderingcontext2d.md#lengthmetricsunit12)。<br>默认值：DEFAULT。| 24 25## 属性 26 27**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 28 29**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 30 31**系统能力：** SystemCapability.ArkUI.ArkUI.Full 32 33| 名称 | 类型 | 只读 | 可选 | 说明 | 34| ----- | ----- | --------------- | ------ | ------------------------ | 35| scaleX | number | 否 | 是 | 水平缩放系数。 | 36| scaleY | number | 否 | 是 | 垂直缩放系数。 | 37| rotateX | number | 否 | 是 | 水平倾斜系数。 | 38| rotateY | number | 否 | 是 | 垂直倾斜系数。 | 39| translateX | number | 否 | 是 | 水平平移距离。<br>默认单位：vp。 | 40| translateY | number | 否 | 是 | 垂直平移距离。<br>默认单位：vp。 | 41 42> **说明：** 43> 44> 可使用[px2vp](ts-pixel-units.md#像素单位转换)接口进行单位转换。 45 46**示例：** 47 48```ts 49// xxx.ets 50@Entry 51@Component 52struct Parameter { 53 private settings: RenderingContextSettings = new RenderingContextSettings(true) 54 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) 55 private matrix : Matrix2D = new Matrix2D() 56 57 build() { 58 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 59 Canvas(this.context) 60 .width('240vp') 61 .height('180vp') 62 .backgroundColor('#ffff00') 63 .onReady(() =>{ 64 this.context.fillRect(100,20,50,50) 65 this.matrix.scaleX = 1 66 this.matrix.scaleY = 1 67 this.matrix.rotateX = -0.5 68 this.matrix.rotateY = 0.5 69 this.matrix.translateX = 10 70 this.matrix.translateY = 10 71 this.context.setTransform(this.matrix) 72 this.context.fillRect(100,20,50,50) 73 }) 74 } 75 .width('100%') 76 .height('100%') 77 } 78} 79``` 80 81 82 83 84## 方法 85 86### identity 87 88identity(): Matrix2D 89 90创建一个单位矩阵。 91 92**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 93 94**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 95 96**系统能力：** SystemCapability.ArkUI.ArkUI.Full 97 98**返回值：** 99 100| 类型 | 说明 | 101| --------------------- | ---------- | 102| [Matrix2D](#matrix2d) | 单位矩阵。 | 103 104**示例：** 105 106```ts 107// xxx.ets 108@Entry 109@Component 110struct Identity { 111 private settings: RenderingContextSettings = new RenderingContextSettings(true) 112 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) 113 private matrix : Matrix2D = new Matrix2D() 114 115 build() { 116 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 117 Canvas(this.context) 118 .width('240vp') 119 .height('180vp') 120 .backgroundColor('#ffff00') 121 .onReady(() =>{ 122 this.context.fillRect(100,20,50,50) 123 this.matrix = this.matrix.identity() 124 this.context.setTransform(this.matrix) 125 this.context.fillRect(100,100,50,50) 126 }) 127 } 128 .width('100%') 129 .height('100%') 130 } 131} 132``` 133 134 135 136 137### invert 138 139invert(): Matrix2D 140 141得到当前矩阵的逆矩阵。 142 143**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 144 145**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 146 147**系统能力：** SystemCapability.ArkUI.ArkUI.Full 148 149**返回值：** 150 151| 类型 | 说明 | 152| --------------------- | ------------ | 153| [Matrix2D](#matrix2d) | 逆矩阵结果。 | 154 155**示例：** 156 157```ts 158// xxx.ets 159@Entry 160@Component 161struct Invert { 162 private settings: RenderingContextSettings = new RenderingContextSettings(true) 163 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) 164 private matrix : Matrix2D = new Matrix2D() 165 166 build() { 167 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 168 Canvas(this.context) 169 .width('240vp') 170 .height('180vp') 171 .backgroundColor('#ffff00') 172 .onReady(() =>{ 173 this.context.fillRect(100,110,50,50) 174 this.matrix.scaleX = 1 175 this.matrix.scaleY = 1 176 this.matrix.rotateX = -0.5 177 this.matrix.rotateY = 0.5 178 this.matrix.translateX = 10 179 this.matrix.translateY = 10 180 this.matrix.invert() 181 this.context.setTransform(this.matrix) 182 this.context.fillRect(100,110,50,50) 183 }) 184 } 185 .width('100%') 186 .height('100%') 187 } 188} 189``` 190 191 192 193 194### multiply<sup>(deprecated) </sup> 195 196multiply(other?: Matrix2D): Matrix2D 197 198当前矩阵与目标矩阵相乘。 199 200**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。该接口为空接口。 201 202该接口从API version 10开始废弃，且无实际绘制效果。 203 204**参数：** 205 206| 参数名 | 类型 | 必填 | 说明 | 207| ----- | -------- | ---- | ---------- | 208| other | Matrix2D | 否 | 目标矩阵。<br>默认值：null。 | 209 210**返回值：** 211 212| 类型 | 说明 | 213| --------------------- | -------------- | 214| [Matrix2D](#matrix2d) | 相乘结果矩阵。 | 215 216**示例：** 217 218```ts 219// xxx.ets 220@Entry 221@Component 222struct Multiply { 223 @State message: string = 'Matrix2D Multiply' 224 225 printMatrix(title: string, matrix: Matrix2D) { 226 console.log(title) 227 console.log("Matrix [scaleX = " + matrix.scaleX + ", scaleY = " + matrix.scaleY + 228 ", rotateX = " + matrix.rotateX + ", rotateY = " + matrix.rotateY + 229 ", translateX = " + matrix.translateX + ", translateY = " + matrix.translateY + "]") 230 } 231 build() { 232 Row() { 233 Column() { 234 Text(this.message) 235 .fontSize(20) 236 .fontWeight(FontWeight.Bold) 237 Button("matrix multiply") 238 .onClick(() => { 239 let matrix : Matrix2D = new Matrix2D() 240 matrix.scaleX = 1 241 matrix.scaleY = 1 242 matrix.rotateX = 0 243 matrix.rotateY = 0 244 matrix.translateX = 0 245 matrix.translateY = 0 246 let other: Matrix2D = new Matrix2D() 247 other.scaleX = 2 248 other.scaleY = 2 249 other.rotateX = 0 250 other.rotateY = 0 251 other.translateX = 10 252 other.translateY = 10 253 other.multiply(other) 254 this.printMatrix(this.message, matrix) 255 }) 256 } 257 .width('100%') 258 } 259 .height('100%') 260 } 261} 262``` 263 264 265 266 267### rotate<sup>(deprecated) </sup> 268 269rotate(rx?: number, ry?: number): Matrix2D 270 271对当前矩阵进行旋转运算。 272 273**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。该接口为空接口。 274 275该接口从API version 10开始废弃，推荐使用[rotate](#rotate10)。 276 277**参数：** 278 279| 参数名 | 类型 | 必填 | 说明 | 280| ---- | ------ | ---- | -------------------------------- | 281| rx | number | 否 | 旋转点的水平方向坐标。<br>默认单位：vp。 | 282| ry | number | 否 | 旋转点的垂直方向坐标。<br>默认单位：vp。 | 283 284**返回值：** 285 286| 类型 | 说明 | 287| --------------------- | -------------------- | 288| [Matrix2D](#matrix2d) | 旋转后结果矩阵对象。 | 289 290**示例：** 291 292```ts 293// xxx.ets 294@Entry 295@Component 296struct Rotate { 297 private settings: RenderingContextSettings = new RenderingContextSettings(true) 298 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) 299 private matrix : Matrix2D = new Matrix2D() 300 301 build() { 302 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 303 Canvas(this.context) 304 .width('240vp') 305 .height('180vp') 306 .backgroundColor('#ffff00') 307 .onReady(() =>{ 308 this.context.fillRect(50,110,50,50) 309 this.matrix.scaleX = 1 310 this.matrix.scaleY = 1 311 this.matrix.rotateX = -0.5 312 this.matrix.rotateY = 0.5 313 this.matrix.translateX = 10 314 this.matrix.translateY = 10 315 this.matrix.rotate(5, 5) 316 this.context.setTransform(this.matrix) 317 this.context.fillRect(50,110,50,50) 318 }) 319 } 320 .width('100%') 321 .height('100%') 322 } 323} 324``` 325 326 327 328 329### rotate<sup>10+</sup> 330 331rotate(degree: number, rx?: number, ry?: number): Matrix2D 332 333以旋转点为中心、对当前矩阵进行右乘旋转运算。 334 335**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 336 337**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 338 339**系统能力：** SystemCapability.ArkUI.ArkUI.Full 340 341**参数：** 342 343| 参数名 | 类型 | 必填 | 说明 | 344| ------ | ------ | ---- | ------------------------------------------------------------ | 345| degree | number | 是 | 旋转角度。顺时针方向为正角度，可以通过 degree * Math.PI / 180 将角度转换为弧度值。<br>默认单位：弧度。| 346| rx | number | 否 | 旋转点的水平方向坐标。<br>默认单位：vp。<br>默认值：0。 | 347| ry | number | 否 | 旋转点的垂直方向坐标。<br>默认单位：vp。<br>默认值：0。 | 348 349**返回值：** 350 351| 类型 | 说明 | 352| --------------------- | -------------------- | 353| [Matrix2D](#matrix2d) | 旋转后结果矩阵对象。 | 354 355**示例：** 356 357```ts 358// xxx.ets 359@Entry 360@Component 361struct Rotate { 362 private settings: RenderingContextSettings = new RenderingContextSettings(true) 363 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) 364 private matrix : Matrix2D = new Matrix2D() 365 366 build() { 367 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 368 Canvas(this.context) 369 .width('240vp') 370 .height('180vp') 371 .backgroundColor('#ffff00') 372 .onReady(() =>{ 373 this.context.fillRect(60,80,50,50) 374 this.matrix.scaleX = 1 375 this.matrix.scaleY = 1 376 this.matrix.rotateX = -0.5 377 this.matrix.rotateY = 0.5 378 this.matrix.translateX = 10 379 this.matrix.translateY = 10 380 this.matrix.rotate(-60 * Math.PI / 180, 5, 5) 381 this.context.setTransform(this.matrix) 382 this.context.fillRect(60,80,50,50) 383 }) 384 } 385 .width('100%') 386 .height('100%') 387 } 388} 389``` 390 391 392 393 394### translate 395 396translate(tx?: number, ty?: number): Matrix2D 397 398对当前矩阵进行左乘平移运算。 399 400**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 401 402**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 403 404**系统能力：** SystemCapability.ArkUI.ArkUI.Full 405 406**参数：** 407 408| 参数名 | 类型 | 必填 | 说明 | 409| ---- | ------ | ---- | ---------------------------- | 410| tx | number | 否 | 水平方向平移距离。<br>默认单位：vp。<br>默认值：0。 | 411| ty | number | 否 | 垂直方向平移距离。<br>默认单位：vp。<br>默认值：0。 | 412 413**返回值：** 414 415| 类型 | 说明 | 416| --------------------- | -------------------- | 417| [Matrix2D](#matrix2d) | 平移后结果矩阵对象。 | 418 419**示例：** 420 421```ts 422// xxx.ets 423@Entry 424@Component 425struct Translate { 426 private settings: RenderingContextSettings = new RenderingContextSettings(true) 427 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) 428 private matrix : Matrix2D = new Matrix2D() 429 430 build() { 431 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 432 Canvas(this.context) 433 .width('240vp') 434 .height('180vp') 435 .backgroundColor('#ffff00') 436 .onReady(() =>{ 437 this.context.fillRect(40,20,50,50) 438 this.matrix.scaleX = 1 439 this.matrix.scaleY = 1 440 this.matrix.rotateX = 0 441 this.matrix.rotateY = 0 442 this.matrix.translateX = 0 443 this.matrix.translateY = 0 444 this.matrix.translate(100, 100) 445 this.context.setTransform(this.matrix) 446 this.context.fillRect(40,20,50,50) 447 }) 448 } 449 .width('100%') 450 .height('100%') 451 } 452} 453``` 454 455 456 457 458### scale 459 460scale(sx?: number, sy?: number): Matrix2D 461 462对当前矩阵进行右乘缩放运算。 463 464**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 465 466**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 467 468**系统能力：** SystemCapability.ArkUI.ArkUI.Full 469 470**参数：** 471 472| 参数 | 类型 | 必填 | 描述 | 473| ---- | ------ | ---- | ------------------ | 474| sx | number | 否 | 水平缩放比例系数。<br>默认值：1.0。 | 475| sy | number | 否 | 垂直缩放比例系数。<br>默认值：1.0。 | 476 477**返回值：** 478 479| 类型 | 说明 | 480| --------------------- | ------------------ | 481| [Matrix2D](#matrix2d) | 缩放结果矩阵对象。 | 482 483**示例：** 484 485```ts 486// xxx.ets 487@Entry 488@Component 489struct Scale { 490 private settings: RenderingContextSettings = new RenderingContextSettings(true) 491 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) 492 private matrix : Matrix2D = new Matrix2D() 493 494 build() { 495 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 496 Canvas(this.context) 497 .width('240vp') 498 .height('180vp') 499 .backgroundColor('#ffff00') 500 .onReady(() =>{ 501 this.context.fillRect(120,70,50,50) 502 this.matrix.scaleX = 1 503 this.matrix.scaleY = 1 504 this.matrix.rotateX = -0.5 505 this.matrix.rotateY = 0.5 506 this.matrix.translateX = 10 507 this.matrix.translateY = 10 508 this.matrix.scale(0.5, 0.5) 509 this.context.setTransform(this.matrix) 510 this.context.fillRect(120,70,50,50) 511 }) 512 } 513 .width('100%') 514 .height('100%') 515 } 516} 517``` 518 519
