Skyline Route

Skyline 自定义路由与页面转场

适用场景

• 实现自定义页面转场动画（半屏、缩放、渐显等）
• 使用预设路由快速实现常见转场效果
• 配置页面返回手势（横向/纵向/多方向）
• 实现卡片展开到详情页的容器转场动画
• 通过 Router API 管理自定义路由

核心概念

路由能力层级

动画控制器

文档索引

根据需求快速定位（路径相对于 references/）：

强制规则

MUST（必须遵守）

1. 自定义路由仅在连续 Skyline 页面间生效：WebView 页面不支持自定义路由

   js

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

2. 动画处理函数必须声明 'worklet' 指令：

   js

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

3. 手势接管必须成对调用 startUserGesture / stopUserGesture：

   js

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

4. 确认返回时必须调用 didPop：引擎无法自动判断开发者是否要退出页面

   js

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

NEVER（禁止行为）

1. NEVER 在手势处理中忘记调用 startUserGesture 就直接修改 primaryAnimation.value
2. NEVER 假设自定义路由在 WebView 页面生效（低版本基础库会降级）
3. NEVER 在非 worklet 函数中访问 primaryAnimation.value

Quick Reference

预设路由速查

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

API 速查

自定义路由最小示例

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

场景决策表

相关技能

References 目录结构

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