本文详解 WooCommerce 自定义账户下载模板（如 downloads.php）中分页链接点击后内容不更新的根本原因，并提供基于 GET 参数手动处理分页的可靠方案，确保 /account/downloads/2 等 URL 正确加载对应页数据。
本文详解 woocommerce 自定义账户下载模板（如 `downloads.php`）中分页链接点击后内容不更新的根本原因，并提供基于 get 参数手动处理分页的可靠方案，确保 `/account/downloads/2` 等 url 正确加载对应页数据。
在 WooCommerce 中为账户页面（如「我的下载」）创建自定义模板时，开发者常遇到一个典型问题：分页链接外观正常（例如从 /account/downloads 变为 /account/downloads/2），但页面内容始终显示第一页数据——即分页“失效”。根本原因在于：WooCommerce 账户端点（如 downloads）默认不支持 WordPress 标准的 paged 查询变量，其重写规则未将路径中的数字映射为有效的分页参数，导致 get_query_var('paged') 始终返回 0 或 1，从而使 wc_get_orders() 每次都获取第一页结果。
解决此问题的关键是绕过 WordPress 默认的 paged 机制，改用显式的 GET 参数（如 ?pagina=2）进行分页控制。这需要三步协同：
✅ 1. 正确读取当前页码（替代 get_query_var('paged')）
$paged = max(1, (int) filter_input(INPUT_GET, 'pagina'));
- 使用
filter_input(INPUT_GET, 'pagina')安全获取 URL 中的pagina参数（如?pagina=2）； -
max(1, (int)...)确保页码至少为 1，避免无效值； -
切勿再使用
get_query_var('paged')，因其在自定义端点中不可靠。
✅ 2. 配置 wc_get_orders() 查询参数
$args = array(
'customer_id' => get_current_user_id(),
'post_status' => array('wc-completed'),
'paged' => $paged, // 传入手动解析的页码
'posts_per_page' => 3, // 每页条目数
'paginate' => true, // 启用分页（返回 WP_Query 对象）
);
$customer_orders = wc_get_orders($args);
-
paginate => true是必须项，它使wc_get_orders()返回包含max_num_pages属性的对象，供后续分页渲染使用。
✅ 3. 正确配置 paginate_links() 的 base 和 format
$args = array(
'base' => esc_url(wc_get_endpoint_url('libreria')) . '%_%', // 注意：此处应为你的实际端点 slug（如 'downloads'）
'format' => '?pagina=%#%', // 关键！使用 ?pagina= 形式，而非 /%#%/
'total' => $customer_orders->max_num_pages,
'current' => $paged,
'prev_text' => __('← Indietro'),
'next_text' => __('Avanti →'),
'type' => 'plain'
);
echo paginate_links($args);
-
'base'必须指向你的自定义端点 URL（如wc_get_endpoint_url('downloads')），且末尾保留%_%占位符； -
'format' => '?pagina=%#%'是核心：%#%会被替换为实际页码（如?pagina=2），确保链接生成符合预期； -
避免使用
'/page/%#%/'格式——它依赖 WordPress 重写规则，在账户端点中通常未注册，会导致 404 或刷新当前页。
⚠️ 注意事项与最佳实践
-
端点一致性：确保
wc_get_endpoint_url('libreria')中的'libreria'与你在add_rewrite_endpoint()中注册的端点 slug 完全一致（示例中应为'downloads'）； -
安全性：始终使用
esc_url()处理 URL，wp_kses_post()/esc_attr()过滤输出内容； -
空状态处理：检查
$customer_orders->orders是否为空数组，而非仅判断$customer_orders对象； - 性能优化：若订单量极大，考虑添加缓存逻辑或限制最大分页数；
-
移动端适配：示例中
<table> 结构在移动设备上可能体验不佳，建议改用语义化 <code><div> + CSS Grid/Flex 布局。<p>通过以上调整，分页链接将正确生成 <code>?pagina=2、?pagina=3等 URL，PHP 脚本能准确捕获页码并查询对应数据块，彻底解决“点击分页始终显示第一页”的顽疾。此方案不依赖主题或插件钩子，兼容 WooCommerce 6.x+ 及主流 WordPress 版本，是自定义账户模板分页的稳定实践。
