Skip to content

专属小程序端特性

当你将项目编译到小程序平台时,会面临各个平台的限制,这导致许多特性无法在小程序中使用。然而,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-routersetup 钩子里面的生命周期函数进行了处理,确保其中的生命周期函数按照路由拦截的预期进行执行。因为该限制只针对 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 中需要立即执行的函数,建议将其放置在 onLoadonLaunch 等生命周期函数中。这样可以确保它们按预期执行,并与 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 路径中的参数。

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

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

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

专属小程序端特性 has loaded