Skyline Custom Route and Page Transition

Applicable Scenarios

• Implement custom page transition animations (half-screen, scaling, fade-in, etc.)
• Quickly implement common transition effects using preset routes
• Configure page back gestures (horizontal/vertical/multi-directional)
• Implement container transition animation for card expansion to detail page
• Manage custom routes through Router API

Core Concepts

Route Capability Levels

<open-container>

Animation Controller

Document Index

references/

custom-route/custom-route-guide.md

custom-route/route-patterns.md

preset-route/preset-route.md

pop-gesture/pop-gesture.md

open-container/open-container.md

api/router-api.md

api/navigate-to.md

api/route-events.md

Mandatory Rules

MUST (Must Comply)

1. Custom routes only take effect between consecutive Skyline pages: WebView pages do not support custom routes
   js

   // ✅ Page A (Skyline) → Page B (Skyline): Custom route takes effect
   // ❌ Page A (WebView) → Page B (Skyline): Degrade to default route

2. The animation processing function must declare the 'worklet' directive:
   js

   // ✅ Correct
   const handlePrimaryAnimation = () => {
     'worklet'
     return { transform: `translateX(${...}px)` }
   }
   
   // ❌ Incorrect: Missing worklet directive, cannot execute in UI thread
   const handlePrimaryAnimation = () => {
     return { transform: `translateX(${...}px)` }
   }

3. Gesture takeover must call startUserGesture / stopUserGesture in pairs:
   js

   // ✅ Correct
   handleDragStart() {
     'worklet'
     this.customRouteContext.startUserGesture()
   }
   handleDragEnd() {
     'worklet'
     // ... In animation completion callback:
     stopUserGesture()
   }

4. must call didPop when confirming return: The engine cannot automatically determine whether the developer wants to exit the page
   js

   // ✅ Correct: Call didPop after animation is completed
   primaryAnimation.value = timing(0.0, { duration }, () => {
     'worklet'
     didPop()
     stopUserGesture()
   })

5. The navigator component can only nest text nodes under Skyline:
   html

   <!-- ✅ Correct -->
   <navigator url="/page">Click to jump</navigator>
   
   <!-- ❌ Incorrect: Cannot nest ordinary nodes such as view -->
   <navigator url="/page"><view>Jump</view></navigator>

NEVER (Prohibited Behaviors)

1. NEVER directly modify

   primaryAnimation.value

   in gesture processing without calling

   startUserGesture

2. NEVER assume that custom routes take effect on WebView pages (lower version basic libraries will degrade)
3. NEVER access

   primaryAnimation.value

   in non-worklet functions

Quick Reference

Preset Route Quick Check

wx://bottom-sheet

wx://upwards

wx://zoom

wx://cupertino-modal

wx://cupertino-modal-inside

wx://modal-navigation

wx://modal

// Use preset route
wx.navigateTo({
  url: 'xxx',
  routeType: 'wx://bottom-sheet',
  routeOptions: { height: 60, round: true }
})

API Quick Check

wx.router.addRouteBuilder(type, builder)

wx.router.removeRouteBuilder(type)

wx.router.getRouteContext(this)

wx.navigateTo({ routeType })

wx.navigateTo({ routeConfig })

wx.navigateTo({ routeOptions })

wx.navigateTo({ withOpenContainer })

wx.onBeforeAppRoute(fn)

wx.onAppRoute(fn)

Minimal Custom Route Example

// Register: Slide in from right
wx.router.addRouteBuilder('slide', ({ primaryAnimation }) => {
  const { windowWidth } = wx.getWindowInfo()
  const handlePrimaryAnimation = () => {
    'worklet'
    const transX = windowWidth * (1 - primaryAnimation.value)
    return { transform: `translateX(${transX}px)` }
  }
  return { handlePrimaryAnimation }
})

// Jump
wx.navigateTo({ url: 'pageB', routeType: 'slide' })

Scenario Decision Table

wx://bottom-sheet

wx://cupertino-modal

<open-container>

popGestureDirection: 'vertical'

Related Skills

skyline-worklet

skyline-components

skyline-components

skyline-config

skyline-overview

References Directory Structure

references/
├── api/
│   ├── navigate-to.md
│   ├── route-events.md
│   └── router-api.md
├── custom-route/
│   ├── custom-route-guide.md
│   └── route-patterns.md
├── open-container/
│   └── open-container.md
├── pop-gesture/
│   └── pop-gesture.md
└── preset-route/
    └── preset-route.md