【年度特惠】现邀请朋友使用企业版,最高可延长 4 个月服务时长!活动仅剩 2 天,错过再等一年!查看详情
私信发送成功
Watch Star Fork

习习风 / pjaxpageJavaScriptMIT

Pagination controls solution for pjax. pushState + ajax = pjax.
克隆/下载
习习风 最后提交于 2017-10-26 10:21 换一张图
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README.md 15.14 KB

1. Quick Start

1.1 HTML Code

Here is the minimal HTML code to get pages working:

<table class="table table-bordered table-hover">
	<!-- 表头 -->
	<tr class="bg"> <th>词组</th> <th>拼音</th> <th>多选项</th> <th>正确答案</th> <th>词义</th> </tr>
	<!-- 分页数据 -->
	<tbody id="dataListBox"> </tbody>
</table>

<!-- 分页索引(分页控制区) -->
<div id="pageCodeBox"></div>

1.2 JS Reference

<!-- 核 -->
<script src="pjaxPage.js"></script>
<!-- 任选一个分页模型(命名规范: pjaxPage.xXXModel.js) -->
<script src="pjaxPage.numberModel.js"></script>

1.3 JS Setup

如果采用本插件提供的分页模型,服务端响应的数据的格式必须为{pageData:{...},...}, 熟悉分页数据结构.
注意: {pageData:{...},...} 中的pageData分页数据结构的对象名称,该名称允许配置,请看pjaxPage配置选项(opts)章节.

$.pjaxPage({

	// ajax 配置.支持jQuery.ajax所有的配置选项.ajax的settings,请参照jQuery官方说明
	ajax : {
		url : "https://your.damain.com/pjaxpage-data.json",
		dataType : "jsonp" // 支持"json","jsonp","xml","html","script","text"...等等
	},
	// 自定义分页数据结构对象的名称为"pageData",其实默认也是这个值,可以省略不配置.
	pageDataKeyName : "pageData",
	size : 10,
	// 配置分页模型
	pageModel: {
		name : "numberModel", // 分页模型的名称
		opts : {
                       // 分页模型的opts, 详情请阅读分页模型章节
                       indexNum: 7,
                       home : "Home",
                       prev : "Prev",
                       next : "Next",
                       end : "End",
                       showEllipsis : false
		}
	},
	createDataHtml : function(data,textStatus,jqXHR) { // 在此仅需拼接分页数据 然后return 即可
		var content = data.pageData.content;
		var total = content.length;
		if (total == 0)
			return "";

		var dataHtml = '';
		var orderNum = (this.currentPage - 1) * this.size + 1; // 序号
		for (var i = 0; i < total; i++, orderNum++) {
			
			var cizu = content[i].cizu;
			var pinyin = content[i].pinyin;
			var options = content[i].options;
			var ok = content[i].ok;
			var info = content[i].info;
			
			dataHtml += '<tr>';
			dataHtml += '	<td>' + orderNum + '</td>';
			dataHtml += '	<td>' + cizu + '</td>';
			dataHtml += '	<td>' + pinyin + '</td>';
			dataHtml += '	<td>' + options + '</td>';
			dataHtml += '	<td>' + ok + '</td>';
			dataHtml += '	<td>' + info + '</td>';
			dataHtml += '</tr>';
		}

		return dataHtml;
	}
});

2. Example

http://xixifeng.com.oschina.io/pjaxpage/example/

3. 什么是pjaxPage ?

pjax = pushState + ajax, Page源自于FastQuery项目的Page设计.
pjaxPage 它基于jQuery,用于实现前端页面翻页,它的优势在于:

  • 可以让局部分页请求变成有状态
  • 有多种分页模型可供选择
  • 模块化设计,开发者可以扩展分页模型

4. 定义

为了方便描述,现在做如下定义(本定义仅仅只针对pjaxPage项目):

定义名 学名 解释
页片 P.Slice 待分页的数据可以分成很多页片,以便翻页
分页概述 P.Info 对分页之后的数据进行描述,称之为分页概述
分页控制区 P.Ctrl 用于控制翻页的区域,称之为分页控制区
分页索引 P.Index 对页片进行编号,一般从1开始,这个编号将称之为分页索引,分页索引通常可以被单击,用于翻页
索引触发状态 P.Active 用于明显标记被触发的分页索引的状态,称之为索引触发状态
分页数据结构 P.Struct 从服务端请求某一页数据,有一定格式的,这个格式称之为分页数据结构

定义名,如下图所示:
定义名

5. P.Struct

分页数据结构:

{
	"content":[             // 这页的数据
		{
			"name":"查尔斯·巴贝奇","id":2,"year":1792
		},
		{
			"name":"约翰·冯·诺依曼","id":3,"year":1903
		},
		{                     
			"name":"阿兰·麦席森·图灵","id":1,"year":1912
		},
		{
			"name":"约翰·麦卡锡","id":4,"year":1927
		},
		{
			"name":"丹尼斯·里奇","id":5,"year":1941
		},
		{
			"name":"蒂姆·伯纳斯·李","id":6,"year":1955
		}
	],
    "first": true,           	// 是否是第一页
    "hasContent": true,      	// 这页是否有数据
    "hasNext": true,         	// 是否有下一页
    "hasPrevious": false,    	// 是否有上一页
    "last": false,           	// 是否是最后一页
    "nextPageable": {        	// 下一页的基本属性
        "number": 1,         	// 定位的页码
        "size": 15           	// 每页多少条数据
    },
    "number": 1,             	// 当前页码,从1开始
    "numberOfElements": 6,  	// 当前页的真实记录行数
    "previousPageable": {    	// 上一页的基本属性
        "number": 0,         	// 定位的页码
        "size": 15           	// 每页多少条数据
    },
    "size": 15,              	// 每页行数
    "totalElements": 188,    	// 总行数
    "totalPages": 13         	// 总页数
}

FastQuery项目中的Page实例转换成JSON后就是这种结构.本项目自带的分页模型都基于P.Struct(分页数据结构). 当然,开发者也可以自定义数据结构.

6. pjaxPage配置选项(opts)

该配置描述中提到的opts指的是pjaxPage中的options.

属性 类型 默认值 描述
ajax Object {} jQuery的ajax的配置(settings),支持jQuery.ajax所有的配置选项.ajax的settings,请参照jQuery官方说明
size int 15 用于指定P.Slice(页片)显示多少条记录.换言之,指定每页显示多少条记录
pageKeyName String "page" 表示告诉服务端要请求的是第几页,这个参数的名称(换言之,用哪个参数名称表示要请求的页索引)
sizeKeyName String "size" 表示告诉服务端当前页需要多少记录,这个参数的名称(换言之,用哪个参数名称表示要请求的页有多少条记录)
currentPage int 1 用于指定当前页的P.Index(分页索引),例如:把currentPage设置为N,那么就显示第N页
dataListBox jQuery $("#dataListBox") 用于装载P.Slice的盒子
pageCodeBox jQuery $("#pageCodeBox") 用于装载P.Ctrl的盒子
pageInfoTpl String "<p>共{totalElements}条记录,总页数:{totalPages}</p>" P.Info(分页概述)模板,它会被pageCodeBox包裹.熟悉内置模板标签
buildTplSource(data,
textStatus,jqXHR)
callback function --- 返回类型:JSON Object.作用:构模板数据源.举例:若返回{info:"xxx",goods:3},那么在pageInfoTpl中可以通过{info}引用到info值,通过{goods}引用到goods值.参数解释,data:是ajax成功请求所响应的数据;textStatus:用于描述状态的字符串;jqXHR:请参与jQuery文档http://api.jquery.com/jQuery.ajax/#jqXHR.**注意**:这个方法的上下文对象为opts
pageModel JSON {name:"numberModel"} 用于配置分页模型,开发者扩展扩展自己的分页模型.numberModel的可选参数,请参阅分页模型章节
pageDataKeyName String "pageData" 用于指定P.Struct(分页数据结构)的对象名称
createDataHtml(data,
textStatus,jqXHR)
callback function --- 返回类型:String.共:3个参数. 解释,data:是ajax成功请求所响应的数据;textStatus:用于描述状态的字符串;jqXHR:请参与jQuery文档http://api.jquery.com/jQuery.ajax/#jqXHR. 该函数的作用:创建当前P.Slice的HTML代码,并返回.注意:这个方法的上下文对象为opts
notFoundTip String "Not Found Data!" 翻页时如果没有找到数据,会将此选项设置的值写入到用于装载P.Slice的盒子里,支持HTML
pageCodeItem HTML
element
"a[tabindex]" P.Index的HTML元素选择器
eventName String "click" P.Index的事件名称.默认click,表示单击分页索引就翻页,若设置为dblclick,表示双击分页索引,才能翻页.当然,也可以基于jQuery自定义一个事件
dataCache boolean true 是否采用jQuery的data函数缓存P.Slice(页片)数据,该缓存生命周期很短,只要用户刷新浏览器(F5)或关闭浏览器,缓存的数据立马消失
clear() callback function --- 返回类型:opts.清除所有页片缓存
writeListBefore() callback function --- 返回类型:自定义.数据列表写入倒dom之前,该方法的上下文对象(this)是opts
writeListAfter(data,
textStatus,jqXHR)
callback function --- 返回类型:自定义.数据列表写入倒dom之后,data为服务器响应的数据,该方法的上下文对象(this)为opts
getReqParam() callback function --- 返回类型:String,URL参数部分.获取请求参数,注意:它的上下文对象为opts
pjaxId String "xixifeng_pjax" pjax ID 会显示在浏览器地址栏上
enabledPjax boolean true 是否启用pjax功能,如果浏览器不支持pushState将无法开启pjax功能
pageHrefPre String --- P.Index链接地址的前缀
pageIndex(indexNum,
currentPage,totalpage)
callback function --- 返回类型:JSON Object.计算开始页和结束页.参数说明:indexNum:(必选项)指定在分页控制区中显示分页索引的个数(不包含"N+...","...N+"或"箭头");currentPage:当前分页索引;totalpage:(必选项)总页面数 返回格式: {"startpage" : startpage,"endpage":endpage}
queryParam(href,name) callback function --- 返回类型:String.从一个参数地址中查询出一个参数的值.举例: 从a=1&b=2&c=3查出c的值. 写法:queryParam("a=1&b=2&c=3","c") 得出3.参数说明:href:(必选项)url地址;name:(必选项)参数的名称.返回: 参数值,如果没有找到返回""

内置模板标签

标签 描述
{totalElements} 数据总记录数
{currentPage} 当前页索引
{totalPages} 总页数

7. 自定义请求参数

分页默认请求参数:

参数名 类型 描述
page int 告诉服务端要请求的是第几页
size int 告诉服务端当前页需要多少记录

自定义请求参数名称,举例说明:
若page=3,size=10时, pajxPage内部会发出请求https://your.damain.com?page=3&size=10,表示获取第3页,期望这页是10条数据组成.pagesize这两个内置请求参数,因为不需要开发者维护,更不需要人为指定.所以,有可能跟设计的业务参数有冲突.因此,这两个内置参数允许开发者自行修改,是有意义的.若在pjaxPage配置选项里把pageKeyName设置为"pageIndex",sizeKeyName设置为"recordNum".同样的需求,pajxPage内部会发出请求https://your.damain.com?pageIndex=3&recordNum=10,从而,避开pagesize这两个参数.

8. 分页模型

8.1 pjaxPage.numberModel.js

pjaxPage.numberModel

<ul class="pagination">
	<li><a href="#">首页</a></li>
	<li><a href="#">上一页</a></li>
	<li><a href="#">4</a></li>
	<li class="active"><a href="#">5</a></li>
	<li><a href="#">6</a></li>
	<li><a href="#">下一页</a></li>
	<li><a href="#">末页</a></li>
</ul>

配置选项(opts):

属性 类型 默认值 描述
activeName String active P.Index被触发后的class样式选择器的名称
indexNum int 5 指定在分页控制区中显示分页索引的个数(不包含"N+...","...N+"或"箭头"),建议设置值是一个奇数,可以让当前触发索引位于中间,那样好看些
home String "&lt;&lt;"
"<<" HTML
表示首页用什么字符串标识
prev String "&lt;"
"<" HTML
表示上一页用什么字符串标识
next String "&gt;"
">" HTML
表示下一页用什么字符串标识
end String "&gt;&gt;"
">>" HTML
表示末页用什么字符串标识
showEllipsis boolean true 是否在分页控制区显示省略号(...)
pageInfoTpl String 同pjaxPage的opts.pageInfoTpl中的默认值 此配置优先

8.2 pjaxPage.singleModel.js

pjaxPage.singleModel

<ul class="pagination">
	<li><a href="#">下一页</a></li>
</ul>

这个分页模型,只有一个按钮,特点:下一页到尽头了,允许回到上一页. 上一页到尽头了允许回到下一页.
配置选项(opts):

属性 类型 默认值 描述
prev String "上一页" 表示上一页用什么字符串标识
next String "下一页" 表示下一页用什么字符串标识
pageInfoTpl String 同pjaxPage的opts.pageInfoTpl中的默认值 此配置优先

8.3 pjaxPage.textModel.js

pjaxPage.singleModel

<ul class="pagination">
	<li><a href="#">首页</a></li>
	<li><a href="#">上一页</a></li>
	<li><a href="#">下一页</a></li>
	<li><a href="#">末页</a></li>
</ul>

配置选项(opts):

属性 类型 默认值 描述
home String "首页" 表示首页用什么字符串标识
prev String "上一页" 表示上一页用什么字符串标识
next String "下一页" 表示下一页用什么字符串标识
end String "末页" 表示末页用什么字符串标识
pageInfoTpl String 同pjaxPage的opts.pageInfoTpl中的默认值 此配置优先
disabledName String "disabled" 定义不可点击链接的class样式选择器的名称

8.4 pjaxPage.toggleModel.js

pjaxPage.singleModel

<ul class="pagination">
	<li><a href="#">&laquo;</a></li>
	<li><a href="#"></a></li>
	<li><a><b>17</b>/32</a></li>
	<li><a href="#"></a></li>
	<li><a href="#">&raquo;</a></li>
</ul>

配置选项(opts): 同 pjaxPage.textModel.js.

8.5 pjaxPage.simpleModel.js

pjaxPage.singleModel

<ul class="pagination">
	<li><a href="#">Prev</a></li>
	<li><a href="#">Next</a></li>
</ul>

配置选项(opts):

属性 类型 默认值 描述
prev String "上一页" 表示上一页用什么字符串标识
next String "下一页" 表示下一页用什么字符串标识
pageInfoTpl String 同pjaxPage的opts.pageInfoTpl中的默认值 此配置优先
disabledName String "disabled" 定义不可点击链接的class样式选择器的名称

项目点评 (0)

你可以在登录后,对此项目发表评论