skyline-route

Skyline Custom Routing and Page Transitions

Use Cases

• Implement custom page transition animations (half-screen, scale, fade-in, etc.)
• Use preset routes to quickly implement common transition effects
• Configure page back gestures (horizontal/vertical/multi-direction)
• Implement container transition animations for expanding a card to a detail page
• Manage custom routes via the Router API

Core Concepts

Routing Capability Levels

Level	Capability	Use Cases
Preset Routes	Use 7 built-in effects with one line of code	Quickly implement common transitions
Custom Routes	Fully control animations via routeBuilder	Highly customized transitions
Container Transitions	<open-container> Element-level transitions	Expand a card to a detail page

Animation Controller

Property	Description
primaryAnimation	Page enter/exit animation progress (0→1 entering, 1→0 exiting)
secondaryAnimation	Current page animation progress when the next page enters (synchronized with the next page's primaryAnimation)
userGestureInProgress	Whether the current route progress is controlled by gestures
startUserGesture / stopUserGesture	Gesture takes over/releases route control
didPop	Confirm returning to the previous page

Documentation Index

Quickly locate based on your needs (paths are relative to references/）：

I want to...	View documentation
Understand the principles and interfaces of custom routing	custom-route/custom-route-guide.md
View half-screen/gesture back code patterns	custom-route/route-patterns.md
Quickly use preset routes	preset-route/preset-route.md
Configure page back gestures	pop-gesture/pop-gesture.md
Implement card expansion transitions	open-container/open-container.md
View the Router API	api/router-api.md
Understand navigateTo route parameters	api/navigate-to.md
Listen for route events	api/route-events.md

Mandatory Rules

MUST (must comply)

1. Custom routing only takes effect between consecutive Skyline pages: WebView pages do not support custom routing

   // ✅ A 页(Skyline) → B 页(Skyline)：自定义路由生效
   // ❌ A 页(WebView) → B 页(Skyline)：降级为默认路由
   

2. Animation handler functions must declare the 'worklet' directive：

   // ✅ 正确
   const handlePrimaryAnimation = () => {
     'worklet'
     return { transform: `translateX(${...}px)` }
   }
   
   // ❌ 错误：缺少 worklet 指令，无法在 UI 线程执行
   const handlePrimaryAnimation = () => {
     return { transform: `translateX(${...}px)` }
   }
   

3. Gesture takeover must call startUserGesture / stopUserGesture in pairs：

   // ✅ 正确
   handleDragStart() {
     'worklet'
     this.customRouteContext.startUserGesture()
   }
   handleDragEnd() {
     'worklet'
     // ... 动画完成回调中：
     stopUserGesture()
   }
   

4. didPop must be called when confirming back: The engine cannot automatically determine whether the developer wants to exit the page

   // ✅ 正确：动画完成后调用 didPop
   primaryAnimation.value = timing(0.0, { duration }, () => {
     'worklet'
     didPop()
     stopUserGesture()
   })
   

NEVER (prohibited behaviors)

1. NEVER In gesture handling, forget to call startUserGesture and directly modify primaryAnimation.value
2. NEVER Assume custom routing takes effect on WebView pages (it will fall back on lower base library versions)
3. NEVER Access primaryAnimation.value

Quick Reference

Preset Routes Quick Reference

routeType	Effect	Minimum Base Library
wx://bottom-sheet	Bottom half-screen popup	3.1.0
wx://upwards	Bottom-to-top full screen	3.1.0
wx://zoom	Scale in	3.1.0
wx://cupertino-modal	iOS-style modal	3.1.0
wx://cupertino-modal-inside	iOS modal embedded	3.1.0
wx://modal-navigation	Modal navigation	3.1.0
wx://modal	Modal popup	3.1.0

// 使用预设路由
wx.navigateTo({
  url: 'xxx',
  routeType: 'wx://bottom-sheet',
  routeOptions: { height: 60, round: true }
})

API Quick Reference

API	Description	Minimum Base Library
wx.router.addRouteBuilder(type, builder)	Register custom route	2.29.2
wx.router.removeRouteBuilder(type)	Remove custom route	2.29.2
wx.router.getRouteContext(this)	Get route context	2.29.2
wx.navigateTo({ routeType })	Navigate by specified route type	2.29.2
wx.navigateTo({ routeConfig })	Override route configuration	3.4.0
wx.navigateTo({ routeOptions })	Pass route parameters	3.4.0
wx.navigateTo({ withOpenContainer })	Container transition navigation	3.12.2
wx.onBeforeAppRoute(fn)	Listen before route execution	3.5.5
wx.onAppRoute(fn)	Listen after route execution	3.5.5

Minimal custom route example

// 注册：从右滑入
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 }
})

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

Scenario decision table

Scenario	Recommended solution
Bottom sheet half-screen	Preset route wx://bottom-sheet
iOS-style modal	Preset route wx://cupertino-modal
Custom half-screen + gestures	Custom route + handlePrimaryAnimation
Card expand to detail page	<open-container> Container transition
Page fade-in effect	Custom route + opacity animation
Requires vertical back gesture	popGestureDirection: 'vertical'

Related skills

Scenario	Recommended skill	Description
Animation development	skyline-worklet	Worklet animation system (timing/spring/Easing)
Gesture handling	skyline-components	gesture-handler gesture components
Shared elements	skyline-components	share-element inter-page animation
Configuration details	skyline-config	app.json/page.json configuration
Overview migration	skyline-overview	Skyline overview and migration guide

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