@tarojsx/history

⏮️
Taro3 History API

Taro3 history 风格路由接口.

_{当前代码提交频繁, 一些特性时有变化.}


^{Built with :purple_heart: by @Colder and Contributors
:star2: :eyes: :zap: :boom:}

npm i @tarojsx/history

介绍

一个建立在 Taro3 之上的轻量级路由包装 API, 语法上类似人们熟知的 react-router 中的 history 模块.

简化页面跳转, 不必思考什么时候该用 navigateTo 什么时候该用 switchTab, 自动序列化 query 参数.

提供监听路由变化的能力, 即使是点击页面上的"返回"按钮或使用 <navigator /> 组件.

需求

taro 3.0.0-rc.1 +

用法

import history from '@tarojsx/history'

// 监听路由
const unlisten = history.listen((location, action) => {
    // location 是 Taro 路由参数对象.
    console.log('路由变化:', action, location.path, location.params);
});

/**********
 以下操作在不使用 history 时同样会触发路由变化事件.
 例如:
    Taro.navigateTo
    wx.navigateTo
    <navigator>
    页面返回按钮
 **********/

// 初始页面为 /pages/index

history.push('/pages/list')
// 路由变化: navigateTo '/pages/list'

history.push('/pages/item', { id: 1 })
// 路由变化: navigateTo '/pages/item' { id: 1 }

console.log(`页面栈长度 ${history.length}, 当前页面 ${history.location.path}, 最后动作 ${history.action}.`)
// 页面栈长度 3, 当前页面 /pages/item, 最后动作 navigateTo.

history.goBack()
// 路由变化: navigateBack '/pages/list'

history.replace('/pages/about')
// 路由变化: redirectTo '/pages/about'

history.push('/pages/tabpage')
// 路由变化: switchTab '/pages/tabpage'

// 停止监听
unlisten()

原理

小程序中唯一能够获取到路由信息变化的途径是监听页面的 onLoad 和 onShow 生命周期, 作为第三方库这是不现实的, Taro 在这两个生命周期中统一设置 Current.router, 在这个字段上定义 setter 成为最简便的监听方式.

每当 setter 被调用时, 代表页面发生跳转, 通过比对 getCurrentPages() 前后变化, 推导出刚刚发生的动作.

变化前	变化后	动作
page1	page1,page2	navigateTo
page1,page2	page1,page3	redirectTo
page1,page2	page1	navigateBack
tab1,page1	tab2	switchTab

特殊情况:

• 从 tab1,page1 到 tab1, 假定为 navigateBack.
• reLaunch 暂时无法判断.
• 循环页面可能发生意想不到的效果, page1,page2,page1

FAQ

为什么不使用 wx.onAppRoute?

这是一个私有的 API, 在其他端兼容性不明.

TODO

• taro rc1 #6412
• goForward()
• action: 'appLaunch'
• action: 'reLaunch'

支持

欢迎各种形式的支持. 至少可以给颗星 :star:

License

MIT