skyline-route

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skyline 自定义路由与页面转场

Skyline Custom Route and Page Transition

适用场景

Applicable Scenarios

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

Implement custom page transition animations (half-screen, scaling, fade-in, etc.)
Quickly implement common transition effects using preset routes
Configure page back gestures (horizontal/vertical/multi-directional)
Implement container transition animation for card expansion to detail page
Manage custom routes through Router API

核心概念

Core Concepts

路由能力层级

Route Capability Levels

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

Level	Capability	Applicable Scenario
Preset Route	Use 7 built-in effects with one line of code	Quickly implement common transitions
Custom Route	Fully control animations via routeBuilder	Highly customized transitions
Container Transition	`<open-container>` element-level transition	Card expansion to detail page

动画控制器

Animation Controller

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

Property	Description
primaryAnimation	Page entry/exit animation progress (0→1 for entry, 1→0 for exit)
secondaryAnimation	Animation progress of current page when the next page enters (synchronized with the primaryAnimation of the next page)
userGestureInProgress	Whether the current routing progress is controlled by gesture
startUserGesture / stopUserGesture	Gesture takes over/releases routing control
didPop	Confirm to return to the previous page

文档索引

Document Index

根据需求快速定位（路径相对于

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`

Quickly locate according to requirements (paths are relative to

references/

I want to...	Refer to Document
Understand custom route principles and interfaces	`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 transition	`open-container/open-container.md`
View Router API	`api/router-api.md`
Understand navigateTo routing parameters	`api/navigate-to.md`
Listen to routing events	`api/route-events.md`

强制规则

Mandatory Rules

MUST（必须遵守）

MUST (Must Comply)

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

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

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

// ✅ 正确
const handlePrimaryAnimation = () => {
  'worklet'
  return { transform: `translateX(${...}px)` }
}

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

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

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

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

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

navigator 组件在 Skyline 下只能嵌套文本节点：

html

<!-- ✅ 正确 -->
<navigator url="/page">点击跳转</navigator>

<!-- ❌ 错误：不能嵌套 view 等普通节点 -->
<navigator url="/page"><view>跳转</view></navigator>

Custom routes only take effect between consecutive Skyline pages: WebView pages do not support custom routes

// ✅ Page A (Skyline) → Page B (Skyline): Custom route takes effect
// ❌ Page A (WebView) → Page B (Skyline): Degrade to default route

The animation processing function must declare the 'worklet' directive:

// ✅ Correct
const handlePrimaryAnimation = () => {
  'worklet'
  return { transform: `translateX(${...}px)` }
}

// ❌ Incorrect: Missing worklet directive, cannot execute in UI thread
const handlePrimaryAnimation = () => {
  return { transform: `translateX(${...}px)` }
}

Gesture takeover must call startUserGesture / stopUserGesture in pairs:

// ✅ Correct
handleDragStart() {
  'worklet'
  this.customRouteContext.startUserGesture()
}
handleDragEnd() {
  'worklet'
  // ... In animation completion callback:
  stopUserGesture()
}

must call didPop when confirming return: The engine cannot automatically determine whether the developer wants to exit the page

// ✅ Correct: Call didPop after animation is completed
primaryAnimation.value = timing(0.0, { duration }, () => {
  'worklet'
  didPop()
  stopUserGesture()
})

The navigator component can only nest text nodes under Skyline:

html

<!-- ✅ Correct -->
<navigator url="/page">Click to jump</navigator>

<!-- ❌ Incorrect: Cannot nest ordinary nodes such as view -->
<navigator url="/page"><view>Jump</view></navigator>

NEVER（禁止行为）

NEVER (Prohibited Behaviors)

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

NEVER directly modify
```
primaryAnimation.value
```
in gesture processing without calling
```
startUserGesture
```
NEVER assume that custom routes take effect on WebView pages (lower version basic libraries will degrade)
NEVER access
```
primaryAnimation.value
```
in non-worklet functions

Quick Reference

预设路由速查

Preset Route Quick Check

routeType	效果	最低基础库
`wx://bottom-sheet`	底部弹出半屏	3.1.0
`wx://upwards`	自底向上全屏	3.1.0
`wx://zoom`	缩放进入	3.1.0
`wx://cupertino-modal`	iOS 风格模态	3.1.0
`wx://cupertino-modal-inside`	iOS 模态内嵌	3.1.0
`wx://modal-navigation`	模态导航	3.1.0
`wx://modal`	模态弹窗	3.1.0

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

routeType	Effect	Minimum Basic Library Version
`wx://bottom-sheet`	Bottom pop-up half screen	3.1.0
`wx://upwards`	Full screen from bottom to top	3.1.0
`wx://zoom`	Zoom 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

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

API 速查

API Quick Check

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

API	Description	Minimum Basic Library Version
`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 routing context	2.29.2
`wx.navigateTo({ routeType })`	Jump with specified route type	2.29.2
`wx.navigateTo({ routeConfig })`	Override routing configuration	3.4.0
`wx.navigateTo({ routeOptions })`	Pass routing parameters	3.4.0
`wx.navigateTo({ withOpenContainer })`	Container transition jump	3.12.2
`wx.onBeforeAppRoute(fn)`	Listen before routing execution	3.5.5
`wx.onAppRoute(fn)`	Listen after routing 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' })

// Register: Slide in from right
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 }
})

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

场景决策表

Scenario Decision Table

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

Scenario	Recommended Solution
Bottom pop-up half screen	Preset route `wx://bottom-sheet`
iOS style modal	Preset route `wx://cupertino-modal`
Custom half screen + gesture	Custom route + handlePrimaryAnimation
Card expansion to detail page	`<open-container>` container transition
Page fade-in effect	Custom route + opacity animation
Require vertical back gesture	`popGestureDirection: 'vertical'`

Related Skills

场景	推荐技能	说明
动画开发	`skyline-worklet`	Worklet 动画系统（timing/spring/Easing）
手势处理	`skyline-components`	gesture-handler 手势组件
共享元素	`skyline-components`	share-element 页面间动画
配置详解	`skyline-config`	app.json/page.json 配置
概览迁移	`skyline-overview`	Skyline 概览与迁移指南

Scenario	Recommended Skill	Description
Animation development	`skyline-worklet`	Worklet animation system (timing/spring/Easing)
Gesture processing	`skyline-components`	gesture-handler gesture component
Shared element	`skyline-components`	share-element cross-page animation
Configuration explanation	`skyline-config`	app.json/page.json configuration
Overview migration	`skyline-overview`	Skyline overview and migration guide

References 目录结构

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

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

skyline-route

Original

Translation

Skyline 自定义路由与页面转场

Skyline Custom Route and Page Transition

适用场景

Applicable Scenarios

核心概念

Core Concepts

路由能力层级

Route Capability Levels

动画控制器

Animation Controller

文档索引

Document Index

强制规则

Mandatory Rules

MUST（必须遵守）

MUST (Must Comply)

NEVER（禁止行为）

NEVER (Prohibited Behaviors)

Quick Reference

Quick Reference

预设路由速查

Preset Route Quick Check

API 速查

API Quick Check

自定义路由最小示例

Minimal Custom Route Example

场景决策表

Scenario Decision Table

相关技能

Related Skills

References 目录结构

References Directory Structure