目录

页面路由

接口声明

无需声明

导入模块

在调用接口页面的<script>部分增加如下配置。

import router from '@system.router'

或

var router = require("@system.router")

使用限制

限制条件

说明

适用终端

手机、平板、智慧屏、车机

适用区域

全球

接口定义

接口

描述

router.push(OBJECT)

跳转到设置的页面。

router.replace(OBJECT)

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

router.back(OBJECT)

返回上一页面。

router.clear()

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

router.getLength()

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

router.getPages()

返回当前页面栈列表。

router.getState()

获取当前页面状态。

[h2]router.push(OBJECT)

描述

跳转到设置的页面。

页面跳转传递的数据可能被其他应用获取,建议不要传递安全敏感度较高的数据,禁止在后台调用。

OBJECT参数

OBJECT参数总大小不能超过128KB。

参数

类型

是否必填

说明

uri

string

是

要跳转到的uri,可以是下面的格式:

  • 包含scheme的完整uri;目前支持的scheme有tel,sms,mailto和hap(1035+),例如tel:10086,mailto:abc@gmail.com,hap://app/com.company.app/index?param1=value1
  • 以"/"开头的应用内页面的路径;例:/about
  • 以非"/"开头的应用内页面的名称;例:About
  • 特殊的,如果uri的值是"/",则跳转到path为"/"的页,没有则跳转到首页
  • hap://settings/permission_manager,跳转到快应用的权限管理界面(1035+)
  • hap://settings/permissions,跳转到快应用的权限管理页面(1107+)
  • hap://settings/location_source_manager,跳转到手机系统的位置管理界面(1035+)
  • hap://settings/5g,跳转到5G开关设置页面(1080+)
  • hap://settings/feedback,跳转到统一菜单下的“问题与建议”页面(1103+)
    注意:

    在加载器上调试无效,上架后生效。

支持包含scheme的完整uri。对于带有scheme的uri,处理流程如下:

  1. 查找app下所有page的filter设置来选择合适的page处理请求(参见“manifest文件”)
  2. 如果没有合适的page能够处理请求,会使用默认策略来处理请求。目前默认策略支持对http、https、internal这几种scheme的处理
  3. 如果默认策略也不能处理请求,会尝试使用系统中的应用来处理请求
  4. 如果没有系统应用可以处理请求,会抛弃请求

默认策略的处理逻辑:

  1. 如果scheme是http/https,会用内置的web页面打开网页,不支持在卡片中打开网页
  2. 如果scheme是internal(参见“文件组织”),会根据uri的文件扩展名来确定文件类型,再调用系统中的应用打开文件

params

object

否

跳转时需要传递的数据。参数可以在页面中通过this.param1的方式使用,param1为json中的参数名,param1对应的值会统一转换为String类型。

params说明:

参数

类型

是否必填

说明

___PARAM_LAUNCH_FLAG___(1050+)

string

否

快应用启动参数,目前仅支持"clearTask",在启动目标页面时会清除除此页面外的其他页面。详细请参见“页面启动模式”。

___PARAM_LAUNCH_NATIVE_FLAG___(1070+)

string

否

在打开原生应用页面时设置flag。默认值为newTask。可以根据需要设置多个flag,多个flag之间用 | 分割,例如newTask|clearTask、newTask|clearTop。

  • newTask:引擎默认行为,与打开activity时携带 Intent.FLAG_ACTIVITY_NEW_TASK 参数行为保持一致。
  • standard:使用activity打开的默认行为,将新打开的页面入栈到快应用的栈里,点击返回后仍然在快应用中。与打开activity时不携带flag保持一致。
  • broughtToFront:与打开activity时携带 Intent. FLAG_ACTIVITY_BROUGHT_TO_FRONT 参数行为保持一致。
  • clearTask:与打开activity时携带 Intent. FLAG_ACTIVITY_CLEAR_TASK 参数行为保持一致。
  • singleTop:与打开activity时携带 Intent. FLAG_ACTIVITY_SINGLE_TOP 参数行为保持一致。
  • clearTop:与打开activity时携带 Intent.FLAG_ACTIVITY_CLEAR_TOP 参数行为保持一致。

___PARAM_PAGE_ANIMATION___(1070+)

object

否

页面跳转时的动画类型。

说明:

华为暂不支持,设置后无效果。

示例代码

// launch phone app
router.push({
  uri: 'tel:10086'
});
// open page by path
router.push({
  uri: '/about',
  params: {testId:'1'}
});
// open page by name
router.push({
  uri: 'About',
  params: {testId:'1'}
});
// send sms
router.push({
  uri: 'sms:',
  params: {body:'test send message'}
});

新增以下用法:

// open web page
router.push({
  uri: 'https://www.example.com'
});
// install apk
router.push({
  uri: 'internal://cache/example.apk'
});

拉起百度和高德地图的用法:

import pkg from '@system.package';
// 地图导航
navMap(address){
    console.log("nav map");
    if (address == undefined) {
        return;
    }
    // 转换地址
    var special = "华为松山湖基地 F区";
    if (address.indexOf(special)>=0) {
        address = address.substr(0, address.indexOf(special)+ special.length);
    }
    special = "华为松山湖基地 L区";
    if (address.indexOf(special)>=0) {
        address = address.substr(0, address.indexOf(special)+ special.length);
    }
    special = "华为松山湖基地 K区";
    if (address.indexOf(special)>=0) {
        address = address.substr(0, address.indexOf(special)+ special.length);
    }
    special = "华为松山湖基地F区";
    if (address.indexOf(special)>=0) {
        address = address.substr(0, address.indexOf(special)+ special.length);
    }
    special = "华为松山湖基地L区";
    if (address.indexOf(special)>=0) {
        address = address.substr(0, address.indexOf(special)+ special.length);
    }
    special = "华为松山湖基地K区";
    if (address.indexOf(special)>=0) {
        address = address.substr(0, address.indexOf(special)+ special.length);
    }
    special = "华为溪流背坡村F区";
    if (address.indexOf(special)>=0) {
        address = address.substr(0, address.indexOf(special)+ special.length);
    }
    special = "华为溪流背坡村L区";
    if (address.indexOf(special)>=0) {
        address = address.substr(0, address.indexOf(special)+ special.length);
    }
    var listNavApp = {baidu:false,gaode:false};
    // 异步检测百度地图
    this.checkBaidu(listNavApp, address);
    },
    // 异步检测百度地图
    checkBaidu(navAppObj, address){
        var that = this;
        pkg.hasInstalled({
            package: 'com.baidu.BaiduMap',
            success: function (data) {
                if (data.result) {
                    navAppObj.baidu = true;
                }
                that.checkGaode(navAppObj, address);
            },
            fail: function (data, code) {
                that.checkGaode(navAppObj, address);
            }
        });
    },
    // 异步检测高德地图
    checkGaode(navAppObj, address){
        var that = this;
        pkg.hasInstalled({
            package: 'com.autonavi.minimap',
            success: function (data) {
                if (data.result) {
                    navAppObj.gaode = true;
                }
                that.onCheckEnd(navAppObj, address);
            },
            fail: function (data, code) {
                that.onCheckEnd(navAppObj, address);
            }
        });
    },
    // 弹出导航选择框
    onCheckEnd(navAppObj, address){
    console.log('listNavApp = ' + JSON.stringify(navAppObj));
    var listNavApp=[];
    if(navAppObj.baidu) {
        listNavApp = listNavApp.concat("百度导航");
    }
    if(navAppObj.gaode) {
        listNavApp = listNavApp.concat("高德导航");
    }
    if (listNavApp.length == 0) {
        return;
    }
    // show nav list
    prompt.showContextMenu({
        itemList: listNavApp,
        success: function (data) {
            // find map url
            var mapUrl;
            if (listNavApp[data.index] == '百度导航') {
                mapUrl = 'baidumap://map/direction?destination='+address+'&coord_type=bd09ll&mode=driving&src=com.huawei.fastapp';
            } else if (listNavApp[data.index] == '高德导航'){
                mapUrl = 'amapuri://route/plan?sourceApplication=amap&dname='+address+'&dev=0&style=0';
            } else {
                return;
            }
        // start nav app
        router.push({
            uri: mapUrl
        })
    },
    cancel: function () {
        console.log('user cancel');
    }
})
}

1050+新增以下用法:

// `1050+` Open page with 'clearTask' flag
router.push({
  uri: '/about',
params: {___PARAM_LAUNCH_FLAG___: 'clearTask'}
});

1070+新增以下用法:

router.push({
  uri: uri,  // 此处的uri是原生应用activity的deeplink
  params: {___PARAM_LAUNCH_NATIVE_FLAG___: 'standard'}
});
router.push({
  uri: '/',
  params: {
    ___PARAM_PAGE_ANIMATION___: {
      openEnter: 'slide',
      closeEnter: 'none',
      openExit: 'slide',
      closeExit: 'none'
    }
  }
});

[h2]router.replace(OBJECT)

描述

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

页面跳转传递的数据可能被其他应用获取,建议不要传递安全敏感度较高的数据。

OBJECT参数

参数

类型

是否必填

说明

uri

string

是

要跳转到的uri,可以是下面的格式:

  1. 以"/"开头的应用内页面的路径;例:/about
  2. 以非"/"开头的应用内页面的名称;例:About
  3. 特殊的,如果uri的值是"/",则跳转到path为"/"的页,没有则跳转到首页

params

object

否

跳转时需要传递的数据,参数可以在页面中通过this.param1的方式使用,param1为json中的参数名,param1对应的值会统一转换为String类型。

示例代码

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

[h2]router.back(OBJECT)

描述

返回上一页面。

OBJECT参数(1020+)

如果不传入参数,返回上一个页面,效果类似按手机返回键;传入参数请参见下表中的说明。

参数

类型

是否必填

说明

path

string

否

返回指定path的界面,可以是以下几种取值:

  1. 不传该参数,如果 delta 设置了,则按 delta 设置的页面数层层返回;delta 未设置,和默认router.back()效果一样,返回上一页面。
  2. 以"/"开头的应用内的页面,则返回到指定应用界面,例如:/about。如果设置了多个path,则返回到栈顶的path对应页面。
  3. 特殊的,如果 path 设置的页面在应用内不存在,则返回上一个页面。
注意:

path不能设置返回到其他应用的页面。

delta

number

否

返回的页面数(华为扩展接口,非厂商联盟规范,非华为应用请勿使用),缺省为1,如果 delta 大于现有页面数,则返回到首页,假如同时填写了path和delta字段,则以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'
})

[h2]router.clear()

描述

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

示例代码

router.clear()

[h2]router.getLength()

描述

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

返回值

参数

说明

string

页面数量

示例代码

var length= router.getLength()
console.log("pages' length = "length);

[h2]router.getPages()(1070+)

描述

返回当前页面栈列表。

返回值

参数

说明

array

页面栈列表是一个数组,数组每一项是一个对象。

Object参数列表

参数

类型

说明

name

string

页面名称。

path

string

页面路径。

示例代码

// 调用getPages方法
let pages = router.getPages()
// 由于获得的值是一个JSON数组,所以直接打印是打印不出来的,可以使用下面的方法来打印
console.log("tag", printJSONArray(router.getPages()));
function printJSONArray(array) {
    let result = ""
    const suffix = ", "
    Array.isArray(array) && array.forEach((element, index) => {
        result = result + JSON.stringify(element) + (index === array.length-1 ? "" : ", ")
    })
    return result
}

[h2]router.getState()

描述

获取当前页面状态。

返回值

参数

类型

说明

index

string

当前页面在页面栈中的位置。

注意:

请勿对index的类型进行强校验。

name

string

当前页面的名称

path

string

当前页面的路径

示例代码

var page = router.getState()
console.log("page index = "+page.index);
console.log("page name = "+page.name);
console.log("page path = "+page.path);

Demo

<template>
  <div class="container">
    <div class="item-container">
      <input type="button" class="btn"  onclick="routeHome" value="routeHome" />
      <input type="button" class="btn"  onclick="routeBack" value="routeBack" />
      <input type="button" class="btn"  onclick="routeReplace" value="routeReplace" />
      <input type="button" class="btn"  onclick="routeDetail" value="routeDetail" />
      <input type="button" class="btn"  onclick="routeDetailObject" value="routeDetailObject" />
      <input type="button" class="btn"  onclick="routeTel" value="route to Tel " />
      <input type="button" class="btn"  onclick="routeMail" value="router to Mail" />
      <input type="button" class="btn"  onclick="routeSms" value="router to Sms" />
      <input type="button" class="btn"  onclick="routeMsg" value="router to Msg" />
      <input type="button" class="btn"  onclick="routeApp" value="router to app" />
      <input type="button" class="btn"  onclick="routeLocation" value="route to Location page"/>
      <input type="button" class="btn"  onclick="routeWlan" value="router to permission_manager"/>
      <input type="button" class="btn"  onclick="route5g" value="route to 5g page"/>
      <input type="button" class="btn"  onclick="routeBluetooth" value="open web page"/>
      <input type="button" class="btn"  onclick="routeAnimate" value="route Animate"/>
      <input type="button" class="btn"  onclick="routeAnimateNone" value="route AnimateNone"/>
      <input type="button" class="btn" onclick="routerclear" value="Clears all historical pages" />
      <input type="button" class="btn" onclick="routerlength" value="Obtains the number of pages" />
      <input type="button" class="btn" onclick="routerpages" value="Page stack list" />
      <text if="{{getpagesinfo}}">{{getpagesinfo}}</text>
      <input type="button" class="btn" onclick="routerstates" value="Current page status" />
      <text if="{{getpagestatus}}">{{getpagestatus}}</text>
    </div>
  </div>
</template>
<style>
    .container {
    flex-direction: column;
    justify-content: center;
    align-items: center;
  }
  .item-container{
    margin-top: 50px;
    margin-right: 30px;
    margin-left: 30px;
    flex-direction: column;
  }
   .btn { 
    height: 80px;
    text-align: center;
    border-radius: 5px;
    margin-right: 60px;
    margin-left: 60px;
    margin-bottom: 50px;
    color: #ffffff;
    font-size: 30px;
    background-color: #0faeff;
  }
</style>
<script>
  import router from '@system.router'
  import prompt from '@system.prompt'

  export default {
    private: {
      show: true,
      getpagesinfo:'',
      getpagestatus:''
    },
    onInit () {
      this.$page.setTitleBar({text: ' Page Router'})
    },
    routeHome () {
      router.push({
        uri: '/'
      })
    },
    routeBack () {
      router.back()
    },
    routeReplace () {
      router.replace({
        uri: '/'
      })
    },
    routeDetail () {
      router.push({
        uri: '/',
        params: {pageInfo: '我是上个页面传递来的数据'}
      })
    },
    routeDetailObject () {
      // params传递的数据为对象时,会被序列化为字符串,可以通过JSON.parse()反序列化
      router.push({
        uri: '',
        params: {
          pageInfoObject: {
            msg: '我是上个页面传递来的数据对象'
          }
        }
      })
    },
    // 跳转到指定快应用,以移动惠福利为例
    routeApp () {
      router.push({
        uri: 'hap://app/com.ahyd.ydhfl/'
      })
    },
    // 跳转到电话
    routeTel () {
      router.push({
        uri: 'tel:10086'
      })
    },
    // 跳转到邮件
    routeMail () {
      router.push({
        uri: 'mailto:xxx@163.com'
      })
    },
    // 跳转到短信发送(指定联系人)
    routeSms () {
      router.push({
        uri: 'sms:10086'
      })
    },
    // 跳转到短信发送(带内容)
    routeMsg () {
      router.push({
        uri: 'sms:',
        params: {
          body:"hello world"
        }
      })
    },
    routeLocation () {
      router.push({
        uri: 'hap://settings/location_source_manager'
      })
    },
    routeWlan () {
      router.push({
        uri: 'hap://settings/permission_manager'
      })
    },
    routeBluetooth () {
      router.push({
        uri: 'https://developer.huawei.com/consumer/cn/doc/development/quickApp-References/quickapp-api-router-0000001073326953#section19418113011289'
      })
    },
    route5g () {
      router.push({
        uri: 'hap://settings/5g'
      })
    },
    routeAnimate () {
      //华为暂不支持,设置后无效果
      router.push({
        uri: '/',
        params: {
          ___PARAM_PAGE_ANIMATION___: {
            openEnter:`slide`,
            closeEnter:`slide`,
            openExit:`slide`,
            closeExit:`slide`
          }
        }
      })
    },
    routeAnimateNone () {
      //华为暂不支持,设置后无效果
      router.push({
        uri: '/',
        params: {
          ___PARAM_PAGE_ANIMATION___: {
            openEnter: `none`,
            closeEnter:`none`,
            openExit:`none`,
            closeExit:`none`
          }
        }
      })
    },
    routerclear () {
      router.clear()
    },
        routerlength() {
          var length = router.getLength();
          console.log("pages length = "+length);
    },
    routerpages() {
      // 调用getPages方法
    //  let pages = router.getPages();
      this.getpagesinfo = printJSONArray(router.getPages());
      // 由于获得的值是一个JSON数组,所以直接打印是打印不出来的,可以使用下面的方法来打印
      console.log("tag", printJSONArray(router.getPages()));
      function printJSONArray(array) {
          let result = ""
          const suffix = ", "
          Array.isArray(array) && array.forEach((element, index) => {
          result = result + JSON.stringify(element) + (index === array.length - 1 ? "" : ", ")
            })
          return result
        }
    },
    routerstates () {
      var page = router.getState()
      this.getpagestatus = router.getState()
      console.log("page index = "+page.index);
      console.log("page name = "+page.name);
      console.log("page path = "+page.path);
    }
  }
</script>

效果图如下:

版本更新说明

版本

发布日期

描述

1107

2023-08-31

router.push接口新增hap://settings/permissions,跳转到快应用的权限管理页面。

1103

2022-12-26

router.push接口新增hap://settings/feedback,跳转到统一菜单下的“问题与建议”页面。

1080

2021-12-28

router.push接口新增hap://settings/5g,通过router.push跳转到5G开关设置页面。

1070

2020-05-19

  • 新增getPages方法,用于获取当前页面栈列表。
  • router.push的params新增参数___PARAM_LAUNCH_NATIVE_FLAG___,用于在打开原生应用页面时添加Flag。
  • 新增参数___PARAM_PAGE_ANIMATION___,用于控制页面跳转时的动画类型。

1050

2019-09-20

router.push 新增快应用启动参数 PARAM_LAUNCH_FLAG。

1040

2019-06-24

router.push的uri参数支持设置跳转另一个快应用页面、快应用的权限管理界面和手机系统的位置管理界面。

1020

2018-06-20

router.back 新增path和delta参数,开发者调用一次接口可以返回多个页面。

相关链接

[h2]FAQ

[h2]案例