Skip to content

快速上手

先决条件

  • 在开始之前,确保你已经跟随 安装 文档进行了必要的设置。
  • 安装 Node.js 16.0 或更高版本
  • 如果你喜欢使用 IDE 创建项目,请确保 HBuilderX 版本 在 3.7.11.20230427 或更高版本
  • 如果你喜欢使用 CLI 创建项目,请确保 官方依赖 版本 在 3.0.0-alpha-3070720230316001 或更高版本
  • 当您准备将插件包与uni-app工程集成时,请确保您已经获得授权并成功下载插件包。这样可以确保您有合法的许可证,并且可以顺利进行集成和使用插件的功能。

使用 uni-app 和 uni-simple-router 创建应用非常简单。通过 uni-simple-router,我们可以使用任何组件来构建我们的应用。当使用 uni-simple-router 时,我们只需要将我们的组件映射到路由上,让 uni-simple-router 知道在哪里渲染它们,而无需关注 pages.json。

从显示 Hello Word 开始

如果你已经按照 安装 文档的配置完成,并顺利到达这一步,恭喜你!你已经成功地集成了 uni-simple-router。现在你可以重新编译你的项目,享用uni-simple-router带来的灵活与高效。现在我们将改进配置,并构建一个真正的应用。

我们先从最简单的输出 'Hello World' 开始,在跟随安装文档进行配置时,我们注册了一个组件,并将其位置设置为 pages/index.vue。现在,我们将改进这个组件,以便在编译后能够显示出 'Hello World'。

vue
// pages/index.vue
<template>
  <view class="content">
    <h1>{{ title }}</h1>
  </view>
</template>

<script setup lang="ts">
import { ref } from 'vue'
const title = ref('Hello World')
</script>

编译后,我们将在终端上看到 'Hello World' 的字样,并伴随着一个默认的固定 uni-app 标题栏。现在,让我们尝试在注册路由表时更改导航栏的样式。请按照以下步骤修改 router.js 文件:

js
// router.js
import {
    createRouter,
    __dynamicImportComponent__
} from '@/uni-simple-router'

const router = createRouter({
	platform: process.env.VUE_APP_PLATFORM,
    routes:[{
        path:`/`,
        component:__dynamicImportComponent__(`@/pages/index.vue`,{
            pageType:`top`,
            style:{ 
                navigationBarTitleText:`uni-simple-router`, 
                navigationBarBackgroundColor:`#42b883`, 
                navigationBarTextStyle:`white`  
            } 
        })
    }]
})

export default router

请注意以上代码中标有糟色的部分,我们对原始的 uni-app 样式进行了重置,并将导航栏样式修改为白色字体绿色背景标题栏为 uni-simple-router。此外,你还可以通过 __dynamicImportComponent__ 函数的 style 字段修改其他默认配置,该字段与 pages.json 文件中的 pages -> style 字段完全相同。如果你希望了解完整的配置选项,请点击这里

注册多个顶级页面

在应用中,uni-simple-router 允许你有一个或多个顶级页面。顶级页面是指保留了 uni-app 的所有原始配置的页面,就像你以前在 pages.json 中定义的页面一样。注册顶级页面非常简单,就像下面的示例一样:

js
// router.js
import {
    createRouter,
    __dynamicImportComponent__,
    type platformRule
} from '@/uni-simple-router'

const router = createRouter({
    platform:process.env.VUE_APP_PLATFORM as platformRule,
    routes:[
        {
            path:`/`,
            component:__dynamicImportComponent__(`@/pages/index.vue`,{
                pageType:`top`,
                style:{
                    navigationBarTitleText:`uni-simple-router`,
                    navigationBarBackgroundColor:`#42b883`,
                    navigationBarTextStyle:`white`
                }
            })
        },
        // 下方是注册的新顶级页面
        { 
            path:`/my`, 
            component:__dynamicImportComponent__(`@/pages/my.vue`,{ 
                pageType:`top`  
            })  
        }, 
        //  或者注册更多的顶级页面
    ]
})

顶级页面会继承 uni-app 的原始配置和机制,因此当你进行页面跳转时,它与原始的 uni-app 页面没有任何区别。这意味着你可以像平常一样使用 uni-app 的导航 API(如 uni.navigateTo、uni.redirectTo、uni.reLaunch 等)在顶级页面之间进行跳转。同时,uni-simple-router 还提供了自己的路由 API(如 $Router.push、$Router.replace、$Router.back 等),方便你进行更灵活的导航操作。

无论是在顶级页面还是在 uni-simple-router 的其他页面,你都可以使用相同的导航方式,享受统一的开发体验。

为顶级页面注册子页面

在一些复杂的场景下,仅仅依靠独立的顶级页面可能无法满足需求,而 uni-simple-router 提供了子路由页面的支持,也就是嵌套路由。子路由允许你在一个页面中嵌套多个子页面,常见的应用场景包括后台管理中的左侧导航栏和右侧内容展示区、手机端开发时的底部菜单导航等等。

js
// router.js
import {
    createRouter,
    __dynamicImportComponent__,
    type platformRule
} from '@/uni-simple-router'

const router = createRouter({
    platform:process.env.VUE_APP_PLATFORM as platformRule,
    routes:[
        {
            path:`/`,
            component:__dynamicImportComponent__(`@/pages/index.vue`,{
                pageType:`top`,
                style:{
                    navigationBarTitleText:`uni-simple-router`,
                    navigationBarBackgroundColor:`#42b883`,
                    navigationBarTextStyle:`white`
                }
            }),
        },
        {
            path:`/my`,
            component:__dynamicImportComponent__(`@/pages/my.vue`,{
                pageType:`top`
            }),
            children:[
                {
                    path:`profile`,
                    name:`profile`,
                    component:__dynamicImportComponent__(`@/components/profile.vue`)
                },
                {
                    path:`setting`,
                    name:`setting`,
                    component:__dynamicImportComponent__(`@/components/setting.vue`)
                }
            ]
        }
    ]
})

修改 pages/my.vue 内容并添加子路由挂载点 <simple-router-view/>

vue
// pages/my.vue 
<template>
    <view class="content">
        <h1>my page</h1>
        <div class="content childCont">
            <div class="menus border">
                <div 
                    v-for="(it,i) in menus" 
                    :key="i" 
                    class="menu" 
                    @click="goNav(it.name)"
                >
                    {{ it.name }}
                </div>
            </div>
            <div class="realCont border">
                <simple-router-view></simple-router-view>
            </div>
        </div>
    </view>
</template>

<script setup lang="ts">
import { useRouter } from '@/uni-simple-router'; 
import { ref ,reactive} from 'vue'
const router = useRouter();

const menus = reactive([{
    name:`profile`
},{
    name:`setting`
}])

function goNav(name:string){
    router.replace({
        name
    })
}
</script>
<style scoped>
.content{
    padding: 20rpx;
    box-sizing: border-box;
}
.childCont{
    display: flex;
}
.childCont .menus{
    width: auto;
}
.realCont{
    flex: 1;
    margin-left: 20rpx;
}   
.border{
    border: 1px solid black;
}
.menus .menu{
    margin-bottom: 10rpx;
    cursor: pointer;
    color: blue;
}
</style>

页面之间的互相跳转

在日常的应用开发中,路由导航是一个不可或缺的部分。uni-simple-router 提供了多种方式来进行页面跳转,既可以使用 uni-app 原生的导航方式,也可以利用插件内置的函数进行跳转。

vue
// pages/index.vue
<template>
  <view class="content">
    <h1>{{ title }}</h1>
    <button @click="goToPage(`/my`)"> 
      导航去my页面  
    </button> 
    <button @click="goToPage({name:`profile`})">  
      导航去my/profile页面  
    </button> 
  </view>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { useRouter } from '@/uni-simple-router'; 
const router = useRouter(); 

const title = ref('Hello World')

function goToPage(options:any){ 
  router.push(options)  
  // 与如下跳转方式相同 
  // uni.navigateTo(options)  
} 

</script>
快速上手 has loaded