ThinkPHP 分頁保持搜尋條件的正確實作方法

問題背景

ThinkPHP 內建 Page 類庫預設僅保留分頁參數，搜尋表單提交的查詢條件在翻頁時會遺失。官方手冊建議遍歷 $map 陣列組裝參數，但實務上 $map 往往是動態構建的條件陣列，不一定包含所有 GET 參數，導致遺漏。

核心解決方案：直接使用 $_GET 組裝分頁參數

// 控制器動作
public function index() {
    $model = D('Article');
    
    // 1. 動態構建查詢條件 (範例)
    $map = [];
    if (!empty($_GET['keyword'])) {
        $map['title|content'] = ['LIKE', "%{$_GET['keyword']}%"];
    }
    if (!empty($_GET['category_id'])) {
        $map['category_id'] = intval($_GET['category_id']);
    }
    if (!empty($_GET['status'])) {
        $map['status'] = $_GET['status'];
    }
    // 日期範圍...
    
    // 2. 查詢總數與資料
    $count = $model->where($map)->count();
    $list  = $model->where($map)->order('id DESC')->select();
    
    // 3. 實例化分頁類
    import('ORG.Util.Page');
    $page = new Page($count, 20); // 每頁 20 筆
    
    // 4. 【關鍵】保留所有 GET 參數 (除 page 自身)
    foreach ($_GET as $key => $val) {
        if ($key !== 'p' && $key !== 'page') { // 避免重複 page 參數
            $page->parameter .= "$key=" . urlencode($val) . "&";
        }
    }
    
    // 5. 設定查詢限制 (配合 Page 類的 firstRow/listRows)
    $list = $model->where($map)
                  ->order('id DESC')
                  ->limit($page->firstRow . ',' . $page->listRows)
                  ->select();
    
    // 6. 輸出分頁 HTML
    $pageHtml = $page->show();
    
    $this->assign('list', $list);
    $this->assign('page', $pageHtml);
    $this->display();
}

Page 類關鍵屬性說明

進階：自訂分頁主題 (Bootstrap 5 風格)

$page->config = [
    'header' => '',
];

// %STATUS% 會被替換為 ' active' (當前頁) 或空字串

常見坑點與解決

1. POST 表單搜尋：搜尋表單 必須使用 GET 方法，否則翻頁無法攜帶條件。若業務需 POST，搜尋送出後導向至帶查詢字串的 GET URL (PRG 模式)。
2. 特殊字元編碼：urlencode() 處理中文/空格/符號，Page 類內部會自動 urldecode 還原。
3. 參數名稱衝突：分頁類預設頁碼參數為 p，若專案使用 page，需設定 $page->p = 'page'; 或修改類常數。
4. 大量查詢條件導致 URL 過長：超過 2000 字元可能被伺服器/瀏覽器截斷。解決：將條件序列化加密存入 Session/快取，分頁僅攜帶 search_token=abc123。
5. AJAX 分頁：$page->show() 產生的連結需攜帶 data-page 屬性，前端 JS 攔截點擊發送 AJAX 請求，局部更新列表。

完整 AJAX 分頁範例 (jQuery)

<!-- 列表容器 -->
<div id="article-list">...</div>

<!-- 分頁容器 -->
<div id="pagination">{$page}</div>

<script>
$('#pagination').on('click', 'a', function(e) {
    e.preventDefault();
    const url = $(this).attr('href');
    $.get(url, function(html) {
        // 假設回傳 JSON: {list: '...', page: '...'}
        $('#article-list').html(html.list);
        $('#pagination').html(html.page);
    }, 'json');
});
</script>

// 控制器 AJAX 判斷
if (IS_AJAX) {
    $this->ajaxReturn([
        'list' => $this->fetch('Article/list_items'), // 區域模板
        'page' => $page->show(),
    ]);
}