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