mmRouter

Name 路由器

新文档 旧版文档 迁移教程

路由器插件，实现类似angular ui-router的功能

常见问题及解决方案
1、TypeError: avalon.require is not a function --mmState.js 有什么办法，用的是avalon.shim.js - 重写avalon.controller.loader这个函数，参考下边具体的文档说明

更多问题
mmRouter的使用
1、引入依赖(直接依赖于mmRouter, 总共依赖于avalon, mmRouter, mmHistory)
require(["mmRouter"], function() {})
2、定义VM
var model = avalon.define('test', function(vm) {
    vm.currPath = ""
    vm.params = {}
    vm.query = {}
    vm.args = "[]"
})
3、定义路由规则
function callback() {
    model.currPath = this.path
    var params = this.params
    if ("time" in params) {
        params.time = avalon.filters.date(params.time, "yyyy年M月dd日")
    }
    model.params = params
    model.query = this.query
    model.args = "[" + [].slice.call(arguments, 0) + "]"
 
}
avalon.router.get("/aaa/", callback)
avalon.router.get("/bbb", callback)
avalon.router.get("/ccc/:ccc", callback)
avalon.router.get("/ddd/{time:date}/", callback)
avalon.router.get("/eee/{count:\\d{4}}/", callback)
avalon.router.get("/fff", callback)
4、启动历史管理器
avalon.history.start({
    basepath: "/avalon"
})
5、开始扫描
avalon.scan()
6、页面上的链接处理，所有不想跳转不想刷新整面的A标签，都需要以`#!`/或`#/`开头 （这个由历史管理器的`hashPrefix`参数决定，默认是`!`），target属性指向当前页面．
<ul> <li> <a href="#!/aaa">aaa</a> </li>
                        <li> <a href="#!/bbb?uu=3445345&were=4324">bbb</a>
                        </li> <li> <a href="#!/ccc/etretr">ccc</a> </li>
                        <li> <a href="#!/ddd/2014-09-19">ddd</a> </li>
                        <li> <a href="#!/eee/2222">eee</a> </li> <li>
                        <a href="#!/fff?a=1&nn=4&dfg=676">fff</a> </li>
                        </ul>
mmRouter与mmHistory的API列表
`avalon.history.start(opts)`， 开始监听URL变化，opts。 enter image description here
`avalon.history.stop()`， 中止监听URL变化。
`avalon.router.get(path, callback)`，用于添加路由规则。第一个为路由规则，
如"/aaa", "/bbb/:bbbId","/eee/{eeeId}/ddd/{dddId:[0-9]{6}}" 冒号后的东西或花括号的东西表示为参数，
花括号模式下还可以指定匹配规则。callback为回调函数，框架会将冒号后的或花括中的匹配内容传进来，
此外this对象，包含了path、 params、 query等对象与属性。
`'/hello/'` - 匹配'/hello/'或'/hello'
`'/user/:id'` - 匹配 '/user/bob' 或 '/user/1234!!!' 或 '/user/' 但不匹配 '/user' 与 '/user/bob/details'
`'/user/{id}'` - 同上
`'/user/{id:[^/]*}'` - 同上
`'/user/{id:[0-9a-fA-F]{1,8}}'` - 要求ID匹配/[0-9a-fA-F]{1,8}/这个子正则
`'/files/{path:.*}'` - Matches any URL starting with '/files/' and captures the rest of the
path into the parameter 'path'.
`'/files/*path'` - ditto.
avalon.router.get("/ddd/:dddID/", callback)
avalon.router.get("/ddd/{dddID}/", callback)
avalon.router.get("/ddd/{dddID:[0-9]{4}}/", callback)
avalon.router.get("/ddd/{dddID:int}/", callback)
我们甚至可以在这里添加新的类型， avalon.router.$type.d4 = {
    pattern: '[0-9]{4}',
    decode: Number
}
avalon.router.get("/ddd/{dddID:d4}/", callback)
`avalon.router.add(method, path, callback)` ， 添加回调，第一个为请求类型， 如GET，POST，DELETE什么， 第2个为路由规则，第3个为回调函数 `avalon.router.error(callback)`，如果没有一条路由规则满足此请求，那么就转交此回调处理， 我们可以在里面写跳转到404页面这样的逻辑 `avalon.router.navigate(path)`，强制触发对应路径的回调 `avalon.router.setLastPath(path)` ， 这是框架自己调用，保存最近一次跳转的路径 `avalon.router.getLastPath()` 取得最近一次跳转的路径，比如用户F5强制页面，你在ready回调中执行此方法， 得到path，然后将它放进navigate中就能回到原来的页面了。

路由器与多个VM的协作（每个VM定义在不同的JS文件中）

使用说明

名字 类型 默认值 说明
接口方法与固有属性
start(options) Function avalon.history.start 开始监听历史变化
参数名/返回值 类型 说明
options options 配置参数
options.hashPrefix hash以什么字符串开头，默认是 "!"，对应实际效果就是"#!"
options.routeElementJudger 判断a元素是否是触发router切换的链接的函数，return true则触发切换，默认为avalon.noop，history内部有一个判定逻辑，是先判定a元素的href属性是否以hashPrefix开头，如果是则当做router切换元素，因此综合判定规则是 href.indexOf(hashPrefix) == 0 || routeElementJudger(ele, ele.href)，如果routeElementJudger返回true则跳转至href，如果返回的是字符串，则跳转至返回的字符串，如果返回false则返回浏览器默认行为
options.html5Mode 是否采用html5模式，即不使用hash来记录历史，默认false
options.fireAnchor 决定是否将滚动条定位于与hash同ID的元素上，默认为true
options.basepath 根目录，默认为"/"
redirect(hash) Function avalon.router.redirect
参数名/返回值 类型 说明
hash hash 访问的url hash
navigate(hash,options) Function avalon.router.navigate
参数名/返回值 类型 说明
hash hash 访问的url hash
options options 扩展配置
options.replace true替换history，否则生成一条新的历史记录
options.silent true表示只同步url，不触发url变化监听绑定
when(path,redirect) Function avalon.router.when 配置重定向规则
参数名/返回值 类型 说明
path path 被重定向的表达式，可以是字符串或者数组
redirect redirect 重定向的表示式或者url
get(path,callback) Function avalon.router.get 添加一个router规则
参数名/返回值 类型 说明
path path url表达式
callback callback 对应这个url的回调
go(toName,params,options) Function avalon.router.go 跳转到一个已定义状态上，params对参数对象
参数名/返回值 类型 说明
toName toName 状态name
params params 附加参数
options params.query 在hash后面附加的类似search的参数对
options 扩展配置
options.reload true强制reload，即便url、参数并未发生变化
options.replace true替换history，否则生成一条新的历史记录
options.confirmed true不触发onBeforeUnload,$onBeforeUnload,onBeforeExit
state(stateName,opts) Function avalon.state 对avalon.router.get 进行重新封装，生成一个状态对象
参数名/返回值 类型 说明
stateName stateName 指定当前状态名
opts opts 配置
opts.url 当前状态对应的路径规则，与祖先状态们组成一个完整的匹配规则
opts.ignoreChange Function 当mmState.currentState == this时，更新视图的时候调用该函数，return true mmRouter则不会去重写视图和scan，请确保该视图内用到的数据没有放到avalon vmodel $skipArray内
opts.controller 如果不写views属性,则默认view为""，为默认的view指定一个控制器，该配置会直接作为avalon.controller的参数生成一个$ctrl对象
opts.controllerUrl 指定默认view控制器的路径，适用于模块化开发，该情形下默认通过avalon.controller.loader去加载一个符合amd规范，并返回一个avalon.controller定义的对象，传入opts.params作参数
opts.controllerProvider 指定默认view控制器的提供者，它可以是一个Promise，也可以为一个函数，传入opts.params作参数 @param opts.viewCache 是否缓存这个模板生成的dom，设置会覆盖dom元素上的data-view-cache，也可以分别配置到views上每个单独的view上
opts.views 如果不写views属性,则默认view【ms-view=""】为""，也可以通过指定一个viewname属性来配置【ms-view="viewname"】，对多个[ms-view]容器进行处理,每个对象应拥有template, templateUrl, templateProvider，可以给每个对象搭配一个controller||controllerUrl||controllerProvider属性 views的结构为 
{
"": {template: "xxx"}
"aaa": {template: "xxx"}
"bbb@": {template: "xxx"}
}
views的每个键名(keyname)的结构为viewname@statename， 如果名字不存在@，则viewname直接为keyname，statename为opts.stateName 如果名字存在@, viewname为match[0], statename为match[1]
opts.views.{viewname}.template 指定当前模板，也可以为一个函数，传入opts.params作参数，* @param opts.views.viewname.cacheController 是否缓存view的控制器，默认true
opts.views.{viewname}.templateUrl 指定当前模板的路径，也可以为一个函数，传入opts.params作参数
opts.views.{viewname}.templateProvider 指定当前模板的提供者，它可以是一个Promise，也可以为一个函数，传入opts.params作参数
opts.views.{viewname}.ignoreChange 用法同state.ignoreChange，只是针对的粒度更细一些，针对到具体的view
opts.onBeforeEnter Function 切入某个state之前触发，this指向对应的state，如果return false则会中断并退出整个状态机
opts.onEnter Function 进入状态触发，可以返回false，或任意不为true的错误信息或一个promise对象，用法跟视图的$onEnter一致
onEnter.params Function 视图所属的state的参数
onEnter.resolve Function $onEnter return false的时候，进入同步等待，直到手动调用resolve
onEnter.reject Function 数据加载失败，调用
opts.onBeforeExit Function state退出前触发，this指向对应的state，如果return false则会中断并退出整个状态机
opts.onExit Function 退出后触发，this指向对应的state
opts.ignoreChange.changeType 值为"param"，表示params变化，值为"query"，表示query变化
opts.ignoreChange.viewname 关联的ms-view name
opts.abstract 表示它不参与匹配，this指向对应的state
opts.parentState private 父状态对象（框架内部生成）
config(config) Function avalon.state.config 全局配置
参数名/返回值 类型 说明
config Object config 配置对象
config.onBeforeUnload Function 开始切前的回调，this指向router对象，第一个参数是fromState，第二个参数是toState，return false可以用来阻止切换进行
config.onAbort Function onBeforeUnload return false之后，触发的回调，this指向mmState对象，参数同onBeforeUnload
config.onUnload Function url切换时候触发，this指向mmState对象，参数同onBeforeUnload
config.onBegin Function 开始切换的回调，this指向mmState对象，参数同onBeforeUnload，如果配置了onBegin，则忽略begin
config.onLoad Function 切换完成并成功，this指向mmState对象，参数同onBeforeUnload
config.onViewEnter Function 视图插入动画函数，有一个默认效果
config.onViewEnter.arguments[0] Node 新视图节点
config.onViewEnter.arguments[1] Node 旧的节点
config.onError Function 出错的回调，this指向对应的state，第一个参数是一个object，object.type表示出错的类型，比如view表示加载出错，object.name则对应出错的view name，object.xhr则是当使用默认模板加载器的时候的httpRequest对象，第二个参数是对应的state
getQuery() Function state.getQuery 获取state的query，等价于state.query 
onEnter: function() {
var query = this.getQuery()
or
this.query
}
getParams() Function state.getParams 获取state的params，等价于state.params 
onEnter: function() {
var params = this.getParams()
or
this.params
}
controller() Function avalon.controller 给avalon.state视图对象配置控制器
参数名/返回值 类型 说明
name 控制器名字
factory Function 控制器函数，传递一个内部生成的控制器对象作为参数
factory.arguments[0] Object $ctrl 控制器的第一个参数：实际生成的控制器对象
$ctrl.$vmodels Object 给视图指定一个scan的vmodels数组，实际scan的时候$vmodels.concat(dom树上下文继承的vmodels)
$ctrl.$onBeforeUnload Function 该视图被卸载前触发，return false可以阻止视图卸载，并阻止跳转
$ctrl.$onEnter Function 给该视图加载数据，可以返回false，或任意不为true的错误信息或一个promise对象，传递3个参数
$ctrl.$onEnter.arguments[0] Object params第一个参数：视图所属的state的参数
$ctrl.$onEnter.arguments[1] Function resolve $onEnter 第二个参数：return false的时候，进入同步等待，直到手动调用resolve
$ctrl.$onEnter.arguments[2] Function reject 第三个参数：数据加载失败，调用
$ctrl.$onRendered Function 视图元素scan完成之后，调用
loader(url,callback) Function avalon.controller.loader avalon.controller异步引入模块的加载器，默认是通过avalon.require加载
templateLoader(url,resolve,reject,reason) Function avalon.state.templateLoader 通过url异步加载模板的函数，默认是通过内置的httpRequest去加载，但是在node-webkit环境是不work的，因此开放了这个配置，用以自定义url模板加载器，会在一个promise实例里调用这个方法去加载模板
参数名/返回值 类型 说明
url url 模板地址
resolve resolve 加载成功，如果需要缓存模板，请调用
resolve(avalon.templateCache[url] = templateString)
否则，请调用
resolve(templateString)
reject reject 加载失败，请调用reject(reason)
reason reason 挂在失败原因的对象