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