1# @ohos.matrix4 (矩阵变换)
2
3本模块提供矩阵变换功能,可对图形进行平移、旋转和缩放等。
4
5> **说明:**
6>
7> 本模块首批接口从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
8
9
10## 导入模块
11
12```ts
13import { matrix4 } from '@kit.ArkUI';
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
21Matrix的构造函数,可以通过传入的参数创建一个四阶矩阵,矩阵为列优先。
22
23**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
24
25**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
26
27**参数:**
28
29| 参数名 | 类型                                                         | 必填 | 说明                                                         |
30| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
31| options | [number,number,number,number,<br/>number,number,number,number,<br/>number,number,number,number,<br/>number,number,number,number] | 是   | 参数为长度为16(4\*4)的number数组,&nbsp;详情见四阶矩阵说明。<br/>默认值:<br/>[1,&nbsp;0,&nbsp;0,&nbsp;0,<br/>0,&nbsp;1,&nbsp;0,&nbsp;0,<br/>0,&nbsp;0,&nbsp;1,&nbsp;0,<br/>0,&nbsp;0,&nbsp;0,&nbsp;1] |
32
33**返回值:**
34
35| 类型                              | 说明                         |
36| --------------------------------- | ---------------------------- |
37| [Matrix4Transit](#matrix4transit) | 根据入参创建的四阶矩阵对象。 |
38
39**四阶矩阵说明:**
40
41| 参数名  | 类型     | 必填   | 说明                   |
42| ---- | ------ | ---- | -------------------- |
43| m00  | number | 是    | x轴缩放值,单位矩阵默认为1。      |
44| m01  | number | 是    | 第2个值,xyz轴旋转或倾斜会影响这个值。   |
45| m02  | number | 是    | 第3个值,xyz轴旋转会影响这个值。   |
46| m03  | number | 是    | 第4个值,透视投影会影响这个值。               |
47| m10  | number | 是    | 第5个值,xyz轴旋转或倾斜会影响这个值。   |
48| m11  | number | 是    | y轴缩放值,单位矩阵默认为1。      |
49| m12  | number | 是    | 第7个值,xyz轴旋转会影响这个值。   |
50| m13  | number | 是    | 第8个值,透视投影会影响这个值。               |
51| m20  | number | 是    | 第9个值,xyz轴旋转会影响这个值。   |
52| m21  | number | 是    | 第10个值,xyz轴旋转会影响这个值。  |
53| m22  | number | 是    | z轴缩放值,单位矩阵默认为1。      |
54| m23  | number | 是    | 第12个值,透视投影会影响这个值。               |
55| m30  | number | 是    | x轴平移值,单位px,单位矩阵默认为0。 |
56| m31  | number | 是    | y轴平移值,单位px,单位矩阵默认为0。 |
57| m32  | number | 是    | z轴平移值,单位px,单位矩阵默认为0。 |
58| m33  | number | 是    | 齐次坐标下生效,产生透视投影效果。    |
59
60**示例**
61
62```ts
63import { matrix4 } from '@kit.ArkUI';
64// 创建一个四阶矩阵
65let matrix = matrix4.init([1.0, 0.0, 0.0, 0.0,
66                          0.0, 1.0, 0.0, 0.0,
67                          0.0, 0.0, 1.0, 0.0,
68                          0.0, 0.0, 0.0, 1.0])
69@Entry
70@Component
71struct Tests {
72  build() {
73    Column() {
74      Image($r("app.media.zh"))
75        .width("40%")
76        .height(100)
77        .transform(matrix)
78    }
79  }
80}
81```
82
83
84## matrix4.identity
85
86identity(): Matrix4Transit
87
88Matrix的初始化函数,可以返回一个单位矩阵对象。
89
90**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
91
92**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
93
94**返回值:**
95
96| 类型                              | 说明           |
97| --------------------------------- | -------------- |
98| [Matrix4Transit](#matrix4transit) | 单位矩阵对象。 |
99
100**示例:**
101
102```ts
103// matrix1 和 matrix2 效果一致
104import { matrix4 } from '@kit.ArkUI';
105let matrix1 = matrix4.init([1.0, 0.0, 0.0, 0.0,
106                          0.0, 1.0, 0.0, 0.0,
107                          0.0, 0.0, 1.0, 0.0,
108                          0.0, 0.0, 0.0, 1.0])
109let matrix2 = matrix4.identity()
110@Entry
111@Component
112struct Tests {
113  build() {
114    Column() {
115      Image($r("app.media.zh"))
116        .width("40%")
117        .height(100)
118        .transform(matrix1)
119      Image($r("app.media.zh"))
120        .width("40%")
121        .height(100)
122        .margin({ top: 150 })
123        .transform(matrix2)
124    }
125  }
126}
127```
128
129## Matrix4Transit
130
131矩阵对象。
132
133**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
134
135**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
136
137### copy
138
139copy(): Matrix4Transit
140
141Matrix的拷贝函数,可以拷贝一份当前的矩阵对象。
142
143**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
144
145**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
146
147**返回值:**
148
149| 类型                              | 说明                 |
150| --------------------------------- | -------------------- |
151| [Matrix4Transit](#matrix4transit) | 当前矩阵的拷贝对象。 |
152
153
154**示例:**
155
156```ts
157// xxx.ets
158import { matrix4 } from '@kit.ArkUI';
159
160@Entry
161@Component
162struct Test {
163  private matrix1 = matrix4.identity().scale({ x: 1.5 })
164  private matrix2 = this.matrix1.copy().translate({ x: 200 })
165  imageSize:Length = '300px'
166  build() {
167    Column({space:"50px"}) {
168      Image($r("app.media.testImage"))
169        .width(this.imageSize)
170        .height(this.imageSize)
171      Image($r("app.media.testImage"))
172        .width(this.imageSize)
173        .height(this.imageSize)
174        .transform(this.matrix1)
175      Image($r("app.media.testImage"))
176        .width(this.imageSize)
177        .height(this.imageSize)
178        .transform(this.matrix2)
179    }.alignItems(HorizontalAlign.Center)
180    .height('100%').width("100%")
181    .justifyContent(FlexAlign.Center)
182  }
183}
184
185```
186
187![zh-cn_image_0000001219744181](figures/h-cn_image_0000001219744185.png)
188### combine
189
190combine(options: Matrix4Transit): Matrix4Transit
191
192Matrix的叠加函数,可以将两个矩阵的效果叠加起来生成一个新的矩阵对象。会改变调用该函数的原始矩阵。
193
194**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
195
196**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
197
198**参数:**
199
200| 参数名 | 类型                              | 必填 | 说明               |
201| ------ | --------------------------------- | ---- | ------------------ |
202| options | [Matrix4Transit](#matrix4transit) | 是   | 待叠加的矩阵对象。 |
203
204**返回值:**
205
206| 类型                              | 说明               |
207| --------------------------------- | ------------------ |
208| [Matrix4Transit](#matrix4transit) | 矩阵叠加后的对象。 |
209
210**示例:**
211
212```ts
213// xxx.ets
214import { matrix4 } from '@kit.ArkUI';
215
216@Entry
217@Component
218struct Test {
219  private matrix1 = matrix4.identity().translate({ x: 200 })
220  private matrix2 = matrix4.identity().scale({ x: 2 })
221
222  build() {
223    Column() {
224      // 矩阵变换前
225      Image($r("app.media.icon"))
226        .width("40%")
227        .height(100)
228        .margin({ top: 50 })
229      // 先平移x轴200px,再缩放两倍x轴,得到矩阵变换后的效果图
230      Image($r("app.media.icon"))
231        .transform(this.matrix1.copy().combine(this.matrix2))
232        .width("40%")
233        .height(100)
234        .margin({ top: 50 })
235    }
236  }
237}
238```
239
240![zh-cn_image_0000001118642902](figures/zh-cn_image_0000001118642902.png)
241
242
243### invert
244
245invert(): Matrix4Transit
246
247Matrix的逆函数,可以返回一个当前矩阵对象的逆矩阵,即效果正好相反。会改变调用该函数的原始矩阵。
248
249**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
250
251**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
252
253**返回值:**
254
255| 类型                              | 说明                   |
256| --------------------------------- | ---------------------- |
257| [Matrix4Transit](#matrix4transit) | 当前矩阵的逆矩阵对象。 |
258
259**示例:**
260
261```ts
262import { matrix4 } from '@kit.ArkUI';
263// matrix1(宽放大2倍) 和 matrix2(宽缩小2倍) 效果相反
264let matrix1 = matrix4.identity().scale({ x: 2 })
265let matrix2 = matrix1.copy().invert()
266
267@Entry
268@Component
269struct Tests {
270  build() {
271    Column() {
272      Image($r("app.media.zh"))
273        .width(200)
274        .height(100)
275        .transform(matrix1)
276        .margin({ top: 100 })
277      Image($r("app.media.zh"))
278        .width(200)
279        .height(100)
280        .margin({ top: 150 })
281        .transform(matrix2)
282    }
283  }
284}
285```
286
287
288### translate
289
290translate(options: TranslateOption): Matrix4Transit
291
292Matrix的平移函数,可以为当前矩阵增加x轴/y轴/z轴平移效果。会改变调用该函数的原始矩阵。
293
294**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
295
296**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
297
298**参数:**
299
300| 参数名 | 类型                                | 必填 | 说明           |
301| ------ | ----------------------------------- | ---- | -------------- |
302| options | [TranslateOption](#translateoption) | 是   | 设置平移参数。 |
303
304**返回值:**
305
306| 类型                              | 说明                         |
307| --------------------------------- | ---------------------------- |
308| [Matrix4Transit](#matrix4transit) | 平移效果后的矩阵对象。 |
309
310**示例:**
311
312```ts
313// xxx.ets
314import { matrix4 } from '@kit.ArkUI';
315
316@Entry
317@Component
318struct Test {
319  private matrix1 = matrix4.identity().translate({ x: 100, y: 200, z: 30 })
320
321  build() {
322    Column() {
323      Image($r("app.media.bg1")).transform(this.matrix1)
324        .width("40%")
325        .height(100)
326    }
327  }
328}
329```
330
331![zh-cn_image_0000001219662645](figures/zh-cn_image_0000001219662645.png)
332
333
334### scale
335
336scale(options: ScaleOption): Matrix4Transit
337
338Matrix的缩放函数,可以为当前矩阵增加x轴/y轴/z轴缩放效果。会改变调用该函数的原始矩阵。
339
340**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
341
342**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
343
344**参数:**
345
346| 参数名 | 类型                        | 必填 | 说明           |
347| ------ | --------------------------- | ---- | -------------- |
348| options | [ScaleOption](#scaleoption) | 是   | 设置缩放参数。 |
349
350**返回值:**
351
352| 类型                              | 说明                         |
353| --------------------------------- | ---------------------------- |
354| [Matrix4Transit](#matrix4transit) | 缩放效果后的矩阵对象。 |
355
356**示例:**
357
358```ts
359// xxx.ets
360import { matrix4 } from '@kit.ArkUI';
361
362@Entry
363@Component
364struct Test {
365  private matrix1 = matrix4.identity()
366    .scale({ x: 2, y: 3, z: 4, centerX: 50, centerY: 50 })
367
368  build() {
369    Column() {
370      Image($r("app.media.testImage")).transform(this.matrix1)
371        .width("300px")
372        .height("300px")
373    }.width("100%").height("100%").justifyContent(FlexAlign.Center)
374  }
375}
376```
377
378![zh-cn_image_0000001219864131](figures/zh-cn_image_0000001219864131.png)
379
380
381### skew<sup>12+</sup>
382
383skew(x: number, y: number): Matrix4Transit
384
385Matrix的倾斜函数,可以为当前矩阵增加x轴/y轴倾斜效果。会改变调用该函数的原始矩阵。
386
387**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
388
389**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
390
391**参数:**
392
393| 参数名 | 类型                        | 必填 | 说明           |
394| ------ | --------------------------- | ---- | -------------- |
395| x | number | 是   | 设置x轴倾斜参数。 |
396| y | number | 是   | 设置y轴倾斜参数。 |
397
398**返回值:**
399
400| 类型                              | 说明                         |
401| --------------------------------- | ---------------------------- |
402| [Matrix4Transit](#matrix4transit) | 倾斜效果后的矩阵对象。 |
403
404**示例:**
405
406```ts
407// xxx.ets
408import { matrix4 } from '@kit.ArkUI';
409@Entry
410@Component
411struct Test {
412  private matrix1 = matrix4.identity().skew(2, 3)
413
414  build() {
415    Column() {
416      Image($r("app.media.bg1")).transform(this.matrix1)
417        .height(100)
418        .margin({
419          top: 300
420        })
421    }
422    .width("100%")
423    .height("100%")
424  }
425}
426```
427
428![zh-cn_image_0000001219864132](figures/zh-cn_image_0000001219864132.jpeg)
429
430
431### rotate
432
433rotate(options: RotateOption): Matrix4Transit
434
435Matrix的旋转函数,可以为当前矩阵增加x轴/y轴/z轴旋转效果。会改变调用该函数的原始矩阵。
436
437**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
438
439**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
440
441**参数:**
442
443| 参数名 | 类型                          | 必填 | 说明           |
444| ------ | ----------------------------- | ---- | -------------- |
445| options | [RotateOption](#rotateoption) | 是   | 设置旋转参数。 |
446
447**返回值:**
448
449| 类型                              | 说明                         |
450| --------------------------------- | ---------------------------- |
451| [Matrix4Transit](#matrix4transit) | 旋转效果后的矩阵对象。 |
452
453**示例:**
454
455```ts
456// xxx.ets
457import { matrix4 } from '@kit.ArkUI';
458
459@Entry
460@Component
461struct Test {
462  private matrix1 = matrix4.identity().rotate({ x: 1, y: 1, z: 2, angle: 30 })
463
464  build() {
465    Column() {
466      Image($r("app.media.bg1")).transform(this.matrix1)
467        .width("40%")
468        .height(100)
469    }.width("100%").margin({ top: 50 })
470  }
471}
472```
473
474![zh-cn_image_0000001174422898](figures/zh-cn_image_0000001174422898.png)
475
476
477### transformPoint
478
479transformPoint(options: [number, number]): [number, number]
480
481Matrix的坐标点转换函数,可以将当前的变换效果作用到一个坐标点上。
482
483**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
484
485**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
486
487**参数:**
488
489| 参数名  | 类型             | 必填 | 说明               |
490| ------- | ---------------- | ---- | ------------------ |
491| options | [number, number] | 是   | 需要转换的坐标点。 |
492
493**返回值:**
494
495| 类型             | 说明                        |
496| ---------------- | --------------------------- |
497| [number, number] | 返回矩阵变换后的Point对象。 |
498
499**示例:**
500
501```ts
502// xxx.ets
503import { matrix4 } from '@kit.ArkUI';
504
505@Entry
506@Component
507struct Test {
508  private originPoint: number[] = [50, 50]
509  private matrix_1 = matrix4.identity().translate({ x: 150, y: -50 })
510  private transformPoint = this.matrix_1.transformPoint([this.originPoint[0], this.originPoint[1]])
511  private matrix_2 = matrix4.identity().translate({ x: this.transformPoint[0], y: this.transformPoint[1] })
512
513  build() {
514    Column() {
515      Text(`矩阵变换前的坐标:[${this.originPoint}]`)
516        .fontSize(16)
517      Image($r("app.media.image"))
518        .width('600px')
519        .height('300px')
520        .margin({ top: 50 })
521      Text(`矩阵变换后的坐标:[${this.transformPoint}]`)
522        .fontSize(16)
523        .margin({ top: 100 })
524      Image($r("app.media.image"))
525        .width('600px')
526        .height('300px')
527        .margin({ top: 50 })
528        .transform(this.matrix_2)
529    }.width("100%").padding(50)
530  }
531}
532```
533
534![zh-cn_image_0000001219864133](figures/zh-cn_image_0000001219864133.PNG)
535
536### setPolyToPoly<sup>12+</sup>
537
538setPolyToPoly(options: PolyToPolyOptions): Matrix4Transit
539
540将一个多边形的顶点坐标映射到另外一个多边形的顶点坐标。
541
542**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
543
544**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
545
546**参数:**
547
548| 参数名 | 类型             | 必填 | 说明               |
549| ------ | ---------------- | ---- | ------------------ |
550| options | [PolyToPolyOptions](#polytopolyoptions12)  | 是   | 映射相关的参数。 |
551
552**返回值:**
553
554| 类型                              | 说明                 |
555| --------------------------------- | -------------------- |
556| [Matrix4Transit](#matrix4transit) | 当前矩阵变换后的对象。 |
557
558> **说明:**
559> 需要配合scale({centerX:0,centerY:0,x:1})保证变换的中心点是组件左上角。
560
561**示例:**
562
563```ts
564import { matrix4 } from '@kit.ArkUI'
565
566@Entry
567@Component
568struct Index {
569  private matrix1 = matrix4.identity().setPolyToPoly({ src: [{x:0, y:0}, {x:500, y:0}, {x:0, y:500}, {x:500, y:500} ],
570    dst:[{x:0, y:0}, {x:500, y:0}, {x:0, y:500}, {x:750, y:1000} ], pointCount:4})
571
572  build() {
573    Stack() {
574      Column().backgroundColor(Color.Blue)
575        .width('500px')
576        .height('500px')
577      Image($r('app.media.transition_image1'))
578        .scale({centerX:0,centerY:0,x:1})
579        .transform(this.matrix1)
580        .width('500px')
581        .height('500px')
582    }.width("100%").height("100%").opacity(0.5)
583  }
584}
585```
586![zh-cn_image_0000001174422898](figures/setPolyTopoly.png)
587## TranslateOption
588
589**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
590
591**系统能力:** SystemCapability.ArkUI.ArkUI.Full
592
593| 名称 | 类型   | 必填 | 说明                                                        |
594| ---- | ------ | ---- | ----------------------------------------------------------- |
595| x    | number | 否   | x轴的平移距离。<br/>单位:px<br/>默认值:0<br/>取值范围 (-∞, +∞) |
596| y    | number | 否   | y轴的平移距离。<br/>单位:px<br/>默认值:0<br/>取值范围 (-∞, +∞) |
597| z    | number | 否   | z轴的平移距离。<br/>单位:px<br/>默认值:0<br/>取值范围 (-∞, +∞) |
598
599## ScaleOption
600
601**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
602
603**系统能力:** SystemCapability.ArkUI.ArkUI.Full
604
605| 名称    | 类型   | 必填 | 说明                                                         |
606| ------- | ------ | ---- | ------------------------------------------------------------ |
607| x       | number | 否   | x轴的缩放倍数。x>1时以x轴方向放大,0&lt;x&lt;1时以x轴方向缩小,x<0时沿x轴反向并缩放。<br/>默认值:1<br/>取值范围 (-∞, +∞) |
608| y       | number | 否   | y轴的缩放倍数。y>1时以y轴方向放大,0&lt;y&lt;1时以y轴方向缩小,y<0时沿y轴反向并缩放。<br/>默认值:1<br/>取值范围 (-∞, +∞) |
609| z       | number | 否   | z轴的缩放倍数。z>1时以z轴方向放大,0&lt;z&lt;1时以z轴方向缩小,z<0时沿z轴反向并缩放。<br/>默认值:1<br/>取值范围 (-∞, +∞) |
610| centerX | number | 否   | 变换中心点x轴坐标。<br/>单位:px<br/>默认值:组件中心点x轴坐标。<br/>取值范围 (-∞, +∞)    |
611| centerY | number | 否   | 变换中心点y轴坐标。<br/>单位:px<br/>默认值:组件中心点y轴坐标。<br/>取值范围 (-∞, +∞)    |
612
613## RotateOption
614
615**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
616
617**系统能力:** SystemCapability.ArkUI.ArkUI.Full
618
619| 名称    | 类型   | 必填 | 说明                                                         |
620| ------- | ------ | ---- | ------------------------------------------------------------ |
621| x       | number | 否   | 旋转轴向量x坐标。<br/>默认值:0。<br/>取值范围 (-∞, +∞)      |
622| y       | number | 否   | 旋转轴向量y坐标。<br/>默认值:0。<br/>取值范围 (-∞, +∞)      |
623| z       | number | 否   | 旋转轴向量z坐标。<br/>默认值:0。<br/>取值范围 (-∞, +∞)。<br/>**说明:** 旋转向量中x、y、z至少有一个不为0才有意义。 |
624| angle   | number | 否   | 旋转角度。<br/>默认值:0                                     |
625| centerX | number | 否   | 单次矩阵变换中心点相对于组件变换中心点(锚点)的额外x轴偏移值。<br/>单位:px<br/>默认值:0<br/>**说明:** <br/>为0时表示x方向的矩阵变换中心恰好为组件x方向锚点,取值表示相对组件x方向锚点的额外偏移量。具体实现可参考[示例3(按中心点旋转)](arkui-ts/ts-universal-attributes-transformation.md#示例3按中心点旋转)。 |
626| centerY | number | 否   | 单次矩阵变换中心点相对于组件变换中心点(锚点)的额外y轴偏移值。<br/>单位:px<br/>默认值:0<br/>**说明:** <br/>为0时表示y方向的矩阵变换中心恰好为组件y方向锚点,取值表示相对组件y方向锚点的额外偏移量。具体实现可参考[示例3(按中心点旋转)](arkui-ts/ts-universal-attributes-transformation.md#示例3按中心点旋转)。 |
627
628## PolyToPolyOptions<sup>12+</sup>
629
630**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
631
632**系统能力:** SystemCapability.ArkUI.ArkUI.Full
633
634| 名称 | 类型   | 必填 | 说明                                                        |
635| ---- | ------ | ---- | ----------------------------------------------------------- |
636| src    |  Array<[Point](#point12)> | 是   | 源点坐标。 |
637| srcIndex    | number | 否   | 源点坐标起始索引。<br>默认值:0。|
638| dst    |  Array<[Point](#point12)>  | 是   | 目标点坐标。 |
639| dstIndex    | number | 否   |  目标坐标起始索引。<br>默认值:0。 |
640| pointCount    | number | 否   | 使用到的点数量。<br>默认值: src.length/2。|
641
642## Point<sup>12+</sup>
643
644**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
645
646**系统能力:** SystemCapability.ArkUI.ArkUI.Full
647
648| 名称 | 类型   | 必填 | 说明                                                        |
649| ---- | ------ | ---- | ----------------------------------------------------------- |
650| x    |  number | 是   | x轴坐标。 |
651| y    | number | 是   | y轴坐标。 |
652
653## matrix4.copy<sup>(deprecated)</sup>
654
655copy(): Matrix4Transit
656
657
658Matrix的拷贝函数,可以拷贝一份当前的矩阵对象。
659
660> **说明:**
661>
662> 从API version 10开始废弃。建议使用[Matrix4Transit.copy](#copy)替代。
663
664
665**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
666
667**返回值:**
668
669| 类型                              | 说明                 |
670| --------------------------------- | -------------------- |
671| [Matrix4Transit](#matrix4transit) | 当前矩阵的拷贝对象。 |
672
673**示例:**
674
675```ts
676// xxx.ets
677import { matrix4 } from '@kit.ArkUI';
678
679@Entry
680@Component
681struct Test {
682  private matrix1 = matrix4.identity().translate({ x: 100 })
683  // 对matrix1的拷贝矩阵做scale操作,不影响到matrix1
684  private matrix2 = this.matrix1.copy().scale({ x: 2 })
685
686  build() {
687    Column() {
688      Image($r("app.media.bg1"))
689        .width("40%")
690        .height(100)
691        .transform(this.matrix1)
692      Image($r("app.media.bg2"))
693        .width("40%")
694        .height(100)
695        .margin({ top: 50 })
696        .transform(this.matrix2)
697    }
698  }
699}
700```
701
702![zh-cn_image_0000001219744181](figures/zh-cn_image_0000001219744181.png)
703
704## matrix4.invert<sup>(deprecated)</sup>
705
706invert(): Matrix4Transit
707
708Matrix的逆函数,可以返回一个当前矩阵对象的逆矩阵,即效果正好相反。
709
710> **说明:**
711>
712> 从API version 10开始废弃。建议使用[Matrix4Transit.invert](#invert)替代。
713
714**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
715
716**返回值:**
717
718| 类型                              | 说明                   |
719| --------------------------------- | ---------------------- |
720| [Matrix4Transit](#matrix4transit) | 当前矩阵的逆矩阵对象。 |
721
722## matrix4.combine<sup>(deprecated)</sup>
723
724combine(options: Matrix4Transit): Matrix4Transit
725
726Matrix的叠加函数,可以将两个矩阵的效果叠加起来生成一个新的矩阵对象。
727
728> **说明:**
729>
730> 从API version 10开始废弃。建议使用[Matrix4Transit.combine](#combine)替代。
731
732**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
733
734**参数:**
735
736| 参数名  | 类型                              | 必填 | 说明               |
737| ------- | --------------------------------- | ---- | ------------------ |
738| options | [Matrix4Transit](#matrix4transit) | 是   | 待叠加的矩阵对象。 |
739
740**返回值:**
741
742| 类型                              | 说明                   |
743| --------------------------------- | ---------------------- |
744| [Matrix4Transit](#matrix4transit) | 叠加后的矩阵对象。 |
745
746## matrix4.translate<sup>(deprecated)</sup>
747
748translate(options: TranslateOption): Matrix4Transit
749
750Matrix的平移函数,可以为当前矩阵增加x轴/y轴/z轴平移效果。
751
752> **说明:**
753>
754> 从API version 10开始废弃。建议使用[Matrix4Transit.translate](#translate)替代。
755
756**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
757
758**参数:**
759
760| 参数名  | 类型                                | 必填 | 说明           |
761| ------- | ----------------------------------- | ---- | -------------- |
762| options | [TranslateOption](#translateoption) | 是   | 设置平移参数。 |
763
764**返回值:**
765
766| 类型                              | 说明                   |
767| --------------------------------- | ---------------------- |
768| [Matrix4Transit](#matrix4transit) | 平移后的矩阵对象。 |
769
770## matrix4.scale<sup>(deprecated)</sup>
771
772scale(options: ScaleOption): Matrix4Transit
773
774Matrix的缩放函数,可以为当前矩阵增加x轴/y轴/z轴缩放效果。
775
776> **说明:**
777>
778> 从API version 10开始废弃。建议使用[Matrix4Transit.scale](#scale)替代。
779
780**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
781
782**参数:**
783
784| 参数名  | 类型                        | 必填 | 说明           |
785| ------- | --------------------------- | ---- | -------------- |
786| options | [ScaleOption](#scaleoption) | 是   | 设置缩放参数。 |
787
788**返回值:**
789
790| 类型                              | 说明                   |
791| --------------------------------- | ---------------------- |
792| [Matrix4Transit](#matrix4transit) | 缩放后的矩阵对象。 |
793
794## matrix4.rotate<sup>(deprecated)</sup>
795
796rotate(options: RotateOption): Matrix4Transit
797
798Matrix的旋转函数,可以为当前矩阵增加x轴/y轴/z轴旋转效果。
799
800> **说明:**
801>
802> 从API version 10开始废弃。建议使用[Matrix4Transit.rotate](#rotate)替代。
803
804**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
805
806**参数:**
807
808| 参数名  | 类型                          | 必填 | 说明           |
809| ------- | ----------------------------- | ---- | -------------- |
810| options | [RotateOption](#rotateoption) | 是   | 设置旋转参数。 |
811
812**返回值:**
813
814| 类型                              | 说明                   |
815| --------------------------------- | ---------------------- |
816| [Matrix4Transit](#matrix4transit) | 旋转后的矩阵对象。 |
817
818## matrix4.transformPoint<sup>(deprecated)</sup>
819
820transformPoint(options: [number, number]): [number, number]
821
822Matrix的坐标点转换函数,可以将当前的变换效果作用到一个坐标点上。
823
824> **说明:**
825>
826> 从API version 10开始废弃。建议使用[Matrix4Transit.transformPoint](#transformpoint)替代。
827
828**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
829
830**参数:**
831
832| 参数名  | 类型             | 必填 | 说明               |
833| ------- | ---------------- | ---- | ------------------ |
834| options | [number, number] | 是   | 需要转换的坐标点。 |
835
836**返回值:**
837
838| 类型             | 说明                        |
839| ---------------- | --------------------------- |
840| [number, number] | 返回矩阵变换后的Point对象。 |