在制作网页或是应用程序的图形用户界面时,如果需要显示比较大量的数据,通常制作「换页」、「分页」功能。但是若是做了这样的功能,就必须要让用户能够有方法进行「跳页」的动作。要让用户能够在图形界面上进行跳页,比较简单的方式就是弄个下拉式菜单把所有页码列出来让用户选,或者干脆放上一个文字输入方块直接让用户自行输入要查找的页码。当然,比较潮的方式还是弄一个数字分页导览列(Pagination Bar),会更方便操作。不过数字分页导览列的产生其实有点麻烦,因为通常要考虑到目前用户正在查看的页数、总页数和图形画面上能够显示的页码数量的空间。在 WordPress 中,甚至还提供了一个 paginate_links 函数,专门用来产生数字分页导览列。

下图正是一个 WordPress 产生的数字分页导览列:

WordPress 产生的数字分页导览列

我们可以发现,这个数字分页导览列有着 5 种不同的项目(按钮),列表如下:

  • 上一页:在目前页码不是第一页的时候出现。
  • 其它页码:显示页码并提供超链接。
  • 目前页码:加强显示页码,但不提供超链接。
  • 省略:显示 ...,表示一个或多个连续的页码。当最两端页码的数量和中间(目前页码)两侧的页码数量已达到上限时,其余的页码就会被省略。(其实如果只有一个页码的话不该省略的才对,这是 paginate_links 函数实作方式的问题)
  • 下一页:在目前页码不是最后一页的时候出现。

虽然 WordPress 的 paginate_links 函数还是有它的问题在,但它确实是一个方便的函数。所以在 Rust 上当然也要有一个类似的功能啦!而且还能跨平台使用呢!

Paginator

「Paginator」是笔者开发的套件,用来在网页或是其它用户界面上产生数字分页导览列。

在 Rust 上使用 Paginator

Crates.io

Cargo.toml

paginator = "*"
使用方法

刚才提到的数字分页导览列「项目」,在 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}\">&laquo;</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}\">&raquo;</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 安装指令

npm install pagination-bar-generator
使用方法
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}">&laquo;</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}">&raquo;</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;
    }
}

在网页浏览器上使用 Paginator (pagination-bar-generator)

网页源代码

展示页面