1# 矩阵变换 2 3> **说明：** 4> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 5 6 7## 导入模块 8 9```ts 10import matrix4 from '@ohos.matrix4' 11``` 12 13 14## 权限列表 15 16无 17 18 19## matrix4.init 20 21init(array: Array<number>): Object 22 23 24Matrix的构造函数，可以通过传入的参数创建一个四阶矩阵，矩阵为列优先。 25 26 27- 参数 28 | 参数名 | 类型 | 必填 | 默认值 | 说明 | 29 | -------- | -------- | -------- | -------- | -------- | 30 | array | Array<number> | 是 | [1, 0, 0, 0,<br/>0, 1, 0, 0,<br/>0, 0, 1, 0,<br/>0, 0, 0, 1] | 参数为长度为16（4\*4）的number数组, 详情见参数描述。 | 31 32- 返回值 33 | 类型 | 说明 | 34 | -------- | -------- | 35 | Object | 根据入参创建的四阶矩阵对象。 | 36 37- 参数描述 38 | 参数名 | 类型 | 必填 | 说明 | 39 | -------- | -------- | -------- | -------- | 40 | m00 | number | 是 | x轴缩放值，单位矩阵默认为1。 | 41 | m01 | number | 是 | 第2个值，xyz轴旋转会影响这个值。 | 42 | m02 | number | 是 | 第3个值，xyz轴旋转会影响这个值。 | 43 | m03 | number | 是 | 无实际意义。 | 44 | m10 | number | 是 | 第5个值，xyz轴旋转会影响这个值。 | 45 | m11 | number | 是 | y轴缩放值，单位矩阵默认为1。 | 46 | m12 | number | 是 | 第7个值，xyz轴旋转会影响这个值。 | 47 | m13 | number | 是 | 无实际意义。 | 48 | m20 | number | 是 | 第9个值，xyz轴旋转会影响这个值。 | 49 | m21 | number | 是 | 第10个值，xyz轴旋转会影响这个值。 | 50 | m22 | number | 是 | z轴缩放值，单位矩阵默认为1。 | 51 | m23 | number | 是 | 无实际意义。 | 52 | m30 | number | 是 | x轴平移值，单位px，单位矩阵默认为0。 | 53 | m31 | number | 是 | y轴平移值，单位px，单位矩阵默认为0。 | 54 | m32 | number | 是 | z轴平移值，单位px，单位矩阵默认为0。 | 55 | m33 | number | 是 | 齐次坐标下生效，产生透视投影效果。 | 56 57- 示例 58 ```ts 59 import matrix4 from '@ohos.matrix4' 60 // 创建一个四阶矩阵 61 let matrix = matrix4.init([1.0, 0.0, 0.0, 0.0, 62 0.0, 1.0, 0.0, 0.0, 63 0.0, 0.0, 1.0, 0.0, 64 0.0, 0.0, 0.0, 1.0]) 65 ``` 66 67 68## matrix4.identity 69 70identity(): Object 71 72 73Matrix的初始化函数，可以返回一个单位矩阵对象。 74 75 76- 返回值 77 | 类型 | 说明 | 78 | -------- | -------- | 79 | Object | 单位矩阵对象。 | 80 81- 示例 82 ```ts 83 // matrix1 和 matrix2 效果一致 84 import matrix4 from '@ohos.matrix4' 85 let matrix = matrix4.init([1.0, 0.0, 0.0, 0.0, 86 0.0, 1.0, 0.0, 0.0, 87 0.0, 0.0, 1.0, 0.0, 88 0.0, 0.0, 0.0, 1.0]) 89 let matrix2 = matrix4.identity() 90 ``` 91 92 93## matrix4.copy 94 95copy(): Object 96 97 98Matrix的拷贝函数，可以拷贝一份当前的矩阵对象。 99 100 101- 返回值 102 | 类型 | 说明 | 103 | -------- | -------- | 104 | Object | 当前矩阵的拷贝对象。 | 105 106- 示例 107 ```ts 108 import matrix4 from '@ohos.matrix4' 109 @Entry 110 @Component 111 struct Test { 112 private matrix1 = matrix4.identity().translate({x:100}) 113 private matrix2 = this.matrix1.copy().scale({x:2}) 114 build() { 115 Column() { 116 Image($r("app.media.bg1")) 117 .width("40%") 118 .height(100) 119 .transform(this.matrix1) 120 Image($r("app.media.bg2")) 121 .width("40%") 122 .height(100) 123 .margin({top:50}) 124 .transform(this.matrix2) 125 } 126 } 127 } 128 ``` 129 130  131 132 133## Matrix4 134 135 136### combine 137 138combine(matrix: Matrix4): Object 139 140 141Matrix的叠加函数，可以将两个矩阵的效果叠加起来生成一个新的矩阵对象。 142 143 144- 参数 145 | 参数名 | 类型 | 必填 | 默认值 | 说明 | 146 | -------- | -------- | -------- | -------- | -------- | 147 | matrix | Matrix4 | 是 | - | 待叠加的矩阵对象。 | 148 149- 返回值 150 | 类型 | 说明 | 151 | -------- | -------- | 152 | Object | 矩阵叠加后的对象。 | 153 154- 示例 155 ```ts 156 import matrix4 from '@ohos.matrix4' 157 @Entry 158 @Component 159 struct Test { 160 private matrix1 = matrix4.identity().translate({x:200}).copy() 161 private matrix2 = matrix4.identity().scale({x:2}).copy() 162 build() { 163 Column() { 164 // 先平移x轴100px，再缩放两倍x轴 165 Image($r("app.media.bg1")).transform(this.matrix1.combine(this.matrix2)) 166 .width("40%") 167 .height(100) 168 .margin({top:50}) 169 } 170 } 171 } 172 ``` 173 174  175 176 177### invert 178 179invert(): Object 180 181 182Matrix的逆函数，可以返回一个当前矩阵对象的逆矩阵，即效果正好相反。 183 184 185- 返回值 186 | 类型 | 说明 | 187 | -------- | -------- | 188 | Object | 当前矩阵的逆矩阵对象。 | 189 190- 示例 191 ```ts 192 import matrix4 from '@ohos.matrix4' 193 // matrix1(宽放大2倍) 和 matrix2(宽缩小2倍) 效果相反 194 let matrix1 = matrix4.identity().scale({x:2}) 195 let matrix2 = matrix1.copy().invert() 196 ``` 197 198 199### translate 200 201translate({x?: number, y?: number, z?: number}): Object 202 203 204Matrix的平移函数，可以为当前矩阵增加x轴/Y轴/Z轴平移效果。 205 206 207- 参数 208 | 参数名 | 类型 | 必填 | 默认值 | 说明 | 209 | -------- | -------- | -------- | -------- | -------- | 210 | x | number | 否 | 0 | x轴的平移距离，单位px。 | 211 | y | number | 否 | 0 | y轴的平移距离，单位px。 | 212 | z | number | 否 | 0 | z轴的平移距离，单位px。 | 213 214 215- 返回值 216 | 类型 | 说明 | 217 | -------- | -------- | 218 | Object | 增加好平移效果后的矩阵对象。 | 219 220- 示例 221 ```ts 222 import matrix4 from '@ohos.matrix4' 223 @Entry 224 @Component 225 struct Test { 226 private matrix1 = matrix4.identity().translate({x:100, y:200, z:30}) 227 build() { 228 Column() { 229 Image($r("app.media.bg1")).transform(this.matrix1) 230 .width("40%") 231 .height(100) 232 } 233 } 234 } 235 ``` 236 237  238 239 240### scale 241 242scale({x?: number, y?: number, z?: number, centerX?: number, centerY?: number}): Object 243 244 245Matrix的缩放函数，可以为当前矩阵增加x轴/Y轴/Z轴缩放效果。 246 247 248- 参数 249 | 参数名 | 类型 | 必填 | 默认值 | 说明 | 250 | -------- | -------- | -------- | -------- | -------- | 251 | x | number | 否 | 1 | x轴的缩放倍数。 | 252 | y | number | 否 | 1 | y轴的缩放倍数。 | 253 | z | number | 否 | 1 | z轴的缩放倍数。 | 254 | centerX | number | 否 | 0 | 变换中心点x轴坐标。 | 255 | centerY | number | 否 | 0 | 变换中心点y轴坐标。 | 256 257 258- 返回值 259 | 类型 | 说明 | 260 | -------- | -------- | 261 | Object | 增加好缩放效果后的矩阵对象。 | 262 263- 示例 264 ```ts 265 import matrix4 from '@ohos.matrix4' 266 @Entry 267 @Component 268 struct Test { 269 private matrix1 = matrix4.identity().scale({x:2, y:3, z:4, centerX:50, centerY:50}) 270 build() { 271 Column() { 272 Image($r("app.media.bg1")).transform(this.matrix1) 273 .width("40%") 274 .height(100) 275 } 276 } 277 } 278 ``` 279 280  281 282 283### rotate 284 285rotate({x?: number, y?: number, z?: number, angle?: number, centerX?: Length, centerY?: Length}): Object 286 287 288Matrix的旋转函数，可以为当前矩阵增加x轴/Y轴/Z轴旋转效果。 289 290 291- 参数 292 | 参数名 | 类型 | 必填 | 默认值 | 说明 | 293 | -------- | -------- | -------- | -------- | -------- | 294 | x | number | 否 | 1 | 旋转轴向量x坐标。 | 295 | y | number | 否 | 1 | 旋转轴向量y坐标。 | 296 | z | number | 否 | 1 | 旋转轴向量z坐标。 | 297 | angle | number | 否 | 0 | 旋转角度。 | 298 | centerX | number | 否 | 0 | 变换中心点x轴坐标。 | 299 | centerY | number | 否 | 0 | 变换中心点y轴坐标。 | 300 301 302- 返回值 303 | 类型 | 说明 | 304 | -------- | -------- | 305 | Object | 增加好旋转效果后的矩阵对象。 | 306 307- 示例 308 ```ts 309 import matrix4 from '@ohos.matrix4' 310 @Entry 311 @Component 312 struct Test { 313 private matrix1 = matrix4.identity().rotate({x:1, y:1, z:2, angle:30}) 314 build() { 315 Column() { 316 Image($r("app.media.bg1")).transform(this.matrix1) 317 .width("40%") 318 .height(100) 319 }.width("100%").margin({top:50}) 320 } 321 } 322 ``` 323 324  325 326 327### transformPoint 328 329transformPoint(point: Point): Point 330 331 332Matrix的坐标点转换函数，可以将当前的变换效果作用到一个坐标点上。 333 334 335- 参数 336 | 参数名 | 类型 | 必填 | 默认值 | 说明 | 337 | -------- | -------- | -------- | -------- | -------- | 338 | point | Point | 是 | - | 需要转换的坐标点。 | 339 340 341- 返回值 342 | 类型 | 说明 | 343 | -------- | -------- | 344 | Point | 返回矩阵变换后的Point对象。 | 345 346- 示例 347 ```ts 348 import matrix4 from '@ohos.matrix4' 349 import prompt from '@system.prompt' 350 351 @Entry 352 @Component 353 struct Test { 354 private matrix1 = matrix4.identity().transformPoint([100, 10]) 355 build() { 356 Column() { 357 Button("get Point") 358 .onClick(() => { 359 prompt.showToast({message:JSON.stringify(this.matrix1),duration:2000}) 360 }).backgroundColor(0x2788D9) 361 }.width("100%").padding(50) 362 } 363 } 364 ``` 365 366  367
