README



⏮️
Taro3 History API



Taro3 history 风格路由接口.

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

Licensenpm versionnpm downloadsdependentsPRs welcome
Built with :purple_heart: by@Colder andContributors
: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() 前后变化, 推导出刚刚发生的动作.

变化前变化后动作
page1page1,page2navigateTo
page1,page2page1,page3redirectTo
page1,page2page1navigateBack
tab1,page1tab2switchTab

特殊情况:

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

FAQ

为什么不使用 wx.onAppRoute?

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

TODO

支持

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

License

MIT