uni-simple-router

主题

On this page

专属小程序端特性 ​

Watch a free video lesson on official

当你将项目编译到小程序平台时，会面临各个平台的限制，这导致许多特性无法在小程序中使用。然而，uni-simple-router 尽可能地消除了这些差异，并将功能最大化，以便在小程序开发中能够发挥最大的效益。

特别是对于那些之前没有接触过小程序开发的开发者来说，需要注意不要将 Web 开发的思维方式直接带入小程序开发中。小程序的开发限制非常多，官方提供的 API 也相对较少。因此，在开始小程序开发之前，务必要查阅对应平台的小程序文档，并熟悉相关开发要求。

了解小程序开发平台的限制和规范，以及掌握 uni-simple-router 提供的功能和特性，能够帮助你更好地开发小程序应用。

陷阱提示

  • 当编译为小程序时，请务必认真阅读该文档。

支持的小程序平台 ​

当你有开发小程序的需求时，确保在使用 uni-simple-router 之前查询所需平台的支持度和功能是否在 uni-simple-router 中得到支持。这是非常重要的，因为不同的小程序平台可能有不同的限制和要求。你可以在这里查阅到 目前支持那些平台。

在小程序中使用嵌套路由 ​

使用嵌套路由在日常开发中非常常见。嵌套路由可以帮助你更好地组织和管理页面结构，使应用更具有层次性和灵活性。

然而，在使用嵌套路由或动态路由之前，务必查阅相关文档，了解目标平台是否支持这些功能。

首次冷启动的生命周期拦截 ​

在原生小程序中，底层构建页面必须同步完成，无法使用异步或延迟构建的方式。这就带来了一些兼容性挑战，尤其是对于同时兼容 uni-app 和原生小程序的情况。为了解决这个问题，uni-simple-router 提供了针对首次冷启动时的生命周期拦截。

然而，在 Vue 3 中，引入了一个特殊的编译钩子 setup ，它允许你在运行时提供组合式的 API。由于无法对 setup 钩子进行重写及还原，导致在 setup 钩子中使用了组合API的其他生命周期函数，它们可能无法按预期执行。

针对这个问题，uni-simple-router 对 setup 钩子里面的生命周期函数进行了处理，确保其中的生命周期函数按照路由拦截的预期进行执行。因为该限制只针对 APP.vue 文件，因此，当你在编写 APP.vue 文件下的 setup 时，建议按以下方式改进，以确保生命周期按预期执行：

✅ 正确的选项式： ​

ts
// App.vue
import {getCurrentInstance} from 'vue'
import { onLaunch,onShow,onHide} from '@dcloudio/uni-app'

export default {
  onLaunch: function() {
    console.log('App Launch')
  },
  setup(){
    console.log('setup -- app.vue');
    onLaunch(()=>{
      console.log('setup -- app.vue - onLaunch');
      getRoute();
    })
    onShow(()=>{
      console.log('setup -- app.vue - onShow');
    })
    onHide(()=>{
      console.log('setup -- app.vue - onHide');
    })

    function getRoute(){
      const route = uni.$Route
      console.log(route)
    }

  }
}

✅ 正确的编译式： ​

html
<!-- App.vue -->
<script setup lang="ts">
  import { onLaunch, onShow, onHide } from "@dcloudio/uni-app";
  onLaunch(() => {
    console.log("App Launch");
    getRoute();
  });
  onShow(() => {
    console.log("App Show");
  });
  onHide(() => {
    console.log("App Hide");
  });

  function getRoute(){
    const route = uni.$Route
    console.log(route)
  }
</script>

❌ 错误的编译式 ​

html
<!-- App.vue -->
<script setup lang="ts">
  import { onLaunch, onShow, onHide } from "@dcloudio/uni-app";
  onLaunch(() => {
    console.log("App Launch");
  });

  function getRoute(){
    const route = uni.$Route
    console.log(route)
  }
  getRoute();
</script>

当使用 getRoute() 函数时，建议将其放置在生命周期函数内部，而不是生命周期函数外部。这是因为如果将其放在生命周期函数外部，它将立即执行，而不会按预期执行顺序。而在生命周期函数内部，它会根据路由守卫的拦截执行后再按预期执行。

对于在 setup 中需要立即执行的函数，建议将其放置在 onLoad 或 onLaunch 等生命周期函数中。这样可以确保它们按预期执行，并与 uni-simple-router 的路由拦截机制兼容。

陷阱提示

  • 该限制只针对 App.vue，其他页面或组件不受该限制。

冷启动时的入口动画 ​

在将项目编译为小程序时，uni-simple-router会自动在路由表的第一位添加一个动画页面，类似于App启动页的效果。这个动画页面在小程序中由插件提供，而在App端则由uni-app底层提供。

温馨提示

  • 目前这个动画页面无法进行自定义，也无法取消。然而，未来我们计划对这个动画页面进行扩展，以便开发者可以自定义其外观和行为。在 v1.0.4 中已经可自行配置，详细请查阅文档。

自定义入口动画 1.0.4+ ​

在v1.0.4版本中，我们为开发者提供了自定义动画的配置选项，开发者可以完全自定义入口动画页面内容及窗口样式。了解详细请查看API文档。

如果你正在开发抖音小程序，你可能会遇到如下错误：

sh
小程序自抖音1960版本起，自定义导航栏仅对拥有权限的开发者开放。请完成权限申请，或使用平台提供的标准化导航栏。截止2022年5月23日，未完成操作的小程序将无法更新版本。
请将app.json/page.json中的"navigationStyle": "custom"改为"navigationStyle": "default"。
详情请查看：https://developer.open-douyin.com/forum/synthesize/post/62133f3a4e92f57336ca2f49

因为默认情况下入口动画页面为 custom 风格，在抖音小程序下未申请权限时会有如上警告，所以我们可以利用编译选项配置来关闭默认的 custom 风格。

ts
// vite.config.js
export default defineConfig({
    plugins: [
      vitePluginUniRouter({
        // ...其他配置
        applet:{
          enterPage:{
            style:{
              navigationStyle:`default`
            }
          }
        }
      }),
      uni()
	]
});

无法拦截的原生部分 ​

在小程序中，目前无法通过JavaScript层面拦截原生Tabbar切换、原生Header返回以及手机物理按键返回等原生层面的操作。这些操作都属于小程序的原生功能，在官方未提供相应的API的情况下，JavaScript层面无法直接拦截它们。

然而，uni-simple-router仍然支持其他情况下的路由拦截，并可以通过监听路由信息变化来处理一些逻辑。你可以在路由信息变化时执行一些特定的操作或逻辑，以满足业务需求。

陷阱提示

  • 请注意，在小程序中，原生Tabbar切换、原生Header返回和手机物理按键返回等行为由小程序底层管理，无法直接在JavaScript层面对其进行干预。
  • 我们会持续关注官方动态，如有提供处理方案，我们会在第一时间更新插件。

推送跳转至指定页面 ​

在小程序中，常常需要通过推送模板消息将用户导航到指定页面。然而，在uni-simple-router中，由于存在嵌套路由，无法像传统方式那样在小程序后台直接配置目标地址。相反，你应该按照uni-simple-router提供的方式进行页面跳转。

在uni-simple-router中，跳转至指定页面非常简单。你只需按照下面的配置进行简单的设置，即可完成页面跳转并传递参数。

像这样 /uni-simple-router/inspect/loading?__redirect__=/customTabbar/me&name=hhyang&ages=12345 的路径配置即可完成重定向。

  • /uni-simple-router/inspect/loading： 在小程序中，该目录会自动生成。其中，uni-simple-router 是插件包的路径，而 /inspect/loading 是自动生成的加载页路径。在实际开发中，如果需要将 uni-simple-router 的路径修改为你自己的路径，然后拼接上 /inspect/loading 即可使用自定义路径，记住最前面记得加 /。

  • __redirect__=/customTabbar/me： 需要跳转的路径表路径。__redirect__ 为标识符，后面跟路由表中需要跳转的路径，可以为任何路径表中的地址。

  • &name=hhyang&ages=12345： 其他需要传递到 /customTabbar/me 路径中的参数。

web-view组件中导航到其他页面 1.1.5+ ​

如果你需要在 web-view 加载的 h5 页面中，导航到小程序内部的其他页面位置时，插件提供了一套兼容方案，以达到适配的问题。具体如下：

插件捕捉了web-view 导航中的两个内部变量分别是：

  1. __navtype__ : 必填 可选类型 push、 replaceAll、 replace、 pushTab
  2. __t__ : 必填 当前页面执行的唯一标识符，该参数应当是 毫秒级时间戳

示例

html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
</head>
<body>
    <button id="navigateTo">navigateTo</button>
    <button id="reLaunch">reLaunch</button>
    <button id="redirectTo">redirectTo</button>
    <button id="back">navigateBack</button>
    <button id="switchTab">switchTab</button>
    <script src="https://res.wx.qq.com/open/js/jweixin-1.3.2.js"></script>
    <script>
        document.querySelector('#navigateTo').addEventListener('click',()=>{
            wx.miniProgram.navigateTo({
                url:`/pages/index3/index3?__navtype__=push&__t__=${+new Date()}`,
            })
        })
        document.querySelector('#reLaunch').addEventListener('click',()=>{
            wx.miniProgram.reLaunch({
                url:`/pages/index/index?__navtype__=replaceAll&__t__=${+new Date()}`
            })
        })
        document.querySelector('#redirectTo').addEventListener('click',()=>{
            wx.miniProgram.redirectTo({
                url:`/pages/index3/index3?__navtype__=replace&__t__=${+new Date()}`
            })
        })
        document.querySelector('#back').addEventListener('click',()=>{
            wx.miniProgram.navigateBack()
        })
        document.querySelector('#switchTab').addEventListener('click',()=>{
            // 这里可以不用传递 __navtype__ 及 __t__ 参数
            wx.miniProgram.switchTab({
                url:`/pages/tabbar/tabbar2`
            })
        })
    </script>
</body>
</html>

根据示例可清晰的看到我们只需要在必要的导航时传递对应的 __navtype__ 及 __t__ 参数即可。其他的工作可完全交给插件内部去完成，你只需要关注 __navtype__ 即可，对照表如下：

原生__navtype__必填描述
navigateTopush✅__navtype__ 及 __t__ 必填
reLaunchreplaceAll✅__navtype__ 及 __t__ 必填
redirectToreplace✅__navtype__ 及 __t__ 必填
navigateBackback❌__navtype__ 及 __t__ 可以都不填
switchTabpushTab❌__navtype__ 及 __t__ 可以都不填

开发环境下热更到指定页面 ​

在开发环境下，你可能正在编写对应页面的 UI，并进行热更新调试。通常情况下，每次热更新后应用会回到初始页面，而不是之前正在调试的页面。

如果你希望在热更新时也能回到指定页面，你可以参考 开发与热更 部分的详细说明。该部分会提供相关的指导，帮助你配置 uni-simple-router，使得在热更新时也能恢复到指定页面。