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: PageTransitionCallback): 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 | [PageTransitionCallback](#pagetransitioncallback14) | 是 | 入场动画的逐帧回调直到入场动画结束，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: PageTransitionCallback): 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 | [PageTransitionCallback](#pagetransitioncallback14) | 是 | 出场动画的逐帧回调直到出场动画结束，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<br/>取值范围：[0, +∞) | 119| curve | [Curve](ts-appendix-enums.md#curve) \| string \| [ICurve](../js-apis-curve.md#icurve)<sup>10+</sup> | 否 | 动画曲线。<br/>推荐以Curve或ICurve形式指定。<br/>当类型为string时，为动画插值曲线，取值参考[AnimateParam](./ts-explicit-animation.md#animateparam对象说明)的curve参数。<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: TranslateOptions): T 159 160设置页面转场时的平移效果。 161 162**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 163 164**系统能力：** SystemCapability.ArkUI.ArkUI.Full 165 166**参数：** 167 168| 参数名 | 类型 | 必填 | 说明 | 169| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 170| value | [TranslateOptions](ts-universal-attributes-transformation.md#translateoptions对象说明) | 是 | 设置页面转场时的平移效果，为入场时起点和退场时终点的值，和slide同时设置时默认生效slide。<br/>- x：横向的平移距离。<br/>- y：纵向的平移距离。<br/>- z：竖向的平移距离。 | 171 172### scale 173 174scale(value: ScaleOptions): T 175 176设置页面转场时的缩放效果。 177 178**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 179 180**系统能力：** SystemCapability.ArkUI.ArkUI.Full 181 182**参数：** 183 184| 参数名 | 类型 | 必填 | 说明 | 185| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 186| value | [ScaleOptions](ts-universal-attributes-transformation.md#scaleoptions对象说明) | 是 | 设置页面转场时的缩放效果，为入场时起点和退场时终点的值。<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 | 是 | 设置入场的起点透明度值或者退场的终点透明度值。<br/>取值范围：[0, 1] | 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 255@Entry 256@Component 257struct Index { 258 @State scale1: number = 1 259 @State opacity1: number = 1 260 261 build() { 262 Column() { 263 Image($r("app.media.transition_image1")).width('100%').height('100%') 264 } 265 .width('100%') 266 .height('100%') 267 .scale({ x: this.scale1 }) 268 .opacity(this.opacity1) 269 .onClick(() => { 270 this.getUIContext().getRouter().pushUrl({ url: 'pages/Page1' }) 271 }) 272 } 273 274 pageTransition() { 275 PageTransitionEnter({ duration: 1200, curve: Curve.Linear }) 276 .onEnter((type: RouteType, progress: number) => { 277 if (type == RouteType.Push || type == RouteType.Pop) { 278 this.scale1 = progress 279 this.opacity1 = progress 280 } 281 }) 282 PageTransitionExit({ duration: 1200, curve: Curve.Ease }) 283 .onExit((type: RouteType, progress: number) => { 284 if (type == RouteType.Push) { 285 this.scale1 = 1 - progress 286 this.opacity1 = 1 - progress 287 } 288 }) 289 } 290} 291``` 292 293```ts 294// Page1.ets 295@Entry 296@Component 297struct Page1 { 298 @State scale2: number = 1 299 @State opacity2: number = 1 300 301 build() { 302 Column() { 303 Image($r("app.media.transition_image2")).width('100%').height('100%') // 图片存放在media文件夹下 304 } 305 .width('100%') 306 .height('100%') 307 .scale({ x: this.scale2 }) 308 .opacity(this.opacity2) 309 .onClick(() => { 310 this.getUIContext().getRouter().pushUrl({ url: 'pages/Index' }) 311 }) 312 } 313 314 pageTransition() { 315 PageTransitionEnter({ duration: 1200, curve: Curve.Linear }) 316 .onEnter((type: RouteType, progress: number) => { 317 if (type == RouteType.Push || type == RouteType.Pop) { 318 this.scale2 = progress 319 } 320 this.opacity2 = progress 321 }) 322 PageTransitionExit({ duration: 1200, curve: Curve.Ease }) 323 .onExit((type: RouteType, progress: number) => { 324 if (type == RouteType.Pop) { 325 this.scale2 = 1 - progress 326 this.opacity2 = 1 - progress 327 } 328 }) 329 } 330} 331``` 332 333 334 335自定义方式2：配置了当前页面的入场动画为从左侧滑入，退场为平移加透明度变化。 336 337```ts 338// Index.ets 339@Entry 340@Component 341struct Index { 342 build() { 343 Column() { 344 Image($r('app.media.bg1')).width('100%').height('100%') // 图片存放在media文件夹下 345 } 346 .onClick(() => { 347 this.getUIContext().getRouter().pushUrl({ url: 'pages/Page1' }) 348 }) 349 } 350 351 // 自定义方式2：使用系统提供的多种默认效果(平移、缩放、透明度等) 352 pageTransition() { 353 // 该页面进入动画时长为1200ms，尽量与另一页面的退出动画时长匹配 354 PageTransitionEnter({ duration: 1200 }) 355 .slide(SlideEffect.Left) 356 // 该页面退出动画时长为1000ms，尽量与另一页面的进入动画时长匹配 357 PageTransitionExit({ duration: 1000 }) 358 .translate({ x: 100.0, y: 100.0 }) 359 .opacity(0) 360 } 361} 362``` 363 364```ts 365// Page1.ets 366@Entry 367@Component 368struct Page1 { 369 build() { 370 Column() { 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
