uni-app
uni-app x
uniCloud
HBuilder X
uni 小程序 sdk
uni-ad广告
开发者服务
uni-app x
uni-app
uni-app x
uniCloud
HBuilder X
uni 小程序 sdk
uni-ad广告
开发者服务
简体中文
API
uni.navigateTo(options)
navigateTo 兼容性
参数
NavigateToSuccess 的属性值
NavigateToFail 的属性值
NavigateToComplete 的属性值
返回值
参见
uni.redirectTo(options)
redirectTo 兼容性
展示全部

保留当前页面，跳转到应用内的某个页面

Web 微信小程序 Android iOS HarmonyOS HarmonyOS(Vapor)
4.0 4.41 √ 4.11 4.61 5.0

# 参数

名称 类型 必填 默认值 兼容性 描述
options NavigateToOptions 是 -
-
名称 类型 必备 默认值 兼容性 描述
url string (string.PageURIString) 是 -
需要跳转的应用内非 tabBar 的页面的路径 , 路径后可以带参数
animationType string 否 -
窗口显示的动画类型
合法值 兼容性 描述
auto
自动选择动画效果
none
无动画效果
slide-in-right
从右侧横向滑动效果
slide-in-left
从左侧横向滑动效果
slide-in-top
从上侧竖向滑动效果
slide-in-bottom
从下侧竖向滑动效果
fade-in
从完全透明到不透明逐渐显示
zoom-out
在屏幕中间从小到大逐渐放大显示
zoom-fade-out
从大逐渐缩小并且从不透明到透明逐渐隐藏关闭动画
pop-in
从右侧平移出栈动画效果
animationDuration number 否 -
窗口显示动画的持续时间，单位为 ms
events any 否 -
页面间通信接口，用于监听被打开页面发送到当前页面的数据
success (result: NavigateToSuccess) => void 否 -
接口调用成功的回调函数
fail (result: NavigateToFail) => void 否 -
接口调用失败的回调函数
complete (result: NavigateToComplete) => void 否 -
接口调用结束的回调函数（调用成功、失败都会执行）
routeConfig any 否 -
routeOptions any 否 -
routeType string 否 -
名称 类型 必备 默认值 兼容性 描述
errMsg string 是 -
-
名称 类型 必备 默认值 兼容性 描述
errCode number 是 -
-
路由错误码
- 4: 框架内部异常
errSubject string 是 -
-
统一错误主题（模块）名称
data any 否 -
-
错误信息中包含的数据
cause Error 否 -
-
源错误信息，可以包含多个错误，详见SourceError
errMsg string 是 -
-
名称 类型 必备 默认值 兼容性 描述
errMsg string 是 -
-

# 返回值

类型 必备
Promise<NavigateToSuccess> 否
名称 类型 必备 默认值 兼容性 描述
errMsg string 是 -
-

# 参见

# uni.redirectTo(options)

关闭当前页面，跳转到应用内的某个页面

# redirectTo 兼容性

Web 微信小程序 Android iOS HarmonyOS HarmonyOS(Vapor)
4.0 4.41 √ 4.11 4.61 5.0

# 参数

名称 类型 必填 默认值 兼容性 描述
options RedirectToOptions 是 -
-
名称 类型 必备 默认值 兼容性 描述
url string (string.PageURIString) 是 -
需要跳转的应用内非 tabBar 的页面的路径 , 路径后可以带参数
success (result: RedirectToSuccess) => void 否 -
接口调用成功的回调函数
fail (result: RedirectToFail) => void 否 -
接口调用失败的回调函数
complete (result: RedirectToComplete) => void 否 -
接口调用结束的回调函数（调用成功、失败都会执行）

# RedirectToSuccess 的属性值

名称 类型 必备 默认值 兼容性 描述
errMsg string 是 -
-

# RedirectToFail 的属性值

名称 类型 必备 默认值 兼容性 描述
errCode number 是 -
-
路由错误码
- 4: 框架内部异常
errSubject string 是 -
-
统一错误主题（模块）名称
data any 否 -
-
错误信息中包含的数据
cause Error 否 -
-
源错误信息，可以包含多个错误，详见SourceError
errMsg string 是 -
-

# RedirectToComplete 的属性值

名称 类型 必备 默认值 兼容性 描述
errMsg string 是 -
-

# 返回值

类型 必备
Promise<RedirectToSuccess> 否
名称 类型 必备 默认值 兼容性 描述
errMsg string 是 -
-

# 参见

# uni.reLaunch(options)

关闭所有页面，打开到应用内的某个页面

# reLaunch 兼容性

Web 微信小程序 Android iOS HarmonyOS HarmonyOS(Vapor)
4.0 4.41 √ 4.11 4.61 5.0

# 参数

名称 类型 必填 默认值 兼容性 描述
options ReLaunchOptions 是 -
-
名称 类型 必备 默认值 兼容性 描述
url string (string.PageURIString) 是 -
需要跳转的应用内页面路径 , 路径后可以带参数。参数与路径之间使用?分隔，参数键与参数值用=相连，不同参数用&分隔；如 'path?key=value&key2=value2'，如果跳转的页面路径是 tabBar 页面则不能带参数
success (result: ReLaunchSuccess) => void 否 -
接口调用成功的回调函数
fail (result: ReLaunchFail) => void 否 -
接口调用失败的回调函数
complete (result: ReLaunchComplete) => void 否 -
接口调用结束的回调函数（调用成功、失败都会执行）

# ReLaunchSuccess 的属性值

名称 类型 必备 默认值 兼容性 描述
errMsg string 是 -
-

# ReLaunchFail 的属性值

名称 类型 必备 默认值 兼容性 描述
errCode number 是 -
-
路由错误码
- 4: 框架内部异常
errSubject string 是 -
-
统一错误主题（模块）名称
data any 否 -
-
错误信息中包含的数据
cause Error 否 -
-
源错误信息，可以包含多个错误，详见SourceError
errMsg string 是 -
-

# ReLaunchComplete 的属性值

名称 类型 必备 默认值 兼容性 描述
errMsg string 是 -
-

# 返回值

类型 必备
Promise<ReLaunchSuccess> 否
名称 类型 必备 默认值 兼容性 描述
errMsg string 是 -
-

# 参见

# uni.switchTab(options)

跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面

# switchTab 兼容性

Web 微信小程序 Android iOS HarmonyOS HarmonyOS(Vapor)
4.0 4.41 √ 4.11 4.61 5.0

# 参数

名称 类型 必填 默认值 兼容性 描述
options SwitchTabOptions 是 -
-
名称 类型 必备 默认值 兼容性 描述
url string (string.PageURIString) 是 -
需要跳转的 tabBar 页面的路径，路径后不能带参数
success (result: SwitchTabSuccess) => void 否 -
接口调用成功的回调函数
fail (result: SwitchTabFail) => void 否 -
接口调用失败的回调函数
complete (result: SwitchTabComplete) => void 否 -
接口调用结束的回调函数（调用成功、失败都会执行）

# SwitchTabSuccess 的属性值

名称 类型 必备 默认值 兼容性 描述
errMsg string 是 -
-

# SwitchTabFail 的属性值

名称 类型 必备 默认值 兼容性 描述
errCode number 是 -
-
路由错误码
- 4: 框架内部异常
errSubject string 是 -
-
统一错误主题（模块）名称
data any 否 -
-
错误信息中包含的数据
cause Error 否 -
-
源错误信息，可以包含多个错误，详见SourceError
errMsg string 是 -
-

# SwitchTabComplete 的属性值

名称 类型 必备 默认值 兼容性 描述
errMsg string 是 -
-

# 返回值

类型 必备
Promise<SwitchTabSuccess> 否
名称 类型 必备 默认值 兼容性 描述
errMsg string 是 -
-

# 参见

关闭当前页面，返回上一页面或多级页面

Web 微信小程序 Android iOS HarmonyOS HarmonyOS(Vapor)
4.0 4.41 √ 4.11 4.61 5.0

# 参数

名称 类型 必填 默认值 兼容性 描述
options NavigateBackOptions 否 -
-
名称 类型 必备 默认值 兼容性 描述
delta number 否 -
返回的页面数，如果 delta 大于现有页面数，则返回到首页
animationType string 否 -
窗口关闭的动画类型
合法值 兼容性 描述
auto
自动选择动画效果
none
无动画效果
slide-out-right
横向向右侧滑出屏幕动画
slide-out-left
横向向左侧滑出屏幕动画
slide-out-top
竖向向上侧滑出屏幕动画
slide-out-bottom
竖向向下侧滑出屏幕动画
fade-out
从不透明到透明逐渐隐藏动画
zoom-in
从大逐渐缩小关闭动画
zoom-fade-in
从大逐渐缩小并且从不透明到透明逐渐隐藏关闭动画
pop-out
从右侧平移出栈动画效果
animationDuration number 否 -
窗口关闭动画的持续时间，单位为 ms
success (result: NavigateBackSuccess) => void 否 -
接口调用成功的回调函数
fail (result: NavigateBackFail) => void 否 -
接口调用失败的回调函数
complete (result: NavigateBackComplete) => void 否 -
接口调用结束的回调函数（调用成功、失败都会执行）
名称 类型 必备 默认值 兼容性 描述
errMsg string 是 -
-
名称 类型 必备 默认值 兼容性 描述
errCode number 是 -
-
路由错误码
- 4: 框架内部异常
errSubject string 是 -
-
统一错误主题（模块）名称
data any 否 -
-
错误信息中包含的数据
cause Error 否 -
-
源错误信息，可以包含多个错误，详见SourceError
errMsg string 是 -
-
名称 类型 必备 默认值 兼容性 描述
errMsg string 是 -
-

# 返回值

类型 必备
Promise<NavigateBackSuccess> 否
名称 类型 必备 默认值 兼容性 描述
errMsg string 是 -
-

# 参见

# 示例

示例为hello uni-app x alpha分支，与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见

扫码体验（手机浏览器跳转到App直达页）

示例

<template>
  <!-- #ifdef APP -->
  <scroll-view style="flex: 1">
  <!-- #endif -->
    <view>
      <page-head title="navigate"></page-head>
      <view style="flex-direction: row;">
        <switch @change="onChange"></switch>
        <view class="uni-title">是否启用共享元素动画</view>
      </view>
      <share-element :share-key="data.shareElementKey">
        <image style="width: 250px; height: 176px;" src="/static/shuijiao.jpg" mode="scaleToFill"></image>
      </share-element>
      <text style="font-size: 13px;" >注意：开启共享元素动画后仅支持slide-in-right和fade-in动画效果</text>
      <view class="uni-padding-wrap uni-common-mt uni-common-mb">
        <view class="direction-row">
          <text class="label">onLoad触发时间戳:</text>
          <text>{{ data.onLoadTime }}</text>
        </view>
        <view class="direction-row">
          <text class="label">onShow触发时间戳:</text>
          <text>{{ data.onShowTime }}</text>
        </view>
        <view class="direction-row">
          <text class="label">onReady触发时间戳:</text>
          <text>{{ data.onReadyTime }}</text>
        </view>
        <view class="direction-row">
          <text class="label">onHide触发时间戳:</text>
          <text>{{ data.onHideTime }}</text>
        </view>
        <view class="direction-row">
          <text class="label">onBackPress触发时间戳:</text>
          <text>见控制台</text>
        </view>
        <view class="direction-row">
          <text class="label">onUnload触发时间戳:</text>
          <text>见控制台</text>
        </view>
        <view class="uni-btn-v">
          <button @tap="navigateTo" class="uni-btn">
            跳转新页面，并传递数据
          </button>
          <button @tap="navigateBack" class="uni-btn">返回上一页</button>
          <button @tap="redirectTo" class="uni-btn">在当前页面打开</button>
          <button @tap="switchTab" class="uni-btn">切换到模板选项卡</button>
          <button @tap="reLaunch" class="uni-btn">
            关闭所有页面，打开首页
          </button>
          <button @tap="navigateToErrorPage" class="uni-btn">
            打开不存在的页面
          </button>
          <button v-for="(item, _) in data.animationTypeList" @tap="navigateToAnimationType(item)"
            class="uni-btn">navigateTo动画({{item}})</button>
          <button class="uni-btn" @click="goOnLoadCallAPI">测试 onLoad 调用 API</button>
        </view>
      </view>
    </view>
  <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>

<script setup lang="uts">
  import { state, setLifeCycleNum } from '@/store/index.uts'
  type AnimationType = "slide-in-right" | "slide-in-left" | "slide-in-top" | "slide-in-bottom" | "pop-in" | "fade-in" | "zoom-out" | "zoom-fade-out" | "none" | "auto"

  type DataType = {
    onLoadTime: number;
    onShowTime: number;
    onReadyTime: number;
    onHideTime: number;
    shareElementKey: string;
    animationTypeList: string[];
  }

  const data = reactive({
    onLoadTime: 0,
    onShowTime: 0,
    onReadyTime: 0,
    onHideTime: 0,
    shareElementKey: "",
    animationTypeList: [
      'slide-in-right',
      'slide-in-left',
      'slide-in-top',
      'slide-in-bottom',
      'pop-in',
      'fade-in',
      'zoom-out',
      'zoom-fade-out',
      'none'
    ]
  } as DataType)
  onLoad(() => {
    data.onLoadTime = Date.now()
    console.log('onLoad', data.onLoadTime)
  })

  onPageShow(() => {
    data.onShowTime = Date.now()
    console.log('onShow', data.onShowTime)
  })

  onReady(() => {
    data.onReadyTime = Date.now()
    console.log('onReady', data.onReadyTime)
  })

  onPageHide(() => {
    data.onHideTime = Date.now()
    console.log('onHide', data.onHideTime)
  })

  onBackPress((options : OnBackPressOptions) : boolean | null => {
    console.log('onBackPress', Date.now())
    console.log('onBackPress from', options.from)
    return null
  })

  onUnload(() => {
    console.log('onUnload', Date.now())
  })
  const reLaunch = () => {
    uni.reLaunch({
      url: '/pages/tabBar/component',
      success(result) {
        console.log('reLaunch success', result.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
      fail(error) {
        console.log('reLaunch fail', error.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum - 1)
      },
      complete(result) {
        console.log('reLaunch complete', result.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
    })
  }

  const navigateTo = () => {
    uni.navigateTo({
      url: '/pages/API/navigator/new-page/new-page-1?data=Hello',
      success(result) {
        console.log('navigateTo success', result.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
      fail(error) {
        console.log('navigateTo fail', error.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum - 1)
      },
      complete(result) {
        console.log('navigateTo complete', result.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
    })
  }

  const navigateToAnimationType = (animationType : AnimationType) => {
    uni.navigateTo({
      url: '/pages/API/navigator/new-page/new-page-1?data=Hello',
      animationType: animationType,
      success(result) {
        console.log('navigateTo success', result.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
      fail(error) {
        console.log('navigateTo fail', error.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum - 1)
      },
      complete(result) {
        console.log('navigateTo complete', result.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
    })
  }

  const navigateToErrorPage = () => {
    uni.navigateTo({
      url: '/pages/error-page/error-page',
      success(result) {
        console.log('navigateTo success', result.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum - 1)
      },
      fail(error) {
        console.log('navigateTo fail', error.errMsg)
        uni.showToast({
          title: error.errMsg,
          icon: 'none',
        })
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
      complete(result) {
        console.log('navigateTo complete', result.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
    })
  }

  const navigateToDebounce = () => {
    uni.navigateTo({
      url: '/pages/API/navigator/new-page/new-page-1?data=debounce',
      success(result) {
        console.log('navigateTo success', result.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
      fail(error) {
        console.log('navigateTo fail', error.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum - 1)
      },
      complete(result) {
        console.log('navigateTo complete', result.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
    })
    uni.navigateTo({
      url: '/pages/API/navigator/new-page/new-page-1?data=debounce',
      success(result) {
        console.log('navigateTo success', result.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum - 1)
      },
      fail(error) {
        console.log('navigateTo fail', error.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
      complete(result) {
        console.log('navigateTo complete', result.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
    })
  }

  // 自动化测试
  const navigateToRelativePath1 = () => {
    uni.navigateTo({
      url: 'new-page/new-page-1?data=new-page/new-page-1',
      success() {
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
      fail() {
        setLifeCycleNum(state.lifeCycleNum - 1)
      },
      complete() {
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
    })
  }

  // 自动化测试
  const navigateToRelativePath2 = () => {
    uni.navigateTo({
      url: './new-page/new-page-1?data=./new-page/new-page-1',
      success() {
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
      fail() {
        setLifeCycleNum(state.lifeCycleNum - 1)
      },
      complete() {
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
    })
  }

  // 自动化测试
  const navigateToRelativePath3 = () => {
    uni.navigateTo({
      url: '../navigator/new-page/new-page-1?data=../navigator/new-page/new-page-1',
      success() {
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
      fail() {
        setLifeCycleNum(state.lifeCycleNum - 1)
      },
      complete() {
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
    })
  }

  const navigateBack = () => {
    uni.navigateBack({
      success(result) {
        console.log('navigateBack success', result.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
      fail(error) {
        console.log('navigateBack fail', error.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum - 1)
      },
      complete(result) {
        console.log('navigateBack complete', result.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
    })
  }

  const navigateBackWithDelta1 = () => {
    uni.navigateTo({
      url: '/pages/API/navigator/new-page/new-page-1',
      success() {
        uni.navigateBack({
          delta: 1,
          success(result) {
            console.log('navigateBack success', result.errMsg)
            // 自动化测试
            setLifeCycleNum(state.lifeCycleNum + 1)
          },
          fail(error) {
            console.log('navigateBack fail', error.errMsg)
            // 自动化测试
            setLifeCycleNum(state.lifeCycleNum - 1)
          },
          complete(result) {
            console.log('navigateBack complete', result.errMsg)
            // 自动化测试
            setLifeCycleNum(state.lifeCycleNum + 1)
          },
        })
      },
    })
  }

  const navigateBackWithDelta100 = () => {
    uni.navigateTo({
      url: '/pages/API/navigator/new-page/new-page-1',
      success() {
        uni.navigateBack({
          delta: 100,
          success(result) {
            console.log('navigateBack success', result.errMsg)
            // 自动化测试
            setLifeCycleNum(state.lifeCycleNum + 1)
          },
          fail(error) {
            console.log('navigateBack fail', error.errMsg)
            // 自动化测试
            setLifeCycleNum(state.lifeCycleNum - 1)
          },
          complete(result) {
            console.log('navigateBack complete', result.errMsg)
            // 自动化测试
            setLifeCycleNum(state.lifeCycleNum + 1)
          },
        })
      },
    })
  }

  const redirectTo = () => {
    uni.redirectTo({
      url: '/pages/API/navigator/new-page/new-page-1?data=Hello',
      success(result) {
        console.log('redirectTo success', result.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
      fail(error) {
        console.log('redirectTo fail', error.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum - 1)
      },
      complete(result) {
        console.log('redirectTo complete', result.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
    })
  }

  const switchTab = () => {
    uni.switchTab({
      url: '/pages/tabBar/template',
      success(result) {
        console.log('switchTab success', result.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
      fail(error) {
        console.log('switchTab fail', error.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum - 1)
      },
      complete(result) {
        console.log('switchTab complete', result.errMsg)
        // 自动化测试
        setLifeCycleNum(state.lifeCycleNum + 1)
      },
    })
  }

  // 自动化测试
  const getLifeCycleNum = () : number => {
    return state.lifeCycleNum
  }

  // 自动化测试
  const setLifeCycleNumWrapper = (num : number) => {
    setLifeCycleNum(num)
  }

  const onChange = (event: UniSwitchChangeEvent) => {
    if(event.detail.value) {
      data.shareElementKey = "test-share-element-key"
    } else {
      data.shareElementKey = ""
    }
  }

  const goOnLoadCallAPI = () => {
    uni.navigateTo({
      url: '/pages/API/navigator/new-page/onLoad-call-api'
    })
  }

</script>

<style>
  .direction-row {
    flex-direction: row;
  }

  .label {
    width: 190px;
  }
</style>

# 通用类型

# GeneralCallbackResult

名称 类型 必备 默认值 兼容性 描述
errMsg string 是 -
错误信息

# 页面跳转与参数传递

A页面跳转到B页面时，有两种方式给B页面传递信息：

  1. A页面跳转时，B页面的URL中通过?param1=param1value&param2=param2value方式传递，然后B页面在Onload里接收参数。详见页面onLoad生命周期
  2. 通过eventbus，详见uni.$on、uni.$emit等API

# Bug & Tips

  • navigateTo, redirectTo 只能打开非 tabBar 页面。
  • switchTab 只能打开 tabBar 页面。
  • reLaunch 可以打开任意页面。
  • 页面底部的 tabBar 由页面决定，即只要是定义为 tabBar 的页面，底部都有 tabBar。
  • 不能在首页 onReady 之前进行页面跳转。
本页导读
uni.navigateTo(options)
navigateTo 兼容性
参数
NavigateToSuccess 的属性值
NavigateToFail 的属性值
NavigateToComplete 的属性值
返回值
参见
uni.redirectTo(options)
redirectTo 兼容性
参数
RedirectToSuccess 的属性值
RedirectToFail 的属性值
RedirectToComplete 的属性值
返回值
参见
uni.reLaunch(options)
reLaunch 兼容性
参数
ReLaunchSuccess 的属性值
ReLaunchFail 的属性值
ReLaunchComplete 的属性值
返回值
参见
uni.switchTab(options)
switchTab 兼容性
参数
SwitchTabSuccess 的属性值
SwitchTabFail 的属性值
SwitchTabComplete 的属性值
返回值
参见
uni.navigateBack(options?)
navigateBack 兼容性
参数
NavigateBackSuccess 的属性值
NavigateBackFail 的属性值
NavigateBackComplete 的属性值
返回值
参见
示例
通用类型
GeneralCallbackResult
页面跳转与参数传递
Bug & Tips