1# 页面间转场 (pageTransition) 2 3当路由进行切换时，可以通过在pageTransition函数中自定义页面入场和页面退场的转场动效。详细指导请参考[页面转场动画](../../../ui/arkts-page-transition-animation.md)。 4 5> **说明：** 6> 7> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9> 为了实现更好的转场效果，推荐使用[Navigation组件](../../../ui/arkts-navigation-navigation.md)和[模态转场](../../../ui/arkts-modal-transition.md)。 10 11## pageTransition 12 13pageTransition?(): void 14 15进入此页面或移动到其他页面时实现动画。 16 17**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 18 19**系统能力：** SystemCapability.ArkUI.ArkUI.Full 20 21## PageTransitionEnter 22 23PageTransitionEnter(value: PageTransitionOptions) 24 25设置当前页面的自定义入场动效。继承自[CommonTransition](#commontransition)。 26 27**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 28 29**系统能力：** SystemCapability.ArkUI.ArkUI.Full 30 31**参数：** 32 33| 参数名 | 类型 | 必填 | 说明 | 34| ------ | ------------------------------------------------------ | ---- | -------------------- | 35| value | [PageTransitionOptions](#pagetransitionoptions对象说明) | 是 | 配置入场动效的参数。 | 36 37### onEnter 38 39onEnter(event: (type: RouteType, progress: number) => void): PageTransitionEnterInterface 40 41逐帧回调，直到入场动画结束，progress从0变化到1。 42 43**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 44 45**系统能力：** SystemCapability.ArkUI.ArkUI.Full 46 47**参数：** 48 49| 参数名 | 类型 | 必填 | 说明 | 50| ------ | ----------------------------------------------------------------- | ---- | ------------------------------------------------ | 51| event | (type: [RouteType](#routetype枚举说明), progress: number) => void | 是 | 入场动画的逐帧回调直到入场动画结束，progress从0变化到1。 | 52 53**示例：** 54 55```js 56 pageTransition() { 57 PageTransitionEnter({ duration: 1200, curve: Curve.Linear }) 58 // 转场动画时入场动画 type 为路由类型 ，progress为从0到1逐渐变大 59 .onEnter((type: RouteType, progress: number) => { 60 // 业务逻辑代码 61 }) 62 } 63``` 64 65## PageTransitionExit 66 67PageTransitionExit(value: PageTransitionOptions) 68 69设置当前页面的自定义退场动效。继承自[CommonTransition](#commontransition) 70 71**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 72 73**系统能力：** SystemCapability.ArkUI.ArkUI.Full 74 75**参数：** 76 77| 参数名 | 类型 | 必填 | 说明 | 78| ------ | ------------------------------------------------------- | ---- | -------------------- | 79| value | [PageTransitionOptions](#pagetransitionoptions对象说明) | 是 | 配置退场动效的参数。 | 80 81### onExit 82 83onExit(event: (type: RouteType, progress: number) => void): PageTransitionExitInterface 84 85逐帧回调，直到出场动画结束，progress从0变化到1。 86 87**系统能力：** SystemCapability.ArkUI.ArkUI.Full 88 89**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 90 91**参数：** 92 93| 参数名 | 类型 | 必填 | 说明 | 94| ------ | ----------------------------------------------------------------- | ---- | ------------------------------------------------ | 95| event | (type: [RouteType](#routetype枚举说明), progress: number) => void | 是 | 出场动画的逐帧回调直到入场动画结束，progress从0变化到1。 | 96 97**示例：** 98 99```js 100 pageTransition() { 101 PageTransitionExit({ duration: 1200, curve: Curve.Linear }) 102 // 转场动画时出场动画 type 为路由类型 ，progress为从0到1逐渐变大 103 .onExit((type: RouteType, progress: number) => { 104 // 业务逻辑代码 105 }) 106 } 107``` 108 109## PageTransitionOptions对象说明 110 111**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 112 113**系统能力：** SystemCapability.ArkUI.ArkUI.Full 114 115| 名称 | 类型 | 必填 | 说明 | 116| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 117| type | [RouteType](#routetype枚举说明) | 否 | 页面转场效果生效的路由类型。<br/>默认值：RouteType.None。 | 118| duration | number | 否 | 动画的时长。<br/>单位：毫秒<br/>默认值：1000 | 119| curve | [Curve](ts-appendix-enums.md#curve) \| string \| [ICurve](../js-apis-curve.md#icurve)<sup>10+</sup> | 否 | 动画曲线。string类型的取值支持"ease"、"ease-in"、"ease-out"、"ease-in-out"、"extreme-deceleration"、"fast-out-linear-in"、"fast-out-slow-in"、"friction"、"linear"、"linear-out-slow-in"、"rhythm"、"sharp"、"smooth"。<br/>默认值：Curve.Linear | 120| delay | number | 否 | 动画延迟时长。<br/>单位：毫秒<br/>默认值：0<br/>**说明：** <br/>没有匹配时使用系统默认的页面转场效果(根据设备可能会有差异)，如需禁用系统默认页面转场效果，可以指定duration为0。 | 121 122## CommonTransition 123 124页面转场通用动效。 125 126**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 127 128**系统能力：** SystemCapability.ArkUI.ArkUI.Full 129 130### constructor 131 132constructor() 133 134转场通用动效的构造函数。 135 136**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 137 138**系统能力：** SystemCapability.ArkUI.ArkUI.Full 139 140### slide 141 142slide(value: SlideEffect): T 143 144设置页面转场时的滑入滑出效果。 145 146**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 147 148**系统能力：** SystemCapability.ArkUI.ArkUI.Full 149 150**参数：** 151 152| 参数名 | 类型 | 必填 | 说明 | 153| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 154| value | [SlideEffect](#slideeffect枚举说明) | 是 | 页面转场时的滑入滑出效果。 | 155 156### translate 157 158translate(value: {x? : number \| string; y? : number \| string; z? : number \| string}): T 159 160设置页面转场时的平移效果。 161 162**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 163 164**系统能力：** SystemCapability.ArkUI.ArkUI.Full 165 166**参数：** 167 168| 参数名 | 类型 | 必填 | 说明 | 169| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 170| value | {<br/>x? : number \| string;<br/>y? : number \| string;<br/>z? : number \| string<br/>} | 是 | 设置页面转场时的平移效果，为入场时起点和退场时终点的值，和slide同时设置时默认生效slide。<br/>- x：横向的平移距离。<br/>- y：纵向的平移距离。<br/>- z：竖向的平移距离。 | 171 172### scale 173 174scale(value: { x? : number; y? : number; z? : number; centerX? : number \| string; centerY? : number \| string}): T 175 176设置页面转场时的缩放效果。 177 178**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 179 180**系统能力：** SystemCapability.ArkUI.ArkUI.Full 181 182**参数：** 183 184| 参数名 | 类型 | 必填 | 说明 | 185| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 186| value | {<br/>x? : number;<br/>y? : number;<br/>z? : number;<br/>centerX? : number \| string;<br/>centerY? : number \| string<br/>} | 是 | 设置页面转场时的缩放效果，为入场时起点和退场时终点的值。<br/>- x：横向放大倍数（或缩小比例）。<br/>- y：纵向放大倍数（或缩小比例）。<br/>- z：竖向放大倍数（或缩小比例）。<br/>- centerX、centerY缩放中心点。centerX和centerY默认值是"50%"，即默认以页面的中心点为旋转中心点。<br/>- 中心点为(0, 0)代表页面的左上角。 | 187 188### opacity 189 190opacity(value: number): T 191 192设置入场的起点透明度值或者退场的终点透明度值。 193 194**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 195 196**系统能力：** SystemCapability.ArkUI.ArkUI.Full 197 198**参数：** 199 200| 参数名 | 类型 | 必填 | 说明 | 201| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 202| value | number | 是 | 设置入场的起点透明度值或者退场的终点透明度值。 | 203 204## PageTransitionCallback<sup>14+</sup> 205 206type PageTransitionCallback = (type: RouteType, progress: number) => void 207 208页面转场事件回调。 209 210**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 211 212**系统能力：** SystemCapability.ArkUI.ArkUI.Full 213 214| 参数名 | 类型 | 必填 | 说明 | 215| ------ | ------ | ---- | ---------------- | 216| type | [RouteType](#routetype枚举说明) | 是 | 页面转场类型。 | 217| progress | number | 是 | 转场进度。progress从0变化到1。 | 218 219 ## RouteType枚举说明 220 221**系统能力：** SystemCapability.ArkUI.ArkUI.Full 222 223**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 224 225 226| 名称 | 说明 | 227| ---- | ------------------------------------------------------------ | 228| Pop | 重定向指定页面。从PageB回退到之前的页面PageA。对于PageB，指定RouteType为None或者Pop的PageTransitionExit组件样式生效，对于PageA，指定RouteType为None或者Pop的PageTransitionEnter组件样式生效。 | 229| Push | 跳转到下一页面。PageA跳转到下一个新的界面PageB。对于PageA，指定RouteType为None或者Push的PageTransitionExit组件样式生效，对于PageB，指定RouteType为None或者Push的PageTransitionEnter组件样式生效。 | 230| None | 页面未重定向。如Push和Pop描述中RouteType为None的情形，即页面进场时PageTransitionEnter的转场效果生效；退场时PageTransitionExit的转场效果生效。 | 231 232## SlideEffect枚举说明 233 234**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 235 236**系统能力：** SystemCapability.ArkUI.ArkUI.Full 237 238| 名称 | 说明 | 239| ------------------- | ------------------------------------------------------------ | 240| Left | 设置到入场时表示从左边滑入，出场时表示滑出到左边。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 241| Right | 设置到入场时表示从右边滑入，出场时表示滑出到右边。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 242| Top | 设置到入场时表示从上边滑入，出场时表示滑出到上边。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 243| Bottom | 设置到入场时表示从下边滑入，出场时表示滑出到下边。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 244| START<sup>12+</sup> | 设置LTR入场时表示从左边滑入，出场时表示滑出到左边。RTL入场时表示从右边滑入，出场时表示滑出到右边。<br />**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 245| END<sup>12+</sup> | 设置LTR入场时表示从右边滑入，出场时表示滑出到右边。RTL入场时表示从左边滑入，出场时表示滑出到左边。<br />**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 246 247## 示例 248 249### 示例1（设置退入场动画） 250 251自定义方式1：通过不同的退入场类型配置不同的退场，入场动画。 252 253```ts 254// index.ets 255import { router } from '@kit.ArkUI'; 256 257@Entry 258@Component 259struct Index { 260 @State scale1: number = 1 261 @State opacity1: number = 1 262 263 build() { 264 Column() { 265 Image($r("app.media.transition_image1")).width('100%').height('100%') 266 } 267 .width('100%') 268 .height('100%') 269 .scale({ x: this.scale1 }) 270 .opacity(this.opacity1) 271 .onClick(() => { 272 router.pushUrl({ url: 'pages/Page1' }) 273 }) 274 } 275 276 pageTransition() { 277 PageTransitionEnter({ duration: 1200, curve: Curve.Linear }) 278 .onEnter((type: RouteType, progress: number) => { 279 if (type == RouteType.Push || type == RouteType.Pop) { 280 this.scale1 = progress 281 this.opacity1 = progress 282 } 283 }) 284 PageTransitionExit({ duration: 1200, curve: Curve.Ease }) 285 .onExit((type: RouteType, progress: number) => { 286 if (type == RouteType.Push) { 287 this.scale1 = 1 - progress 288 this.opacity1 = 1 - progress 289 } 290 }) 291 } 292} 293``` 294 295```ts 296// page1.ets 297import { router } from '@kit.ArkUI'; 298 299@Entry 300@Component 301struct Page1 { 302 @State scale2: number = 1 303 @State opacity2: number = 1 304 305 build() { 306 Column() { 307 Image($r("app.media.transition_image2")).width('100%').height('100%') // 图片存放在media文件夹下 308 } 309 .width('100%') 310 .height('100%') 311 .scale({ x: this.scale2 }) 312 .opacity(this.opacity2) 313 .onClick(() => { 314 router.pushUrl({ url: 'pages/Index' }) 315 }) 316 } 317 318 pageTransition() { 319 PageTransitionEnter({ duration: 1200, curve: Curve.Linear }) 320 .onEnter((type: RouteType, progress: number) => { 321 if (type == RouteType.Push || type == RouteType.Pop) { 322 this.scale2 = progress 323 } 324 this.opacity2 = progress 325 }) 326 PageTransitionExit({ duration: 1200, curve: Curve.Ease }) 327 .onExit((type: RouteType, progress: number) => { 328 if (type == RouteType.Pop) { 329 this.scale2 = 1 - progress 330 this.opacity2 = 1 - progress 331 } 332 }) 333 } 334} 335``` 336 337 338 339自定义方式2：配置了当前页面的入场动画为从左侧滑入，退场为平移加透明度变化。 340 341```ts 342// index.ets 343@Entry 344@Component 345struct PageTransitionExample { 346 build() { 347 Column() { 348 Navigator({ target: 'pages/page1', type: NavigationType.Push }) { 349 Image($r('app.media.bg1')).width('100%').height('100%') // 图片存放在media文件夹下 350 } 351 } 352 } 353 354 // 自定义方式2：使用系统提供的多种默认效果(平移、缩放、透明度等) 355 pageTransition() { 356 // 该页面进入动画时长为1200ms，尽量与另一页面的退出动画时长匹配 357 PageTransitionEnter({ duration: 1200 }) 358 .slide(SlideEffect.Left) 359 // 该页面退出动画时长为1000ms，尽量与另一页面的进入动画时长匹配 360 PageTransitionExit({ duration: 1000 }) 361 .translate({ x: 100.0, y: 100.0 }) 362 .opacity(0) 363 } 364} 365``` 366 367```ts 368// page1.ets 369@Entry 370@Component 371struct PageTransitionExample1 { 372 build() { 373 Column() { 374 Navigator({ target: 'pages/index', type: NavigationType.Push }) { 375 Image($r('app.media.bg2')).width('100%').height('100%') // 图片存放在media文件夹下 376 } 377 } 378 } 379 380 // 自定义方式2：使用系统提供的多种默认效果(平移、缩放、透明度等) 381 pageTransition() { 382 // 该页面进入动画时长为1000ms，尽量与另一页面的退出动画时长匹配 383 PageTransitionEnter({ duration: 1000 }) 384 .slide(SlideEffect.Left) 385 // 该页面退出动画时长为1200ms，尽量与另一页面的进入动画时长匹配 386 PageTransitionExit({ duration: 1200 }) 387 .translate({ x: 100.0, y: 100.0 }) 388 .opacity(0) 389 } 390} 391``` 392 393 394 395### 示例2（设置退入场平移效果） 396 397自定义方式1：配置提供的不同退入场平移效果，将系统语言排版模式改为RTL。 398 399```ts 400// index.ets 401import { router } from '@kit.ArkUI' 402 403@Entry 404@Component 405struct PageTransitionExample { 406 @State scale1: number = 1 407 @State opacity1: number = 1 408 409 build() { 410 Column() { 411 Button("页面1").onClick(() => { 412 router.pushUrl({ 413 url: "pages/page1" 414 }) 415 }) 416 .width(200) 417 .height(60) 418 .fontSize(36) 419 Text("START") 420 .fontSize(36) 421 .textAlign(TextAlign.Center) 422 } 423 .scale({ x: this.scale1 }) 424 .opacity(this.opacity1) 425 .height("100%") 426 .width("100%") 427 .justifyContent(FlexAlign.Center) 428 } 429 430 // 自定义方式2：使用系统提供的多种默认效果(平移、缩放、透明度等) 431 pageTransition() { 432 //设置入场动效 433 PageTransitionEnter({ duration: 200 }) 434 .slide(SlideEffect.START) 435 //设置退场动效 436 PageTransitionExit({ delay: 100 }) 437 .slide(SlideEffect.START) //Left 438 } 439} 440``` 441 442```ts 443// page1.ets 444import { router } from '@kit.ArkUI' 445 446@Entry 447@Component 448struct PageTransitionExample { 449 @State scale1: number = 1 450 @State opacity1: number = 1 451 452 build() { 453 Column() { 454 Button("页面2").onClick(() => { 455 router.pushUrl({ 456 url: "pages/Index" 457 }) 458 }) 459 .width(200) 460 .height(60) 461 .fontSize(36) 462 Text("END") 463 .fontSize(36) 464 .textAlign(TextAlign.Center) 465 } 466 .scale({ x: this.scale1 }) 467 .opacity(this.opacity1) 468 .height("100%") 469 .width("100%") 470 .justifyContent(FlexAlign.Center) 471 } 472 473 // 自定义方式2：使用系统提供的多种默认效果(平移、缩放、透明度等) 474 pageTransition() { 475 PageTransitionEnter({ duration: 200 }) 476 .slide(SlideEffect.END) //Right 477 PageTransitionExit({ delay: 100 }) 478 .slide(SlideEffect.END) //Right 479 } 480} 481 482``` 483 484 485 486自定义方式2：使用系统默认的退入场效果，将系统语言排版模式改为RTL。 487 488```ts 489// index.ets 490import { router } from '@kit.ArkUI' 491 492@Entry 493@Component 494struct PageTransitionExample { 495 @State scale1: number = 1 496 @State opacity1: number = 1 497 498 build() { 499 Column() { 500 Button("页面1").onClick(() => { 501 router.pushUrl({ 502 url: "pages/page1" 503 }) 504 }) 505 .width(200) 506 .height(60) 507 .fontSize(36) 508 } 509 .scale({ x: this.scale1 }) 510 .opacity(this.opacity1) 511 .height("100%") 512 .width("100%") 513 .justifyContent(FlexAlign.Center) 514 } 515} 516``` 517 518```ts 519// page1.ets 520import { router } from '@kit.ArkUI' 521 522@Entry 523@Component 524struct PageTransitionExample { 525 @State scale1: number = 1 526 @State opacity1: number = 1 527 528 build() { 529 Column() { 530 Button("页面2").onClick(() => { 531 router.pushUrl({ 532 url: "pages/Index" 533 }) 534 }) 535 .width(200) 536 .height(60) 537 .fontSize(36) 538 } 539 .scale({ x: this.scale1 }) 540 .opacity(this.opacity1) 541 .height("100%") 542 .width("100%") 543 .justifyContent(FlexAlign.Center) 544 } 545} 546``` 547 548 549
