skyline-route

用途

本技能面向微信小程序 Skyline 渲染模式，用于实现自定义路由与页面转场动画。适用场景包括：实现自定义页面转场动画（半屏、缩放、渐显等）、使用预设路由快速实现常见转场效果、配置页面返回手势（横向/纵向/多方向）、实现卡片展开到详情页的容器转场动画，以及通过 Router API 管理自定义路由。

主要能力

路由能力分为三个层级：

预设路由：一行代码使用 7 种内置效果，适合快速实现常见转场。
自定义路由：通过 routeBuilder 完全控制动画，适合高度定制化转场。
容器转场：使用 <open-container> 元素级过渡，适合卡片展开到详情页。

动画控制器提供以下属性与方法：

primaryAnimation：页面进入/退出动画进度（0→1 进入，1→0 退出）。
secondaryAnimation：下一页进入时当前页动画进度（与下一页 primaryAnimation 同步）。
userGestureInProgress：当前路由进度是否由手势控制。
startUserGesture / stopUserGesture：手势接管/释放路由控制。
didPop：确认返回上一页。

预设路由速查（routeType，最低基础库均为 3.1.0）：

wx://bottom-sheet：底部弹出半屏
wx://upwards：自底向上全屏
wx://zoom：缩放进入
wx://cupertino-modal：iOS 风格模态
wx://cupertino-modal-inside：iOS 模态内嵌
wx://modal-navigation：模态导航
wx://modal：模态弹窗

API 速查：

wx.router.addRouteBuilder(type, builder)：注册自定义路由，最低基础库 2.29.2
wx.router.removeRouteBuilder(type)：移除自定义路由，最低基础库 2.29.2
wx.router.getRouteContext(this)：获取路由上下文，最低基础库 2.29.2
wx.navigateTo({ routeType })：指定路由类型跳转，最低基础库 2.29.2
wx.navigateTo({ routeConfig })：覆盖路由配置，最低基础库 3.4.0
wx.navigateTo({ routeOptions })：传入路由参数，最低基础库 3.4.0
wx.navigateTo({ withOpenContainer })：容器转场跳转，最低基础库 3.12.2
wx.onBeforeAppRoute(fn)：路由执行前监听，最低基础库 3.5.5
wx.onAppRoute(fn)：路由执行后监听，最低基础库 3.5.5

使用方式

预设路由示例：

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

自定义路由最小示例（从右滑入）：

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

了解自定义路由原理和接口：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
查看 Router API：api/router-api.md
了解 navigateTo 路由参数：api/navigate-to.md
监听路由事件：api/route-events.md

适用场景决策

底部弹出半屏：预设路由 wx://bottom-sheet
iOS 风格模态：预设路由 wx://cupertino-modal
自定义半屏 + 手势：自定义路由 + handlePrimaryAnimation
卡片展开到详情页：<open-container> 容器转场
页面渐显效果：自定义路由 + opacity 动画
需要纵向返回手势：popGestureDirection: 'vertical'

限制与强制规则

MUST（必须遵守）：

自定义路由仅在连续 Skyline 页面间生效，WebView 页面不支持自定义路由。A 页(Skyline) → B 页(Skyline) 自定义路由生效；A 页(WebView) → B 页(Skyline) 降级为默认路由。
动画处理函数必须声明 'worklet' 指令，否则无法在 UI 线程执行。
手势接管必须成对调用 startUserGesture / stopUserGesture。
确认返回时必须调用 didPop，引擎无法自动判断开发者是否要退出页面。

NEVER（禁止行为）：

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

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

技能介绍

用途