1、简介

router.js是一个路由插件。路由功能将接管页面的链接点击行为,最后达到动画切换的效果,具体如下:

(1) 链接对应的是另一个页面,那么则尝试 ajax 加载,然后把新页面里的符合约定的结构提取出来,然后做动画切换;如果没法 ajax 或结构不符合,那么则回退为普通的页面跳转;
(2) 链接是当前页面的锚点(即内联的新页面),并且该锚点对应的元素存在且符合路由约定,那么则把该元素做动画切入;
(3) 浏览器前进后退(history.forward/history.back)时,也使用动画效果;
(4) 如果链接有 back 这个 class,那么则忽略一切,直接调用 history.back() 来后退;

2、开始使用

(1) 引入router.css和router.js

<link rel="stylesheet" href="css/router.css">
<script type='text/javascript' src='js/router.js' charset='utf-8'></script>

(2) html的结构

注意:ajax加载新页面,一般只需一个page;内联新页面时,需要多个page,每个page需要一个不同的id属性名。

<div class="sui-page-group">
	<div class="sui-page" id="page1">xxx</div>
	<div class="sui-page" id="page2">yyy</div>
</div>

(3) ajax加载新页面时,路由的写法:

<a href="addressForm.jsp" class="edit-address use-router">编辑</a>

(4) 内联新页面时,路由的写法:

<a href="#page2" class="edit-address use-router">编辑</a>

3、使用注意事项

(1) 路由功能默认关闭,如果需要开启路由功能,那么给a标签或a标签的父级加"class='use-router'"即可。

(2) ajax 载入新的文档时,并不会执行里面的 js。到目前为止,在开启路由功能时,建议的做法是:

把所有页面的 js 都放到同一个脚本里,js 里面的事件绑定使用委托而不是直接的绑定在元素上(因为动态加载的页面元素还不存在),然后所有页面都引用相同的 js 脚本。非事件类可以通过监控 pageInit 事件,根据里面的 pageId 来做对应区别处理。


4、相关文件下载

router.css router.js

5、路由其他说明


事件
pageLoad* 系列在发生 ajax 加载时才会触发;当是块切换或已缓存的情况下,不会发送这些事件
- pageLoadCancel: 如果前一个还没加载完,那么取消并发送该事件
- pageLoadStart: 开始加载
- pageLodComplete: ajax complete 完成
- pageLoadError: ajax 发生 error
- pageAnimationStart: 执行动画切换前,实参是 event,sectionId 和 $section
- pageAnimationEnd: 执行动画完毕,实参是 event,sectionId 和 $section
- beforePageRemove: 新 document 载入且动画切换完毕,旧的 document remove 之前在 window 上触发,实参是 event 和 $pageContainer
- pageRemoved: 新的 document 载入且动画切换完毕,旧的 document remove 之后在 window 上触发
- beforePageSwitch: page 切换前,在 pageAnimationStart 前,beforePageSwitch 之后会做一些额外的处理才触发 pageAnimationStart
- pageInitInternal: (经 init.js 处理后,对外是 pageInit)紧跟着动画完成的事件,实参是 event,sectionId 和 $section

术语
- 文档(document),不带 hash 的 url 关联着的应答 html 结构
- 块(section),一个文档内有指定块标识的元素

路由实现约定
- 每个文档的需要展示的内容必需位于指定的标识(routerConfig.sectionGroupClass)的元素里面,默认是: div.sui-page-group (注意,如果改变这个需要同时改变 less 中的命名)
- 每个块必需带有指定的块标识(routerConfig.pageClass),默认是 .sui-page

即,使用路由功能的每一个文档应当是下面这样的结构(省略 <body> 等):
<div class="sui-page-group">
<div class="sui-page">xxx</div>
<div class="sui-spage">yyy</div>
</div>

另,每一个块都应当有一个唯一的 ID,这样才能通过 #the-id 的形式来切换定位。
当一个块没有 id 时,如果是第一个的默认的需要展示的块,那么会给其添加一个随机的 id;否则,没有 id 的块将不会被切换展示。

通过 history.state/history.pushState 以及用 sessionStorage 来记录当前 state 以及最大的 state id 来辅助前进后退的切换效果,所以在不支持 sessionStorage 的情况下,将不开启路由功能。

为了解决 ajax 载入页面导致重复 ID 以及重复 popup 等功能,上面约定了使用路由功能的所有可展示内容都必需位于指定元素内。从而可以在进行文档间切换时可以进行两个文档的整体移动,切换完毕后再把前一个文档的内容从页面之间移除。

默认地过滤了部分协议的链接,包括 tel:, javascript:, mailto:,这些链接将不会使用路由功能。如果有更多的自定义控制需求,可以在 $.config.routerFilter 实现

注: 以 _ 开头的函数标明用于此处内部使用,可根据需要随时重构变更,不对外确保兼容性。