教程 框架 组件 接口 工具 其他

页面路由 router

接口声明

无需声明

导入模块

import router from '@system.router'const router = require('@system.router')

接口定义

router.push(OBJECT)

跳转到应用内的某个页面,页面栈层数没有限制

注意:不能跳到 tabBar 页面

参数:

参数类型必填说明
uriString要跳转到的 uri,可以是下面的格式:
  1. 包含 schema 的完整 uri;目前支持的 schema 有 tel,sms 和 mailto,例如 tel:10086。
  2. 以‘/’开头的应用内页面的路径;例:/about。
  3. 以非‘/’开头的应用内页面的名称;例:About。
  4. 特殊的,如果 uri 的值是"/",则跳转到 path 为"/"的页,没有则跳转到首页
支持包含 schema 的完整 uri。对于带有 schema 的 uri,处理流程如下:
  1. 查找 app 下所有 page 的 filter 设置来选择合适的 page 处理请求(参见manifest 文件
  2. 如果没有合适的 page 能够处理请求,会使用默认策略来处理请求。目前默认策略支持对 http、https、internal 这几种 schema 的处理
  3. 如果默认策略也不能处理请求,会尝试使用系统中的应用来处理请求
  4. 如果没有系统应用可以处理请求,会抛弃请求
默认策略的处理逻辑:
  1. 如果 schema 是 http/https,会用内置的 web 页面打开网页
  2. 如果 schema 是 internal(参见文件组织),会根据 uri 的文件扩展名来确定文件类型,再调用系统中的应用打开文件
  3. 如果 schema 是 hap(参见hap 链接),会跳转到 hap 链接所支持的类型
paramsObject跳转时需要传递的数据,跳转到短信发送页面时,可以通过body1040+)插入短信内容;跳转到快应用页面时,参数可以在目标页面中通过this.param1的方式使用,param1 为 json 中的参数名,param1 对应的值会统一转换为 String 类型。使用this.param1变量时,需要在目标页面中在 public(应用外传参)或 protected (应用内传参)下定义 key 名相同的属性。除开发者自定义的参数外,快应用官方提供了部分供选参数,参数释义如下
params 参数:
参数类型必填说明
body1040+String跳转时短信发送页面时携带的短信内容。
___PARAM_LAUNCH_FLAG___1050+String快应用启动参数,目前仅支持"clearTask",在启动目标页面时会清除除此页面外的其他页面。详见页面启动模式
___PARAM_PAGE_ANIMATION___1070+Object页面跳转时动画类型
___PARAM_PAGE_ANIMATION___ 参数:
页面动作动画类型必填说明
openEnterString打开进入当前页时当前页动画,可选值 slide, none,默认为 slide
closeEnterString关闭返回当前页时当前页动画,可选值 slide, none,默认为 slide
openExitString打开下一页,退出当前页时当前页动画,可选值 slide, none,默认为 slide
closeExitString返回上一页,退出当前页时当前页动画,可选值 slide, none,默认为 slide

slide 模式在各动作下的动画变化详情如下:

页面动作动画变化动画时长
openEnterx from 100%~0300ms
closeEnterx from -25%~0, alpha 0.6~1.0300ms
openExitx from 0~-25%, alpha 1.0~0.6300ms
closeExitx from 0~100%300ms

示例:

  • 唤醒电话
    router.push({
      uri: 'tel:10086'
    })
    
  • 发送短信

    router.push({
      uri: 'sms:10086',
      params: {
        body: 'message'
      }
    })
    
  • 应用内切换页面

    • path 切换
      router.push({
        uri: '/about',
        params: {
          testId: '1'
        }
      })
      
    • name 切换
      // open page by name
      router.push({
        uri: 'About',
        params: {
          testId: '1'
        }
      })
      
    • 切换页面并清除其他页面 1050 +
      router.push({
        uri: '/about',
        params: {
          ___PARAM_LAUNCH_FLAG___: 'clearTask'
        }
      })
      
  • 打开网页

    router.push({
      uri: 'http://www.example.com'
    })
    
  • 打开原生应用

    router.push({
      uri: 'internal://cache/example.apk'
    })
    
  • 打开另一个快应用

    router.push({
      uri: 'hap://app/com.example.quickapp/page?key=value'
    })
    
  • 打开 wifi 设置页面 1040 +

    router.push({
      uri: 'hap://settings/wlan_manager'
    })
    
  • 配置跳转动画模式 1070 +

    router.push({
      uri: '/about',
      params: {
        ___PARAM_PAGE_ANIMATION___: {
          openEnter: `none`,
          closeEnter: `slide`,
          openExit: `slide`,
          closeExit: `slide`
        }
      }
    })
    

router.replace(OBJECT)

跳转到应用内的某个页面,当前页面无法返回

注意:不能跳到 tabBar 页面

参数:

参数类型必填说明
uriString要跳转到的 uri,可以是下面的格式:
  1. 以"/"开头的应用内页面的路径;例:/about。
  2. 以非"/"开头的应用内页面的名称;例:About。
  3. 特殊的,如果 uri 的值是"/",则跳转到 path 为"/"的页,没有则跳转到首页
paramsObject跳转时需要传递的数据,参数可以在目标页面中通过this.param1的方式使用,param1 为 json 中的参数名,param1 对应的值会统一转换为 String 类型。使用this.param1变量时,需要在目标页面中在 public(应用外传参)或 protected (应用内传参)下定义 key 名相同的属性

示例:

router.replace({
  uri: '/test',
  params: {
    testId: '1'
  }
})

router.switchTab(OBJECT) 1110+

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

  • 注:oppo侧暂不支持

参数:

参数类型必填说明
uriString要跳转到的 uri,是以"/"开头的应用内页面的路径;例:/about。注意页面路径必须是配置文件中已经定义存在的 tabBar 页面路径
paramsObject跳转时需要传递的数据,参数可以在目标页面中通过this.param1的方式使用,param1 为 json 中的参数名,param1 对应的值会统一转换为 String 类型。使用this.param1变量时,需要在目标页面中在 public(应用外传参)或 protected (应用内传参)下定义 key 名相同的属性

示例:

router.switchTab({
  uri: '/test',
  params: {
    testId: '1'
  }
})

router.back(OBJECT)

返回指定页面

参数:

参数类型必填说明
path 1020+String返回目标页面的路径,可以是以下几种取值:
  1. 不传该参数,返回上一页面
  2. 以"/"开头的应用内已打开页面的路径;例:/about。
  3. 特殊的,如果 path 的值是"/",则跳转到页面名称为"/"的页,没有则跳转到首页
注意点:
  1. path 需要是以"/"开头的当前应用已经打开的页面路径,否则均视为无效参数,返回上一页面
  2. 若根据 path 未匹配到已经打开的页面,返回上一页面
  3. 若根据 path 参数匹配到多个页面,返回至最后打开的页面

示例:

// A页面, open page by name
router.push({
  uri: 'B'
})
// B页面, open page by name
router.push({
  uri: 'C'
})
// C页面, open page by name
router.push({
  uri: 'D'
})
// D页面, open page by name
router.push({
  uri: 'E'
})
// E页面不传入页面路径,返回至D页面
router.back()
// D页面不传入页面名称,返回至C页面
router.back()
// C页面传入页面路径,返回至A页面
router.back({
  path: '/A'
})

router.clear()

清空所有历史页面记录,仅保留当前页面

参数:

示例:

router.clear()

router.getLength()

获取当前页面栈的页面数量

返回值:

类型说明
Number页面数量

示例:

var length = router.getLength()
console.log(`page's length = ${length}`)

router.getState()

获取当前页面状态

返回参数:

参数名类型说明
indexNumber当前页面在页面栈中的位置
nameString当前页面的名称
pathString当前页面的路径

示例:

var page = router.getState()
console.log(`page index = ${page.index}`)
console.log(`page name = ${page.name}`)
console.log(`page path = ${page.path}`)

router.getPages()1070+

获取当前页面栈列表

返回值:

类型说明
Array页面栈列表。数组每一项都为 Object 类型。

数组每一项构成:

字段类型说明
nameString页面的名称
pathString页面的路径

示例:

var stacks = router.getPages()
console.log('栈底页面名称为:', stacks[0].name) // 如 list、detail 等
console.log('栈底页面路径为:', stacks[0].path) // 如 /list、/detail、/home/preview

后台运行限制

禁止使用。 后台运行详细用法参见后台运行 脚本

条匹配 "" 的结果

    没有搜索到与 "" 相关的内容