1. 什么是编程式导航？

编程式导航是通过代码来控制页面跳转的方式。它可以根据业务逻辑动态跳转到不同页面，并支持传递参数、页面间事件通信等操作。与导航式跳转（如 navigator 组件）不同，编程式跳转更适合复杂场景，如表单提交后的跳转、条件跳转等。

2. 常用编程式导航 API 介绍

2.1 uni.navigateTo(OBJECT)

• 作用：保留当前页面，跳转到应用内非 tabBar 的页面。使用 uni.navigateBack() 可以返回原页面。
• 限制：不能跳转到 tabBar 页面。

主要参数说明

参数名	类型	必填	默认值	说明
url	String	是	无	需要跳转的应用内页面的路径，路径后可以带参数，如 'path?key=value&key2=value2'。
animationType	String	否	pop-in	窗口显示的动画效果，详见：窗口动画。仅 App 平台支持。
animationDuration	Number	否	300	窗口动画持续时间，单位为 ms。仅 App 平台支持。
events	Object	否	无	页面间通信接口，用于监听被打开页面发送到当前页面的数据。
success	Function	否	无	接口调用成功的回调函数。
fail	Function	否	无	接口调用失败的回调函数。
complete	Function	否	无	接口调用结束的回调函数，无论成功或失败都会执行。

跳转并传递参数

<template>
  <view>
    <button @click="goToTestPage">跳转到 Test 页面</button>
  </view>
</template>

<script setup>
/* 跳转到 test 页面并传递参数 */
const goToTestPage = () => {
  uni.navigateTo({
    url: '/pages/test?id=1&name=uniapp', // 目标页面路径和参数
  });
};
</script>

接收参数

在目标页面 (test.vue) 中使用 onLoad 钩子函数接收传递的参数：

<template>
  <view>
    <text>ID: {{ id }}</text>
    <text>Name: {{ name }}</text>
  </view>
</template>

<script setup>
import { ref } from 'vue';
const id = ref('');
const name = ref('');

/* 在页面加载时获取传递的参数 */
onLoad((option) => {
  id.value = option.id;
  name.value = option.name;
});
</script>

页面间事件通信

页面之间可以通过 eventChannel 进行数据通信。uni.navigateTo() 支持事件监听和触发。

<template>
  <view>
    <button @click="goToTestPage">跳转并传递事件数据</button>
  </view>
</template>

<script setup>
/* 跳转并监听 test 页面发送的事件 */
const goToTestPage = () => {
  uni.navigateTo({
    url: '/pages/test?id=1',
    events: {
      // 监听被打开页面传递过来的数据
      acceptDataFromOpenedPage(data) {
        console.log(data);
      },
    },
    success(res) {
      // 通过 eventChannel 发送数据给打开的页面
      res.eventChannel.emit('acceptDataFromOpenerPage', { data: '来自 starter 页面的数据' });
    },
  });
};
</script>

在 test.vue 中，使用 getOpenerEventChannel() 来获取数据：

<script setup>
onLoad(() => {
  const eventChannel = getCurrentInstance().proxy.getOpenerEventChannel();

  // 接收从跳转页面传递的数据
  eventChannel.on('acceptDataFromOpenerPage', (data) => {
    console.log('来自 opener 页面的数据:', data);
  });
});
</script>

2.2 uni.redirectTo(OBJECT)

• 作用：关闭当前页面，跳转到应用内非 tabBar 的页面。
• 限制：不能跳转到 tabBar 页面。

重定向跳转

<template>
  <view>
    <button @click="redirectToSecondPage">重定向到 Second 页面</button>
  </view>
</template>

<script setup>
/* 重定向到 second 页面 */
const redirectToSecondPage = () => {
  uni.redirectTo({
    url: '/pages/second?id=2', // 目标页面路径和参数
  });
};
</script>

2.3 uni.switchTab(OBJECT)

• 作用：跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面。
• 限制：只能跳转到 pages.json 中定义的 tabBar 页面。

切换到 tabBar 页面

<template>
  <view>
    <button @click="switchToHomeTab">切换到 Home Tab 页面</button>
  </view>
</template>

<script setup>
/* 切换到 home tab 页面 */
const switchToHomeTab = () => {
  uni.switchTab({
    url: '/pages/tabBar/home/home', // 目标 tabBar 页面路径
  });
};
</script>

2.4 uni.reLaunch(OBJECT)

• 作用：关闭所有页面，打开到应用内的某个页面。常用于重新启动应用场景。
• 限制：跳转到 tabBar 页面时不能带参数。

重启并跳转

<template>
  <view>
    <button @click="reLaunchToHomePage">重启并跳转到首页</button>
  </view>
</template>

<script setup>
/* 重启应用并跳转到 home 页面 */
const reLaunchToHomePage = () => {
  uni.reLaunch({
    url: '/pages/home/home', // 目标页面路径
  });
};
</script>

2.5 uni.navigateBack(OBJECT)

• 作用：关闭当前页面，返回上一页面或多级页面。
• 限制：可以通过 delta 参数控制返回的层数。

返回两层页面

<template>
  <view>
    <button @click="navigateBackTwoPages">返回两层页面</button>
  </view>
</template>

<script setup>
/* 返回两层页面 */
const navigateBackTwoPages = () => {
  uni.navigateBack({
    delta: 2, // 返回两层页面
  });
};
</script>

3. 编程式导航的应用场景

• 表单提交后的跳转：表单提交成功后跳转到详情页或确认页。
• 条件导航：根据用户权限或操作结果跳转到不同的页面。
• 页面间数据通信：使用 eventChannel 实现页面间的数据传递与通信。
• 导航栈控制：根据需要控制页面返回栈，避免多次页面跳转导致的栈溢出问题。

4. 编程式导航的综合案例

以下案例展示了如何结合多个 API 实现复杂的页面跳转与数据传递。

<template>
  <view>
    <button @click="goToTestPage">跳转到 Test 页面并传递参数</button>
    <button @click="redirectToSecondPage">重定向到 Second 页面</button>
    <button @click="switchToHomeTab">切换到 Home

 Tab 页面</button>
    <button @click="reLaunchToHomePage">重启并跳转到首页</button>
    <button @click="navigateBackTwoPages">返回两层页面</button>
  </view>
</template>

<script setup>
/* 跳转到 test 页面并传递参数 */
const goToTestPage = () => {
  uni.navigateTo({
    url: '/pages/test?id=1&name=uniapp',
    success(res) {
      res.eventChannel.emit('acceptDataFromOpenerPage', { data: '来自 starter 页的数据' });
    }
  });
};

/* 重定向到 second 页面 */
const redirectToSecondPage = () => {
  uni.redirectTo({
    url: '/pages/second?id=2',
  });
};

/* 切换到 home tab 页面 */
const switchToHomeTab = () => {
  uni.switchTab({
    url: '/pages/tabBar/home/home',
  });
};

/* 重启应用并跳转到 home 页面 */
const reLaunchToHomePage = () => {
  uni.reLaunch({
    url: '/pages/home/home',
  });
};

/* 返回两层页面 */
const navigateBackTwoPages = () => {
  uni.navigateBack({
    delta: 2,
  });
};
</script>

总结

编程式导航在 Uniapp 中是非常灵活的页面跳转方式，通过不同的 API，可以实现页面跳转、事件通信、数据传递等复杂的交互操作。在实际开发中，合理运用这些 API，能够大大提高应用的用户体验和导航性能。