在微信 Skyline 中实现自定义路由、预设路由…

适用于微信小程序 Skyline 页面间自定义路由动画、预设路由、返回手势和容器转场的实现与排错。

适用场景

解决思路

1. 先按需求定位文档（路径相对于 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。
2. 按能力层级选择实现方式：只需常见转场用预设路由（一行代码使用 7 种内置效果）；需要高度定制化转场用自定义路由（通过 routeBuilder 完全控制动画）；卡片展开到详情页用容器转场（<open-container> 元素级过渡）。
3. 使用动画控制器：primaryAnimation 控制页面进入/退出动画进度（0→1 进入，1→0 退出）；secondaryAnimation 控制下一页进入时当前页动画进度（与下一页 primaryAnimation 同步）；userGestureInProgress 判断当前路由进度是否由手势控制；startUserGesture/stopUserGesture 接管/释放路由控制；didPop 确认返回上一页。
4. 自定义路由必须只用在连续 Skyline 页面之间；A 页(Skyline) → B 页(Skyline) 时生效；A 页(WebView) → B 页(Skyline) 时会降级为默认路由。
5. 确保自定义路由中的动画处理函数声明 'worklet' 指令，否则无法在 UI 线程执行；示例：const handlePrimaryAnimation = () => { 'worklet'; return { transform: `translateX(${...}px)` } }。
6. 手势接管时必须成对调用 startUserGesture / stopUserGesture；在 handleDragStart 中调用 startUserGesture，在 handleDragEnd 的动画完成回调中调用 stopUserGesture。
7. 确认返回时必须在动画完成后调用 didPop；引擎无法自动判断是否退出页面；示例：primaryAnimation.value = timing(0.0, { duration }, () => { 'worklet'; didPop(); stopUserGesture(); })。
8. 禁止在手势处理中未调用 startUserGesture 就直接修改 primaryAnimation.value。
9. 禁止假设自定义路由在 WebView 页面生效；低版本基础库会降级。
10. 禁止在非 worklet 函数中访问 primaryAnimation.value。
11. 使用预设路由时调用 wx.navigateTo，传入 routeType 和 routeOptions；例如 wx.navigateTo({ url: 'xxx', routeType: 'wx://bottom-sheet', routeOptions: { height: 60, round: true } })。
12. 按预设路由 routeType 选择效果：wx://bottom-sheet 底部弹出半屏；wx://upwards 自底向上全屏；wx://zoom 缩放进入；wx://cupertino-modal iOS 风格模态；wx://cupertino-modal-inside iOS 模态内嵌；wx://modal-navigation 模态导航；wx://modal 模态弹窗；最低基础库均为 3.1.0。
13. 使用 Router 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）。
14. 实现自定义路由最小示例：用 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' })。
15. 按场景决策：底部弹出半屏用预设路由 wx://bottom-sheet；iOS 风格模态用预设路由 wx://cupertino-modal；自定义半屏 + 手势用自定义路由 + handlePrimaryAnimation；卡片展开到详情页用 <open-container> 容器转场；页面渐显效果用自定义路由 + opacity 动画；需要纵向返回手势用 popGestureDirection: 'vertical'。
16. 相关技能参考：动画开发用 skyline-worklet（Worklet 动画系统 timing/spring/Easing）；手势处理用 skyline-components（gesture-handler 手势组件）；共享元素用 skyline-components（share-element 页面间动画）；配置详解用 skyline-config（app.json/page.json 配置）；概览迁移用 skyline-overview（Skyline 概览与迁移指南）。
17. References 目录结构：references/api/navigate-to.md、references/api/route-events.md、references/api/router-api.md、references/custom-route/custom-route-guide.md、references/custom-route/route-patterns.md、references/open-container/open-container.md、references/pop-gesture/pop-gesture.md、references/preset-route/preset-route.md。

适用边界 · 注意事项

• 页面为 WebView 或跳转不是连续 Skyline 页面时，自定义路由不生效，会降级为默认路由。
• 基础库版本低于对应 API/预设路由最低版本（如预设路由需 3.1.0，addRouteBuilder 需 2.29.2，withOpenContainer 需 3.12.2）时，不要依赖该能力。
• 无法在 UI 线程/worklet 中运行动画函数，或无法成对调用 startUserGesture/stopUserGesture、在动画完成时调用 didPop 时，不要使用手势接管路由。