feat(forum): topic list widget AJAX load-more like zibll

Shared query_payload + REST /forum/frontend/widgets/topics wired
to ajax-list for sidebar forum posts lists.

src/AKSRT/Forum/Forum.php

@@ -246,6 +246,40 @@ class Forum {
         $this->view_builder()->ajax_board_topics();
     }
 
+    public function register_widget_routes(): void {
+        register_rest_route('aksrt/v1', '/forum/frontend/widgets/topics', [
+            'methods'             => 'GET',
+            'callback'            => [$this, 'rest_widget_topics'],
+            'permission_callback' => '__return_true',
+        ]);
+    }
+
+    public function rest_widget_topics(\WP_REST_Request $request) {
+        if (!class_exists('\AKSRT\Widgets\WidgetForumTopicLists')) {
+            return new \WP_REST_Response(['success' => false, 'message' => 'widget unavailable'], 500);
+        }
+        $instance = [
+            'count'    => max(1, min(30, (int) ($request->get_param('count') ?? 8))),
+            'orderby'  => sanitize_key((string) ($request->get_param('orderby') ?? 'date')),
+            'style'    => sanitize_key((string) ($request->get_param('style') ?? 'mini')),
+            'plate_id' => max(0, (int) ($request->get_param('plate_id') ?? 0)),
+            'paginate' => sanitize_key((string) ($request->get_param('paginate') ?? 'ajax')),
+        ];
+        $page = max(1, (int) ($request->get_param('page') ?? $request->get_param('paged') ?? 1));
+        $payload = \AKSRT\Widgets\WidgetForumTopicLists::query_payload($instance, $page);
+        return new \WP_REST_Response([
+            'success' => true,
+            'html' => (string) ($payload['html'] ?? ''),
+            'paginate_html' => (string) ($payload['paginate_html'] ?? ''),
+            'has_more' => !empty($payload['has_more']),
+            'page' => (int) ($payload['page'] ?? $page),
+            'max_pages' => (int) ($payload['max_pages'] ?? 1),
+            'total' => (int) ($payload['total'] ?? 0),
+        ], 200);
+    }
+
+
+
     public function render_board_cards(array $boards): void {
         $this->view_builder()->render_board_cards($boards);
     }
@@ -396,6 +430,7 @@ class Forum {
         // Public plate/board topic list (sort tabs)
         add_action('wp_ajax_aksrt_forum_board_topics', [$this, 'ajax_board_topics']);
         add_action('wp_ajax_nopriv_aksrt_forum_board_topics', [$this, 'ajax_board_topics']);
+        add_action('rest_api_init', [$this, 'register_widget_routes']);
 
         add_action('admin_init', [$this, 'maybe_migrate_boards'], 25);
         add_filter('template_include', [$this, 'template_routing']);

src/AKSRT/Widgets/WidgetForumTopicLists.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Forum topic list widget (zibll zib_bbs_widget_ui_posts_lists lite).
+ * Forum topic list widget (zibll zib_bbs_widget_ui_posts_lists lite + ajax pager).
  *
  * @package AKSRT
  */
@@ -16,35 +16,27 @@ class WidgetForumTopicLists extends \WP_Widget {
 			'aksrt_forum_topic_lists',
 			esc_html__('论坛 - 帖子列表', 'aksrt'),
 			[
-				'description' => esc_html__('按排序/版块筛选展示论坛帖子。', 'aksrt'),
+				'description' => esc_html__('按排序/版块筛选展示论坛帖子（支持 AJAX 加载更多）。', 'aksrt'),
 				'classname'   => 'widget_aksrt_forum_topic_lists',
 			]
 		);
 	}
 
-	public function widget($args, $instance): void {
+	/**
-		if (!post_type_exists('aksrt_forum_topic')) {
+	 * @param array $instance
-			return;
+	 * @param int   $paged
-		}
+	 * @return array
-
+	 */
-		$count   = max(1, min(30, (int) ($instance['count'] ?? 8)));
+	public static function build_query_args(array $instance, int $paged = 1): array {
-		$orderby = sanitize_key((string) ($instance['orderby'] ?? 'date'));
+		$count    = max(1, min(30, (int) ($instance['count'] ?? 8)));
-		$style   = sanitize_key((string) ($instance['style'] ?? 'mini'));
+		$orderby  = sanitize_key((string) ($instance['orderby'] ?? 'date'));
 		$plate_id = (int) ($instance['plate_id'] ?? 0);
-		$current_plate = !empty($instance['current_plate']);
-
-		if ($current_plate) {
-			$resolved = $this->resolve_current_plate_id();
-			if ($resolved <= 0) {
-				return;
-			}
-			$plate_id = $resolved;
-		}
 
 		$query = [
 			'post_type'      => 'aksrt_forum_topic',
 			'post_status'    => 'publish',
 			'posts_per_page' => $count,
+			'paged'          => max(1, $paged),
 			'order'          => 'DESC',
 		];
 
@@ -59,35 +51,41 @@ class WidgetForumTopicLists extends \WP_Widget {
 			case 'modified':
 				$query['orderby'] = 'modified';
 				break;
+			case 'essence':
+				$query['meta_query'] = [[
+					'key'   => '_aksrt_essence',
+					'value' => '1',
+				]];
+				$query['orderby'] = 'date';
+				break;
 			default:
 				$query['orderby'] = 'date';
 		}
 
 		if ($plate_id > 0) {
-			$query['meta_query'] = [[
+			$query['meta_query'] = array_values(array_filter(array_merge(
-				'key'   => '_aksrt_plate_id',
+				isset($query['meta_query']) ? $query['meta_query'] : [],
-				'value' => $plate_id,
+				[[
-			]];
+					'key'   => '_aksrt_plate_id',
+					'value' => $plate_id,
+				]]
+			)));
 		}
 
-		$q = new \WP_Query($query);
+		return $query;
+	}
+
+	public static function render_items_html(\WP_Query $q, string $style = 'mini'): string {
 		if (!$q->have_posts()) {
-			wp_reset_postdata();
+			return '';
-			return;
 		}
-
-		echo $args['before_widget']; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
-		$title = apply_filters('widget_title', (string) ($instance['title'] ?? ''), $instance, $this->id_base);
-		if ($title !== '') {
-			echo $args['before_title'] . esc_html($title) . $args['after_title']; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
-		}
-
 		$list_class = $style === 'detail' ? 'aksrt-ftopic-list is-detail' : 'aksrt-ftopic-list is-mini';
+		ob_start();
 		echo '<ul class="' . esc_attr($list_class) . '">';
 		while ($q->have_posts()) {
 			$q->the_post();
 			$views = (int) get_post_meta(get_the_ID(), '_aksrt_views', true);
-			echo '<li class="aksrt-ftopic-list__item">';
+			echo '<li class="aksrt-ftopic-list__item ajax-item">';
 			echo '<a class="aksrt-ftopic-list__link" href="' . esc_url(get_permalink()) . '">' . esc_html(get_the_title()) . '</a>';
 			if ($style === 'detail') {
 				echo '<div class="aksrt-ftopic-list__meta">';
@@ -102,6 +100,96 @@ class WidgetForumTopicLists extends \WP_Widget {
 		}
 		echo '</ul>';
 		wp_reset_postdata();
+		return (string) ob_get_clean();
+	}
+
+	/**
+	 * @return array{html:string,paginate_html:string,has_more:bool,page:int,max_pages:int,total:int}
+	 */
+	public static function query_payload(array $instance, int $page = 1): array {
+		$page  = max(1, $page);
+		$style = sanitize_key((string) ($instance['style'] ?? 'mini'));
+		$paginate = sanitize_key((string) ($instance['paginate'] ?? 'ajax'));
+		$q     = new \WP_Query(self::build_query_args($instance, $page));
+		$html  = self::render_items_html($q, $style);
+		if ($html === '' && $page === 1) {
+			$html = function_exists('aksrt_get_ajax_null')
+				? aksrt_get_ajax_null(__('暂无内容', 'aksrt'))
+				: '<p class="aksrt-ftopic-list__empty ajax-item">' . esc_html__('暂无内容', 'aksrt') . '</p>';
+		}
+		$max_pages = max(1, (int) $q->max_num_pages);
+		$total     = (int) $q->found_posts;
+		$has_more  = $page < $max_pages;
+		$paginate_html = '';
+		if ($paginate === 'ajax' && $has_more) {
+			$next = add_query_arg(
+				array_filter([
+					'page'     => $page + 1,
+					'count'    => max(1, min(30, (int) ($instance['count'] ?? 8))),
+					'orderby'  => sanitize_key((string) ($instance['orderby'] ?? 'date')),
+					'style'    => $style,
+					'plate_id' => (int) ($instance['plate_id'] ?? 0),
+					'paginate' => 'ajax',
+				]),
+				rest_url('aksrt/v1/forum/frontend/widgets/topics')
+			);
+			$paginate_html = function_exists('aksrt_get_ajax_next_paginate')
+				? aksrt_get_ajax_next_paginate($total, $page, max(1, (int) ($instance['count'] ?? 8)), $next)
+				: '<div class="text-center theme-pagination ajax-pag"><div class="next-page ajax-next"><a href="' . esc_url($next) . '">' . esc_html__('加载更多', 'aksrt') . '</a></div></div>';
+		} else {
+			$paginate_html = '<div class="ajax-pag hide"><div class="next-page ajax-next"><a href="#"></a></div></div>';
+		}
+		return [
+			'html'          => $html,
+			'paginate_html' => $paginate_html,
+			'has_more'      => $has_more,
+			'page'          => $page,
+			'max_pages'     => $max_pages,
+			'total'         => $total,
+		];
+	}
+
+	public function widget($args, $instance): void {
+		if (!post_type_exists('aksrt_forum_topic')) {
+			return;
+		}
+
+		$count   = max(1, min(30, (int) ($instance['count'] ?? 8)));
+		$orderby = sanitize_key((string) ($instance['orderby'] ?? 'date'));
+		$style   = sanitize_key((string) ($instance['style'] ?? 'mini'));
+		$plate_id = (int) ($instance['plate_id'] ?? 0);
+		$current_plate = !empty($instance['current_plate']);
+		$paginate = sanitize_key((string) ($instance['paginate'] ?? 'ajax'));
+
+		if ($current_plate) {
+			$resolved = $this->resolve_current_plate_id();
+			if ($resolved <= 0) {
+				return;
+			}
+			$plate_id = $resolved;
+		}
+
+		$instance['count'] = $count;
+		$instance['orderby'] = $orderby;
+		$instance['style'] = $style;
+		$instance['plate_id'] = $plate_id;
+		$instance['paginate'] = $paginate;
+
+		$payload = self::query_payload($instance, 1);
+		$rest = rest_url('aksrt/v1/forum/frontend/widgets/topics');
+
+		echo $args['before_widget']; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
+		$title = apply_filters('widget_title', (string) ($instance['title'] ?? ''), $instance, $this->id_base);
+		if ($title !== '') {
+			echo $args['before_title'] . esc_html($title) . $args['after_title']; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
+		}
+
+		echo '<div class="aksrt-forum-topic-widget" data-aksrt-forum-topic-widget>';
+		echo '<div class="ajaxpager" data-aksrt-ajaxpager data-aksrt-ajax-url="' . esc_url($rest) . '">';
+		echo $payload['html']; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
+		echo $payload['paginate_html']; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
+		echo '<div class="post_ajax_loader" data-aksrt-ajax-loader data-aksrt-ajax-loader-hide hidden></div>';
+		echo '</div></div>';
 
 		echo $args['after_widget']; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
 	}
@@ -119,58 +207,74 @@ class WidgetForumTopicLists extends \WP_Widget {
 	}
 
 	public function form($instance): void {
+		$defaults = [
+			'title'         => __('帖子列表', 'aksrt'),
+			'count'         => 8,
+			'orderby'       => 'date',
+			'style'         => 'mini',
+			'plate_id'      => 0,
+			'current_plate' => 0,
+			'paginate'      => 'ajax',
+		];
+		$instance = wp_parse_args($instance, $defaults);
 		?>
 		<p>
 			<label><?php esc_html_e('标题', 'aksrt'); ?>
-				<input class="widefat" type="text" name="<?php echo esc_attr($this->get_field_name('title')); ?>" value="<?php echo esc_attr((string) ($instance['title'] ?? __('最新帖子', 'aksrt'))); ?>">
+				<input class="widefat" type="text" name="<?php echo esc_attr($this->get_field_name('title')); ?>" value="<?php echo esc_attr((string) $instance['title']); ?>">
 			</label>
 		</p>
 		<p>
 			<label><?php esc_html_e('数量', 'aksrt'); ?>
-				<input class="tiny-text" type="number" min="1" max="30" name="<?php echo esc_attr($this->get_field_name('count')); ?>" value="<?php echo esc_attr((string) ((int) ($instance['count'] ?? 8))); ?>">
+				<input class="tiny-text" type="number" min="1" max="30" name="<?php echo esc_attr($this->get_field_name('count')); ?>" value="<?php echo esc_attr((string) $instance['count']); ?>">
 			</label>
 		</p>
 		<p>
 			<label><?php esc_html_e('排序', 'aksrt'); ?>
-				<select name="<?php echo esc_attr($this->get_field_name('orderby')); ?>">
+				<select class="widefat" name="<?php echo esc_attr($this->get_field_name('orderby')); ?>">
-					<option value="date" <?php selected(($instance['orderby'] ?? 'date'), 'date'); ?>><?php esc_html_e('发布时间', 'aksrt'); ?></option>
+					<option value="date" <?php selected($instance['orderby'], 'date'); ?>><?php esc_html_e('最新', 'aksrt'); ?></option>
-					<option value="views" <?php selected(($instance['orderby'] ?? ''), 'views'); ?>><?php esc_html_e('浏览量', 'aksrt'); ?></option>
+					<option value="views" <?php selected($instance['orderby'], 'views'); ?>><?php esc_html_e('热门', 'aksrt'); ?></option>
-					<option value="comments" <?php selected(($instance['orderby'] ?? ''), 'comments'); ?>><?php esc_html_e('评论数', 'aksrt'); ?></option>
+					<option value="comments" <?php selected($instance['orderby'], 'comments'); ?>><?php esc_html_e('评论', 'aksrt'); ?></option>
-					<option value="modified" <?php selected(($instance['orderby'] ?? ''), 'modified'); ?>><?php esc_html_e('更新时间', 'aksrt'); ?></option>
+					<option value="essence" <?php selected($instance['orderby'], 'essence'); ?>><?php esc_html_e('精华', 'aksrt'); ?></option>
+					<option value="modified" <?php selected($instance['orderby'], 'modified'); ?>><?php esc_html_e('更新', 'aksrt'); ?></option>
 				</select>
 			</label>
 		</p>
 		<p>
 			<label><?php esc_html_e('样式', 'aksrt'); ?>
-				<select name="<?php echo esc_attr($this->get_field_name('style')); ?>">
+				<select class="widefat" name="<?php echo esc_attr($this->get_field_name('style')); ?>">
-					<option value="mini" <?php selected(($instance['style'] ?? 'mini'), 'mini'); ?>><?php esc_html_e('紧凑', 'aksrt'); ?></option>
+					<option value="mini" <?php selected($instance['style'], 'mini'); ?>><?php esc_html_e('迷你', 'aksrt'); ?></option>
-					<option value="detail" <?php selected(($instance['style'] ?? ''), 'detail'); ?>><?php esc_html_e('详情', 'aksrt'); ?></option>
+					<option value="detail" <?php selected($instance['style'], 'detail'); ?>><?php esc_html_e('详情', 'aksrt'); ?></option>
 				</select>
 			</label>
 		</p>
 		<p>
-			<label><?php esc_html_e('限定版块 ID（0=全部）', 'aksrt'); ?>
+			<label><?php esc_html_e('版块 ID', 'aksrt'); ?>
-				<input class="tiny-text" type="number" min="0" name="<?php echo esc_attr($this->get_field_name('plate_id')); ?>" value="<?php echo esc_attr((string) ((int) ($instance['plate_id'] ?? 0))); ?>">
+				<input class="tiny-text" type="number" min="0" name="<?php echo esc_attr($this->get_field_name('plate_id')); ?>" value="<?php echo esc_attr((string) $instance['plate_id']); ?>">
 			</label>
 		</p>
 		<p>
-			<label><input type="checkbox" name="<?php echo esc_attr($this->get_field_name('current_plate')); ?>" value="1" <?php checked(!empty($instance['current_plate'])); ?>> <?php esc_html_e('仅当前版块（版块/帖子页）', 'aksrt'); ?></label>
+			<label><input type="checkbox" name="<?php echo esc_attr($this->get_field_name('current_plate')); ?>" value="1" <?php checked(!empty($instance['current_plate'])); ?>> <?php esc_html_e('跟随当前版块', 'aksrt'); ?></label>
+		</p>
+		<p>
+			<label><?php esc_html_e('分页', 'aksrt'); ?>
+				<select class="widefat" name="<?php echo esc_attr($this->get_field_name('paginate')); ?>">
+					<option value="ajax" <?php selected($instance['paginate'], 'ajax'); ?>><?php esc_html_e('AJAX', 'aksrt'); ?></option>
+					<option value="none" <?php selected($instance['paginate'], 'none'); ?>><?php esc_html_e('无', 'aksrt'); ?></option>
+				</select>
+			</label>
 		</p>
 		<?php
 	}
 
 	public function update($new_instance, $old_instance): array {
-		$orderby = sanitize_key((string) ($new_instance['orderby'] ?? 'date'));
-		if (!in_array($orderby, ['date', 'views', 'comments', 'modified'], true)) {
-			$orderby = 'date';
-		}
 		return [
 			'title'         => sanitize_text_field((string) ($new_instance['title'] ?? '')),
 			'count'         => max(1, min(30, (int) ($new_instance['count'] ?? 8))),
-			'orderby'       => $orderby,
+			'orderby'       => sanitize_key((string) ($new_instance['orderby'] ?? 'date')),
-			'style'         => ($new_instance['style'] ?? '') === 'detail' ? 'detail' : 'mini',
+			'style'         => sanitize_key((string) ($new_instance['style'] ?? 'mini')),
 			'plate_id'      => max(0, (int) ($new_instance['plate_id'] ?? 0)),
 			'current_plate' => !empty($new_instance['current_plate']) ? 1 : 0,
+			'paginate'      => sanitize_key((string) ($new_instance['paginate'] ?? 'ajax')),
 		];
 	}
 }