# routerApi

# API域：

const router = Kreator.router;

# router.navigateTo(path, params?, callbackOptions?)

保留当前页面，跳转至指定页面，页面链接为path。

通过navigateTo方法跳转的页面，可以通过navigateBack方法返回。如果目标页面为小程序tabbar的页面，navigateTo将转换为switchTab方法进行跳转。但是理所当然——跳转后将不能通过左上角返回到上一页。

属性	类型	默认值	必填	说明
path	string / number	''	是	跳转目标页面的链接，或返回页面的层级。参数支持传入Number类型，当传入数值pos时，即为执行返回操作，与navigateBack的效果一致。 path支持参数传递，因此可以简单地将链接通过?或:拼接在字符串上传递。
params	RouteParams	{}	否	路由参数体。支持hash，url，context等不同格式。
callbackOptions	MiniProgramBaseOptions	{}	否	用于小程序端的路由执行回调函数。仅小程序端可用。

RouteParams:{
    urlQuery:{} // 拼接在path上的urlQuery参数，即是通过?开头的参数
    hashQuery:{} // 拼接在path上的hashQuery参数，即出现在hashRouter之后，以:开头的参数
    context:{} // 以内存方式传递的参数，不会出现在path上，跳转后通过getContext方法获取。仅App端可用。
    useNativeMp: boolean // 小程序环境下，是否使用原生路由跳转，默认使用
    useNativeApp: boolean // App环境下，是否使用原生路由跳转，默认使用
}

MiniProgramBaseOptions:{
    success(res):void // 跳转成功的回调
    fail(err):void // 跳转失败的回调
    complete(res):void // 跳转完成的回调。即无论失败或成功都会执行。
}

# 注意：

path允许传入number类型并不是一个bug。我们考虑到开发者的个人习惯（部分路由库是允许的，如kayak.router.go(-1)），认为应该兼容利用同一个api执行返回操作的情况。

也许你会注意到，path是允许传入完整url的，但我们仍然提供了params参数，允许开发者通过Object形式传递参数。这一举措的初衷借鉴了小程序router的设计理念，目的是尽可能照顾不同开发者的编码习惯，并且，部分场景的目标页面需要传很多参数（或者参数的值很长）。在这种情况下，通过String的形式拼接参数看起来并不便利，并且超长的url会让开发者维护时感到压力巨大。

我们将params分成三部分的原因是为了让开发者自由选择业务场景所需要的传参形式——我们曾考虑过将params做成单层级的对象，但这样做的问题是：开发者很可能面临着不知道同样的参数在web端到底是拼接在hash后，还是.html之后。又或者部分App页面必须通过context来传参时，sdk很难100%精准地解决这类问题（单纯通过url格式是不可能准确判断的）。极其极端的情况下，也许会有这样的调用方式出现：

// path与urlQuery传入了key相同的参数
router.navigateTo('pages/itemdetail/itemdetail?id=abc',{
    urlQuery:{
        id:'def'
    }
})

// 最终跳转完成的链接为pages/itemdetail/itemdetail?id=def

正常情况下是绝对不应该出现这种做法的——除非您在协助我们进行单元测试。
类似这样的情况，params中的参数会覆盖url上拼接的参数，有些类似于Object.assign方法，靠后的参数覆盖靠前的。

useNativeApp、useNativeMp是两个有些危险的功能，95%的场景下，都应该使用当前客户端的原生路由跳转。但开发者可能会需要在某些情况下利用location.href的方式跳转来实现部分功能。
最明显的一个例子是，小程序原生跳转的方式是无法让Webview中的H5页面监听到返回行为的。这会让一些依赖后续流程的功能实现变得异常困难。
当你使用这两个功能时，请务必明确你的业务场景需要这么做。

# router.redirectTo(path, params?, callbackOptions?)

重定向至指定页面。path为目标页面链接，它仅支持string类型。 params同上表中的RouteParams类型。

callbackOptions同上表中的MiniProgramBaseOptions类型。

# router.navigateBack(pos)

返回指定层级。pos必须为一正数，请绝对不要传入小于等于0的数值。

# router.switchTab(path, params?, callbackOptions?)

跳转至一为小程序tabbar上的页面。path为该页面路径。

该方法仅在小程序上生效，并且由于小程序的限制，params将被舍弃，path后拼接的参数也不会携带过去。在app与web端，sdk将自动替换为执行navigateTo方法。

params同上表中的RouteParams类型。

callbackOptions同上表中的MiniProgramBaseOptions类型。

请注意，我们不建议您手动调用switchTab方法，对于不熟悉您的业务的开发者来说，这个方法或许会令他们有些困惑不解。navigateTo方法内部已经存在判断逻辑，若目标页面为tabbar页面则会自动执行switchTab方法。除非您发现kreator没有正确地判断目标页面是否为tabbar页面，此时才需要手动调用它。同时请尽快联系我们修复该问题。

# router.relaunch(path, params?, callbackOptions?)

销毁当前全部历史记录栈，跳转至指定页面。跳转后，将不能返回上一页。

仅微信小程序可用。其他客户端下，将自动替换为执行navigateTo方法。

params同上表中的RouteParams类型。

callbackOptions同上表中的MiniProgramBaseOptions类型。

# router.getContext():object

获取跳转时传递的内存级参数。仅App端可用。
通常情况下这种方式的使用应该是比较罕见的，除非目标页面是App端原生页面，只能获取内存级参数。

我们不认为Web端使用这种方法是个好主意，一旦当前页面刷新，参数将会丢失。因此目前暂不提供Web端支持。但后续随着业务场景扩展，也许会考虑支持。

# router.setContext(context):object

设置跳转时传递的内存级参数。仅App端可用。

它的作用与跳转时在params的context字段内传参的结果是相同的。

# router.urlRequest:Object

获取当前url上的?级别参数，即拼接在.html后，通过?开头的query参数。

# router.requestParam:Object

获取当前url上的:级别参数，即拼接在hash之后，通过:开头的hashQuery参数。

url:http://i.dmall.com/?dmNeedLogin=true&dmShowCart=false/#item/view/item/item:id=2-11244-101329972

console.log(router.urlRequest) 
/* {
    dmNeedLogin:true,
    dmShowCart:false
}
*/
console.log(router.requestParam)
/* {
    id: 2-11244-101329972,
}
*/

# router.mpWebViewQuery: Object

小程序环境下，获取webview向H5在URL上透传的参数。
原本url上的参数是JSONString或加密的字符串，通过该方法可直接获取格式化后的Object对象。
非小程序环境中，它将返回一空对象。

url:http://i.dmall.com/?dmNeedLogin=true&dmShowCart=false/#item/view/item/item:id=2-11244-101329972

console.log(router.mpWebViewQuery) 
/* {}
*/
url: "http://testi.dmall.com/kayak-project/kreator/html/index.html?query=4czQ0EUOwIDRxITMDJDR5cjNyIUMDBTQxIkM2czQ4cTQ4MTQBdTQGBzQBNjNzYjM1cjN4EjMBRTOBNzN4EUNChzMyITJBNTJyITJl1WYORXZrNWa0JjMlMkMlIjMlMWOyI2NhVGOhZGN40iZyMWYtcjZyQTLxUTMk1SY0MzMjNjMjJjMlE0MlIjMl4WZr9GdyITJCdTJEdTJyITJzIjMlE0MlIjMlQWS05WYuVGVtRmMyUyQyUSM3kTMxE0MlIjMlQWafJXZk5WZ2JjMlMkMlEDM2IzNxE0MlIjMlQWafVmcvR3cyITJDJTJyITJp5Wat9VMxcjMyUSQzUiMyUCdjVmavJHUrNWYyRnMyUyQyUiMyUSbhJ3ZvJHcp5WatJjMlE0MlIjMl0mcvZGdhxGcyITJDJTJEdTJyITJpEzQyUCN5MkMlMjMxMkMlADKhJ2ZyJjMlE0MlIjMlI3bs92QhJ3ZyITJDJTJyITJpEzQyUCN5MkMlMjMxMkMlADKhJ2ZyJjMlE0MlIjMlI3bs92Qu92YpJjMlMkMlIjMlkSMDJTJ0kzQyUyMyEzQyUCMoEmYnJnMyUSQzUiMyUicvx2bDRmbvNWZzJjMlMkMlIjMlkSMDJTJ0kzQyUyMyEzQyUCMoEmYnJnMyUSQzUiMyUicvx2bD5Wah1mMyUiQ3USQzUiMyUSZtVGa0JjMlMkMlIjMlQjM2gzN3MDOzkzM2ETM2ITM5IURxY0QzEzMGVjRyADMwADOxUjM2kjQxEUODJjMlE0MlIjMlQWa1VnMyUyQyUSOyEjMyUzN5E0MlIjMlQWSyV2c1JjMlMkMlIjMl8WLTRDexI2Y4sERxQ1QyNEapNldtdVNHhFUj9mMyUSQzUiMyUCZJ5WZw9mMyUyQyUCM0E0MlIjMlU2YyV3bzJjMlMkMlIjMlIjMlE0MlIjMlQWSul2ZvxEdlt2YpRnMyUyQyUiMyUyQGZjRGRUMGNTMElDO2EEMwE0MBhzM3cjRDJDR0gDO1QDRGZzN3YTR5QjM1kzQFJDOGV0MzEzQ0YTO1QjQyYUQERDO0MEMyADM1IzQBBTR2IER5UjMyE0Q3czMxYkN2YERBNDR5UkM0UzNzkDNBFTR1UENBlTQGFTO1IzNyMDM1MTNwgTN3ETN1YjN3IDRDNEOxEDRyEEO3cDR2UjQGJzQCRTN5UjM1UkNxAjR4UDMzgzQwAjM3AzNCVUNDZER"

console.log(router.mpWebViewQuery)
/* {
    dmTenantId: "3"
    openId: "ocPXG5WmvSihCrCT1DK8cb1x4S-o"
    platform: "miniprogram"
    source: 40
    store_id: 172601
    theme: {
        mainColor: "rgba(0,123,94,1)",
        secondColor: "rgba(0,123,94,1)",
        iconColor: "rgba(0,123,94,1)",
        graColor: "rgba(0,123,94,1)"
    }
    ticketLoginId: ""
    ticketName: "54A352A560ECC2AF4BFFFBFC3E673EBC1F0C0464E38EA2EC489975EFD418E6C62C55C06030422305F42FB5EC64452244A2067CDC1F8D18DDAE37FAC34265F9F99D4FC8550B94BC2B303E4FB3533E5FB5179B045A441585B1EA55E0124B5065A5700E9519CBAFF7B4E2B4EF8CEF59F9A8322773BBEF886BB83D9F85B366209B42"
    token: "1d30c1b7-863b-4077-928d-cb70d2bf835a"
    trackProject: "711_mini"
    userId: 97522129
    uuid: "C9A1B96251800002F5F313CF1EB912611639383778624"
    vender_id: 11971
}
*/

← 有什么不同？ dLink 跨端统一路由协议 →