# 自定义路由

小程序采用多 WebView 架构，页面间跳转形式十分单一，仅能从右到左进行动画。而原生 App 的动画形式则多种多样，如从底部弹起，页面下沉，半屏等。

Skyline 渲染引擎下，页面有两种渲染模式: WebView 和 Skyline，它们通过页面配置中的 renderer 字段进行区分。在连续的 Skyline 页面间跳转时，可实现自定义路由效果。

# 效果展示

下方为半屏页面效果，点击可查看更多 Skyline 示例。

扫码打开小程序示例，交互动画 - 基础组件 - 自定义路由即可体验。

# 使用方法

建议先阅读完 worklet 动画和手势系统两个章节，它们是自定义路由的基础内容。

# 接口定义

自定义路由相关的接口

页面跳转 wx.navigateTo
路由上下文对象 wx.router.getRouteContext
注册自定义路由 wx.router.addRouteBuilder

type AddRouteBuilder = (routeType: string, routeBuilder: CustomRouteBuilder) => void type CustomRouteBuilder = (routeContext: CustomRouteContext, routeOptions: Record<string, any>) => CustomRouteConfig interface SharedValue<T> { value: T; } interface CustomRouteContext { // 动画控制器，影响推入页面的进入和退出过渡效果 primaryAnimation: SharedValue<number> // 动画控制器状态 primaryAnimationStatus: SharedValue<number> // 动画控制器，影响栈顶页面的推出过渡效果 secondaryAnimation: SharedValue<number> // 动画控制器状态 secondaryAnimationStatus: SharedValue<number> // 当前路由进度由手势控制 userGestureInProgress: SharedValue<number> // 手势开始控制路由 startUserGesture: () => void // 手势不再控制路由 stopUserGesture: () => void // 返回上一级，效果同 wx.navigateBack didPop: () => void } interface CustomRouteConfig { // 下一个页面推入后，不显示前一个页面 opaque?: boolean; // 是否保持前一个页面状态 maintainState?: boolean; // 页面推入动画时长，单位 ms transitionDuration?: number; // 页面推出动画时长，单位 ms reverseTransitionDuration?: number; // 遮罩层背景色，支持 rgba() 和 #RRGGBBAA 写法 barrierColor?: string; // 点击遮罩层返回上一页 barrierDismissible?: boolean; // 无障碍语义 barrierLabel?: string; // 是否与下一个页面联动，决定当前页 secondaryAnimation 是否生效 canTransitionTo?: boolean; // 是否与前一个页面联动，决定前一个页 secondaryAnimation 是否生效 canTransitionFrom?: boolean; // 处理当前页的进入/退出动画，返回 StyleObject handlePrimaryAnimation?: RouteAnimationHandler; // 处理当前页的压入/压出动画，返回 StyleObject handleSecondaryAnimation?: RouteAnimationHandler; // 处理上一级页面的压入/压出动画，返回 StyleObject 基础库 <3.0.0> 起支持 handlePreviousPageAnimation?: RouteAnimationHandler; // 页面进入时是否采用 snapshot 模式优化动画性能 基础库 <3.2.0> 起支持 allowEnterRouteSnapshotting?: boolean // 页面退出时是否采用 snapshot 模式优化动画性能 基础库 <3.2.0> 起支持 allowExitRouteSnapshotting?: boolean // 右滑返回时，可拖动范围是否撑满屏幕，基础库 <3.2.0> 起支持，常用于半屏弹窗 fullscreenDrag?: boolean // 返回手势方向 基础库 <3.4.0> 起支持 popGestureDirection?: 'horizontal' | 'vertical' | 'multi' } type RouteAnimationHandler = () => { [key: string] : any}

# 默认路由配置

const defaultCustomRouteConfig = { opaque: true, maintainState: true, transitionDuration: 300, reverseTransitionDuration: 300, barrierColor: '', barrierDismissible: false, barrierLabel: '', canTransitionTo: true, canTransitionFrom: true, allowEnterRouteSnapshotting: false, allowExitRouteSnapshotting: false, fullscreenDrag: false, popGestureDirection: 'horizontal' }

# 示例模板

以下是注册自定义路由的一份示例模板（未添加手势处理部分），完整实现半屏路由效果见示例代码。

const customRouteBuiler = (routeContext: CustomRouteContext) : CustomRouteConfig => { const { primaryAnimation, secondaryAnimation, userGestureInProgress } = routeContext const handlePrimaryAnimation: RouteAnimationHandler = () => { 'worklet' let t = primaryAnimation.value if (!userGestureInProgress.value) { // select another curve, t = xxx } // StyleObject return {} } const handleSecondaryAnimation: RouteAnimationHandler = () => { 'worklet' let t = secondaryAnimation.value if (!userGestureInProgress.value) { // select another curve, t = xxx } // StyleObject return {} } return { opaque: true, handlePrimaryAnimation, handleSecondaryAnimation } } // 在页面跳转前定义好 routeBuilder wx.router.addRouteBuilder('customRoute', customRouteBuiler) // 跳转新页面时，指定对应的 routeType wx.navigateTo({ url: 'xxxx', routeType: 'customRoute' })

# 工作原理

以半屏效果为例，路由前后页面记为 A 页、B 页，一个路由的生命周期中，会经历如下阶段：

push 阶段：调用 wx.navigateTo，B 页自底向上弹出，A 页下沉收缩
手势拖动：在 B 页上下滑动时，路由动画随之变化
pop 阶段：调用 wx.navigateBack，B 页向下关闭，A 恢复原样

细分到每个页面，在上述阶段会有以下动画方式

进入/退出动画
压入/压出动画
手势拖动

在 push 阶段，B 页进行的是进入动画，A 页进行的是压入动画；
在 pop 阶段，B 页进行的是退出动画，A 页进行的是压出动画；

可以看到在路由过程中，前后两个页面动画进行了联动。在自定义路由模式下，我们可以对动画各个阶段的时长、曲线、效果以及是否联动进行自定义，以实现灵活多变的页面专场效果。

# 路由控制器

当打开新页面时，框架会为其创建两个 SharedValue 类型的动画控制器 primaryAnimation 和 secondaryAnimation，分别控制进入/退出动画和压入/压出动画。

页面的进入和退出可指定不同的时长，但进度变化始终在 0～1 之间。仍以半屏效果为例，路由前后页面记为 A 页、B 页。

# `push` 阶段

B 页对应的 primaryAnimation 从 0 -> 1 变化，做进入动画
A 页对应的 secondaryAnimation 从 0 -> 1 变化，做压入动画

# `pop` 阶段

B 页对应的 primaryAnimation 从 1 -> 0 变化，做退出动画
A 页对应的 secondaryAnimation 从 1 -> 0 变化，做压出动画

其中，A 页 secondaryAnimation 的值始终与 B 页 primaryAnimation 的值同步变化。

通常页面的进入和退出可能采用不同的动画曲线，可通过对应的状态变量 primaryAnimationStatus 和 secondaryAnimationStatus 来区分当前处于哪一阶段，ts 定义如下

enum AnimationStatus { // 动画停在起点 dismissed = 0, // 动画从起点向终点进行 forward = 1, // 动画从终点向起点进行 reverse = 2, // 动画停在终点 completed = 3, }

以 primaryAnimationStatus 为例，页面进入和退出过程中变化情况如下

push 阶段：dismissed -> forward -> completed
pop 阶段：completed -> reverse -> dismissed

# 路由手势

在页面推入后，除了调用 wx.navigateBack 接口返回上一级外，还可以通过手势来处理，例如 iOS 上常见的右滑返回。自定义路由模式下，开发者可根据不同的页面转场效果，来选取所需的退出方式，如半屏效果可采用下滑返回。关于手势监听的内容，可参考手势系统一章，路由手势仅是在其基础上，补充了几个路由相关的接口。

startUserGesture 和 stopUserGesture 两个函数总是成对调用的，startUserGesture 调用后 userGestureInProgress 的值会加 1。

当开发者自行修改 primaryAnimation 的值来控制路由进度的时候，就需要调用这两个接口。由于手势拖动过程中通常采用不同的动画曲线，可通过 userGestureInProgress 值进行判断。

当手势处理后确定需要返回上一级页面时，调用 didPop 接口，作用等同 wx.navigateBack。

# 路由联动

路由动画过程中，默认前后两个页面是一起联动的，可通过配置项关闭。

canTransitionTo：是否与下一个页面联动，栈顶页面该属性置为 false ，推入下一页面时，则栈顶页面始终不动
canTransitionFrom：是否与前一个页面联动，新推入页面该属性置为 false，则栈顶页面始终不动

# 路由上下文对象

由示例模版可见，自定义路由的动画效果就是根据 CustomRouteContext 上下文对象上的路由控制器，编写适当的动画更新函数来实现。

CustomRouteContext 上下文对象还可在页面/自定义组件中通过 wx.router.getRouteContext(this) 读取，进而在手势处理过程中访问，通过对 primaryAnimation 值的改写实现页面手势返回。

小技巧：可在 CustomRouteContext 对象上添加一些私有属性，在页面中进行读取/修改。

# 多类型路由跳转

考虑这样的场景，从页面 A 可能跳转到 B 页和 C 页，但具有不同的路由动画

A -> B 时，希望实现半屏效果，A 需要下沉收缩
A -> C 时，希望采用普通路由，A 需要向左移动

跳转下一级页面时的动画由 handleSecondaryAnimation 控制，这样就需要在定义 A 的 CustomRouteBuilder 时考虑所有的路由类型，实现较为繁琐。

基础库 3.0.0 版本起，自定义路由新增 handlePreviousPageAnimation 接口，用于控制上一级页面的压入/压出动画。

const customRouteBuiler = (routeContext: CustomRouteContext) : CustomRouteConfig => { const { primaryAnimation } = routeContext const handlePrimaryAnimation: RouteAnimationHandler = () => { 'worklet' let t = primaryAnimation.value // 控制当前页的进入和退出 } const handlePreviousPageAnimation: RouteAnimationHandler = () => { 'worklet' let t = primaryAnimation.value // 控制上一级页面的压入和退出 } return { handlePrimaryAnimation, handlePreviousPageAnimation } }

A 跳转到 B 时， A 页 secondaryAnimation 的值始终与 B 页 primaryAnimation 的值同步变化。

我们可以在定义 B 的 CustomRouteBulder 时，通过 primaryAnimation 得知当前路由进度，handlePreviousPageAnimation 返回的 StyleObject 会作用于上一级页面。

同时也不再需要提前声明 A 为自定义路由，在此之前 A 跳转 B 希望实现半屏效果时，A 也必须定义为自定义路由。

完整的示例可参考如下代码，借助 handlePreviousPageAnimation 可去掉对 secondaryAnimation 的依赖，简化代码逻辑。

在开发者工具中预览效果

# 实际案例

下面以半屏效果为例，讲解自定义路由的具体实现过程，完整代码见示例代码。

路由前后页面分别记为 A 页和 B 页，需要分别为其注册自定义路由。未注册任何自定义路由效果时，新打开的页面 B 会立即覆盖显示在 A 页上。

# Step-1 页面进入动画

我们先分别简单实现首页 -> A 页 -> B 页的进入动画，再一步步进行完善。

对于 A 页面，进入方式为自右向左，通过 transform 平移实现。

function ScaleTransitionRouteBuilder(customRouteContext) { const { primaryAnimation } = customRouteContext const handlePrimaryAnimation = () => { 'worklet' let t = primaryAnimation.value const transX = windowWidth * (1 - t) return { transform: `translateX(${transX}px)`, } } return { handlePrimaryAnimation } }

对于 B 页面，进入方式为自底向上，也是通过 transform 平移实现，但需要对页面大小、圆角进行修改。

const HalfScreenDialogRouteBuilder = (customRouteContext) => { const { primaryAnimation, } = customRouteContext const handlePrimaryAnimation = () => { 'worklet' let t = primaryAnimation.value // 距离顶部边距因子 const topDistance = 0.12 // 距离顶部边距 const marginTop = topDistance * screenHeight // 半屏页面大小 const pageHeight = (1 - topDistance) * screenHeight // 自底向上显示页面 const transY = pageHeight * (1 - t) return { overflow: 'hidden', borderRadius: '10px', marginTop: `${marginTop}px`, height: `${pageHeight}px`, transform: `translateY(${transY}px)`, } } return { handlePrimaryAnimation, } }

页面跳转效果如下，可以看到由于采用线性曲线（未对 t 做任何变换），动画有些呆板，同时未区分进入/退出动画。在 B 页完全进入后，A 页变的不可见。

# Step-2 自定义动画曲线

以 B 页为例，根据 AnimationStatus 值，采用不同的动画曲线，同时设置 opaque 为 false，使得路由动画完成后仍显示 A 页面。

const { Easing, derived } = wx.workelt const Curves = { linearToEaseOut: Easing.cubicBezier(0.35, 0.91, 0.33, 0.97), easeInToLinear: Easing.cubicBezier(0.67, 0.03, 0.65, 0.09), fastOutSlowIn: Easing.cubicBezier(0.4, 0.0, 0.2, 1.0), fastLinearToSlowEaseIn: Easing.cubicBezier(0.18, 1.0, 0.04, 1.0), } function CurveAnimation({ animation, animationStatus, curve,reverseCurve }) { return derived(() => { 'worklet' const useForwardCurve = !reverseCurve || animationStatus.value !== AnimationStatus.reverse const activeCurve = useForwardCurve ? curve : reverseCurve const t = animation.value if (!activeCurve) return t if (t === 0 || t === 1) return t return activeCurve(t) }) }

const HalfScreenDialogRouteBuilder = (customRouteContext) => { const { primaryAnimation, primaryAnimationStatus, } = customRouteContext // 1. 页面进入时，采用 Curves.linearToEaseOut 曲线 // 2. 页面退出时，采用 Curves.easeInToLinear 曲线 const _curvePrimaryAnimation = CurveAnimation({ animation: primaryAnimation, animationStatus: primaryAnimationStatus, curve: Curves.linearToEaseOut, reverseCurve: Curves.easeInToLinear, }) const handlePrimaryAnimation = () => { 'worklet' let t = _curvePrimaryAnimation.value ... // 其余内容等上面的代码一致 } return { opaque: false, handlePrimaryAnimation, } }

这里的区别仅在于，当前的进度不再直接读取 primaryAnimation 的值。封装的 CurveAnimation 函数会根据 AnimationStatus 判断是处于进入还是退出状态，从而选择不同的动画曲线。框架提供了多种曲线类型，可进一步参考 worklet.Easing。改进后的页面转场效果如下

# Step-3 页面联动效果

B 页进入时，A 页作压入动画，由 secondaryAnimation 控制。接下来，我们为其添加下沉效果，实现和 B 页的联动。

function ScaleTransitionRouteBuilder(customRouteContext) { const { primaryAnimation } = customRouteContext const handlePrimaryAnimation = () => { 'worklet' ... } const _curveSecondaryAnimation = CurveAnimation({ animation: secondaryAnimation, animationStatus: secondaryAnimationStatus, curve: Curves.fastOutSlowIn, }) const handleSecondaryAnimation = () => { 'worklet' let t = _curveSecondaryAnimation.value // 页面缩放大小 const scale = 0.08 // 距离顶部边距因子 const topDistance = 0.1 // 估算的偏移量 const transY = screenHeight * (topDistance - 0.5 * scale) * t return { overflow: 'hidden', borderRadius: `${ 12 * t }px`, transform: `translateY(${transY}px) scale(${ 1 - scale * t })`, } } return { handlePrimaryAnimation, handleSecondaryAnimation } }

通过对 A 页作 scale 和 translate 变换实现下沉效果。A 页 secondaryAnimation 的值始终与 B 页 primaryAnimation 的值保持同步。

页面是否联动还可通过 canTransitionTo 和 canTransitionFrom 两个属性进行配置，可在开发者工具上修改体验。

# Step-4 手势返回

目前动画效果已经基本实现，还需要最后一步，手势返回。对于半屏效果，我们为 A 页添加右滑返回手势，B 页添加下滑返回手势。

以最常见的右滑返回为例，这里只截取松手后的手势处理部分代码，拖动过程实现较为简单，可参考示例代码。

page({ handleDragEnd(velocity) { 'worklet'; const { primaryAnimation, stopUserGesture, didPop } = this.customRouteContext; let animateForward = false; if (Math.abs(velocity) >= 1.0) { animateForward = velocity <= 0; } else { animateForward = primaryAnimation.value > 0.5; } const t = primaryAnimation.value; const animationCurve = Curves.fastLinearToSlowEaseIn; if (animateForward) { const duration = Math.min( Math.floor(lerp(300, 0, t)), 300, ); primaryAnimation.value = timing( 1.0, { duration, easing: animationCurve, }, () => { 'worklet' stopUserGesture(); }, ); } else { const duration = Math.floor(lerp(0, 300, t)); primaryAnimation.value = timing( 0.0, { duration, easing: animationCurve, }, () => { 'worklet' stopUserGesture(); didPop(); }, ); } }, })

首先根据松手时的速度和位置，决定是否要真正返回上一级。

向右滑动且速度大于 1
或者速度较小时，已拖动超过屏幕 1/2

满足以上条件时，确定返回。通过 timing 接口，为 primaryAnimation 添加过渡动画，使其变化到 0，最后调用 didPop 。否则使其变化到 1，恢复到拖动前的状态。

这里需要注意的是，当需要对 primaryAnimation 值手动修改，自由掌控其过渡方式时，才需要调用 startUserGesture 和 stopUserGesture 接口。

右滑手势已经在示例代码中封装成 swipe-back 组件，开发者可直接使用。下滑手势返回逻辑基本一致，仅一些数值上略有差异。

最后的实现效果如图

# 设置页面透明

一些自定义路由效果下，需要实现页面透明背景，这里对 Skyline 和 webview 模式下背景色的层级关系进行说明。