在制作网页或是应用程序的图形用户界面时,如果需要显示比较大量的数据,通常制作「换页」、「分页」功能。但是若是做了这样的功能,就必须要让用户能够有方法进行「跳页」的动作。要让用户能够在图形界面上进行跳页,比较简单的方式就是弄个下拉式菜单把所有页码列出来让用户选,或者干脆放上一个文字输入方块直接让用户自行输入要查找的页码。当然,比较潮的方式还是弄一个数字分页导览列(Pagination Bar),会更方便操作。不过数字分页导览列的产生其实有点麻烦,因为通常要考虑到目前用户正在查看的页数、总页数和图形画面上能够显示的页码数量的空间。在 WordPress 中,甚至还提供了一个 paginate_links 函数,专门用来产生数字分页导览列。
下图正是一个 WordPress 产生的数字分页导览列:
我们可以发现,这个数字分页导览列有着 5 种不同的项目(按钮),列表如下:
- 上一页:在目前页码不是第一页的时候出现。
- 其它页码:显示页码并提供超链接。
- 目前页码:加强显示页码,但不提供超链接。
- 省略:显示
...,表示一个或多个连续的页码。当最两端页码的数量和中间(目前页码)两侧的页码数量已达到上限时,其余的页码就会被省略。(其实如果只有一个页码的话不该省略的才对,这是paginate_links函数实作方式的问题) - 下一页:在目前页码不是最后一页的时候出现。
虽然 WordPress 的 paginate_links 函数还是有它的问题在,但它确实是一个方便的函数。所以在 Rust 上当然也要有一个类似的功能啦!而且还能跨平台使用呢!
Paginator
「Paginator」是笔者开发的套件,用来在网页或是其它用户界面上产生数字分页导览列。
在 Rust 上使用 Paginator
Crates.io
Cargo.toml
使用方法
刚才提到的数字分页导览列「项目」,在 paginator 这个 crate 中是以 PageItem 枚举来代表。
Paginator 或是 PaginatorIter 结构体的 builder 关联函数可以用来创建 PaginatorBuilder 结构实体,用以安全地产生 Paginator 或是 PaginatorIter 结构实体。PaginatorIter 结构实体可以用来产生不同「目前页码」的 Paginator 结构实体,而 Paginator 结构实体则有 paginate 方法,可以回传一个 Vec<PageItem> 结构实体。按照顺序走访 Vec<PageItem> 结构实体中的 PageItem 枚举的变体,即可产生出数字分页导览列。
以下是一个产生出总页数为 5,目前页数为 1 的数字分页导览列的例子:
use paginator::{Paginator, PageItem};
use core::fmt::Write;
let paginator = Paginator::builder(5).current_page(1).build_paginator().unwrap();
let mut html = String::new();
for page_item in paginator.paginate() {
match page_item {
PageItem::Prev(page) => {
// `PageItem::Prev` variant is used when the `has_prev` option is not set to `YesNoDepends::No`.
html.write_fmt(format_args!("<li><a href=\"/page/{page}\">«</a></li>", page = page)).unwrap();
}
PageItem::Page(page) => {
html.write_fmt(format_args!("<li><a href=\"/page/{page}\">{page}</a></li>", page = page)).unwrap();
}
PageItem::CurrentPage(page) => {
html.write_fmt(format_args!("<li>{page}</li>", page = page)).unwrap();
}
PageItem::Ignore => {
html.push_str("<li>...</li>");
}
PageItem::Next(page) => {
// `PageItem::Next` variant is used when the `has_next` option is not set to `YesNoDepends::No`.
html.write_fmt(format_args!("<li><a href=\"/page/{page}\">»</a></li>", page = page)).unwrap();
}
_ => {
// `PageItem::ReservedPrev` or `PageItem::ReservedNext` variant is used only when the `has_prev` option or the `has_next` option is set to `YesNoDepends::Yes`.
}
}
}
而以下是一个产生出总页数为 2,且目前页数为 1 或 2 的数字分页导览列的例子:
use paginator::{Paginator, PageItem};
let mut paginator_iter = Paginator::builder(2).build_paginator_iter().unwrap();
for page_item in paginator_iter.next().unwrap().paginate() {
// current_page == 1
}
for page_item in paginator_iter.next().unwrap().paginate() {
// current_page == 2
}
数字分页规则
在创建出 Paginator 结构实体前,有一个重要的 max_item_count 选项可以透过 PaginatorBuilder 结构实体来设置。这个 max_item_count 选项能够限制数字分页导览列中项目的数量,会在 paginate 时,将离目前页面比较远的多余页码以 PageItem::Ignore 变体来取代。另外,也可以设置保留任意数量的最前或是最后的页码,让它们不会被省略。
详情可以参考以下代码:
use paginator::{Paginator, page_items_to_string};
let mut p = Paginator::builder(8).max_item_count(9).start_size(1).end_size(1).build_paginator_iter().unwrap();
assert_eq!("1* 2 3 4 5 6 7 8 >", page_items_to_string(p.next().unwrap().paginate().as_slice()));
assert_eq!("< 1 2* 3 4 5 ... 8 >", page_items_to_string(p.next().unwrap().paginate().as_slice()));
assert_eq!("< 1 2 3* 4 5 ... 8 >", page_items_to_string(p.next().unwrap().paginate().as_slice()));
assert_eq!("< 1 2 3 4* 5 ... 8 >", page_items_to_string(p.next().unwrap().paginate().as_slice()));
assert_eq!("< 1 ... 4 5* 6 7 8 >", page_items_to_string(p.next().unwrap().paginate().as_slice()));
assert_eq!("< 1 ... 4 5 6* 7 8 >", page_items_to_string(p.next().unwrap().paginate().as_slice()));
assert_eq!("< 1 ... 4 5 6 7* 8 >", page_items_to_string(p.next().unwrap().paginate().as_slice()));
assert_eq!("< 1 2 3 4 5 6 7 8*", page_items_to_string(p.next().unwrap().paginate().as_slice()));
在 JavaScript/TypeScript 上使用 Paginator (pagination-bar-generator)
由于 npm 上「paginator」这个名称已经被别人使用,所以改取名为 pagination-bar-generator。
npmjs.com
npm 安装指令
使用方法
import { Paginator } from "pagination-bar-generator";
const paginator = Paginator.builder(5).currentPage(1).buildPaginator();
let html = "";
for (const pageItem of paginator.paginate()) {
switch (pageItem.type) {
case "prev":
html += `<li><a href="/page/${pageItem.pageNumber}">«</a></li>`;
break;
case "page":
html += `<li><a href="/page/${pageItem.pageNumber}">${pageItem.pageNumber}</a></li>`;
break;
case "currentPage":
html += `<li>${pageItem.pageNumber}</li>`;
break;
case "ignore":
html += `<li>...</li>`;
break;
case "next":
html += `<li><a href="/page/${pageItem.pageNumber}">»</a></li>`;
break;
case "reservedPrev":
case "reservedNext":
// The `reservedPrev` or `reservedNext` item is used only when the `hasPrev` option or the `hasNext` option is set to `"yes"`.
break;
}
}

