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 this.opacity2 = progress 324 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 }.scale({ x: this.scale1 }).opacity(this.opacity1).height("100%").width("100%").justifyContent(FlexAlign.Center) 423 } 424 425 // 自定义方式2：使用系统提供的多种默认效果(平移、缩放、透明度等) 426 pageTransition() { 427 //设置入场动效 428 PageTransitionEnter({ duration: 200 }) 429 .slide(SlideEffect.START) 430 //设置退场动效 431 PageTransitionExit({ delay: 100 }) 432 .slide(SlideEffect.START) //Left 433 } 434} 435``` 436 437```ts 438// page1.ets 439import { router } from '@kit.ArkUI' 440 441@Entry 442@Component 443struct PageTransitionExample { 444 @State scale1: number = 1 445 @State opacity1: number = 1 446 447 build() { 448 Column() { 449 Button("页面2").onClick(()=>{ 450 router.pushUrl({ 451 url:"pages/Index" 452 }) 453 }) 454 .width(200) 455 .height(60) 456 .fontSize(36) 457 Text("END") 458 .fontSize(36) 459 .textAlign(TextAlign.Center) 460 }.scale({ x: this.scale1 }).opacity(this.opacity1).height("100%").width("100%").justifyContent(FlexAlign.Center) 461 } 462 463 // 自定义方式2：使用系统提供的多种默认效果(平移、缩放、透明度等) 464 pageTransition() { 465 PageTransitionEnter({ duration: 200 }) 466 .slide(SlideEffect.END) //Right 467 PageTransitionExit({ delay:100 }) 468 .slide(SlideEffect.END) //Right 469 } 470} 471 472``` 473 474 475 476自定义方式2：使用系统默认的退入场效果，将系统语言排版模式改为RTL。 477 478```ts 479// index.ets 480import { router } from '@kit.ArkUI' 481 482@Entry 483@Component 484struct PageTransitionExample { 485 @State scale1: number = 1 486 @State opacity1: number = 1 487 488 build() { 489 Column() { 490 Button("页面1").onClick(()=>{ 491 router.pushUrl({ 492 url:"pages/page1" 493 }) 494 }) 495 .width(200) 496 .height(60) 497 .fontSize(36) 498 }.scale({ x: this.scale1 }).opacity(this.opacity1).height("100%").width("100%").justifyContent(FlexAlign.Center) 499 } 500} 501``` 502 503```ts 504// page1.ets 505import { router } from '@kit.ArkUI' 506 507@Entry 508@Component 509struct PageTransitionExample { 510 @State scale1: number = 1 511 @State opacity1: number = 1 512 513 build() { 514 Column() { 515 Button("页面2").onClick(()=>{ 516 router.pushUrl({ 517 url:"pages/Index" 518 }) 519 }) 520 .width(200) 521 .height(60) 522 .fontSize(36) 523 }.scale({ x: this.scale1 }).opacity(this.opacity1).height("100%").width("100%").justifyContent(FlexAlign.Center) 524 } 525} 526``` 527 528 529
