Typecho 置顶文章的一种更干净的实现方式

use Typecho\Db;
use Typecho\Widget;

/**
 * 解析置顶文章的 CID 列表
 *
 * 从主题选项读取逗号分隔的 CID 字符串，过滤非数字值，并缓存结果。
 *
 * @param string $optionKey 主题选项键名（默认 'sticky'）
 * @return array<int,string> 置顶文章 CID 索引数组
 */
function parse_sticky_cids(string $optionKey = 'sticky'): array
{
    static $cache = [];
    if (array_key_exists($optionKey, $cache)) {
        return $cache[$optionKey];
    }

    $options = Widget::widget('Widget_Options');
    $raw = (string) $options->{$optionKey};
    if ($raw === '') {
        return $cache[$optionKey] = [];
    }

    $cids = array_values(array_filter(
        array_map('trim', explode(',', $raw)),
        'is_numeric'
    ));
    return $cache[$optionKey] = $cids;
}

/**
 * 判断给定的 CID 是否为置顶文章
 *
 * @param int|string $cid 文章 CID
 * @return bool
 */
function is_sticky_cid($cid): bool
{
    return in_array((string) $cid, parse_sticky_cids(), true);
}

/**
 * 应用置顶文章修正到归档对象
 *
 * 仅对首页生效：
 * - 第一页顶部插入置顶文章，普通文章补足到 pageSize
 * - 第二页起使用修正后的偏移量，保证每页 pageSize 条
 * - 置顶文章不计入总页数
 *
 * 用法：在主题 index.php 的文章循环前调用一次即可
 *      <?php apply_sticky_pagination($this); ?>
 *
 * @param \Widget\Archive $archive   当前归档对象
 * @param string          $optionKey 置顶配置键名（默认 'sticky'）
 * @return void
 */
function apply_sticky_pagination(\Widget\Archive $archive, string $optionKey = 'sticky'): void
{
    if (!$archive->is('index')) {
        return;
    }

    $stickyCids  = parse_sticky_cids($optionKey);
    $stickyCount = count($stickyCids);
    if ($stickyCount === 0) {
        return;
    }

    $pageSize    = (int) $archive->parameter->pageSize;
    $currentPage = $archive->getCurrentPage();
    $db          = Db::get();
    $now         = (int) Widget::widget('Widget_Options')->time;
    $user        = Widget::widget('Widget_User');

    // 与 Widget_Archive 的 index 归档保持一致：仅展示公开文章，登录用户额外展示自己的私密文章
    $applyStatus = static function ($select) use ($user) {
        if ($user->hasLogin()) {
            return $select->where(
                'table.contents.status = ? OR (table.contents.status = ? AND table.contents.authorId = ?)',
                'publish',
                'private',
                $user->uid
            );
        }
        return $select->where('table.contents.status = ?', 'publish');
    };

    $selectSticky = $archive->select()->where('type = ?', 'post');
    $selectSticky = $applyStatus($selectSticky);
    $selectSticky->where('table.contents.created < ?', $now);

    $selectNormal = $archive->select()->where('type = ?', 'post');
    $selectNormal = $applyStatus($selectNormal);
    $selectNormal->where('table.contents.created < ?', $now);

    foreach ($stickyCids as $i => $cid) {
        if ($i === 0) {
            $selectSticky->where('table.contents.cid = ?', $cid);
        } else {
            $selectSticky->orWhere('table.contents.cid = ?', $cid);
        }
        $selectNormal->where('table.contents.cid != ?', $cid);
    }

    // 清空归档列队，准备重新压入（stack/length/row 为受保护属性，需用反射写入）
    reset_archive_stack($archive);

    $stickyRows = $db->fetchAll($selectSticky);
    $orderMap   = array_flip(array_map('intval', $stickyCids));
    usort($stickyRows, static function ($a, $b) use ($orderMap): int {
        return ($orderMap[(int) ($a['cid'] ?? 0)] ?? PHP_INT_MAX)
             - ($orderMap[(int) ($b['cid'] ?? 0)] ?? PHP_INT_MAX);
    });

    if ($currentPage === 1) {
        foreach ($stickyRows as $stickyPost) {
            $archive->push($stickyPost);
        }
        $normalLimit  = max(0, $pageSize - $stickyCount);
        $normalOffset = 0;
    } else {
        $normalLimit  = $pageSize;
        $normalOffset = ($currentPage - 2) * $pageSize + ($pageSize - $stickyCount);
    }

    $normalPosts = $db->fetchAll(
        $selectNormal
            ->order('table.contents.created', Db::SORT_DESC)
            ->limit($normalLimit)
            ->offset($normalOffset)
    );
    foreach ($normalPosts as $post) {
        $archive->push($post);
    }

    $archive->setTotal(max(0, $archive->getTotal() - $stickyCount));
}

/**
 * 清空归档对象的内部数据堆栈
 *
 * stack/length/row 为 Widget 受保护属性，从主题中直接赋值会走 __set，
 * 导致原始堆栈未被真正清空，从而出现文章重复。这里使用反射直接写入真实属性。
 *
 * @param \Widget\Archive $archive 当前归档对象
 */
function reset_archive_stack(\Widget\Archive $archive): void
{
    $reflection = new ReflectionClass($archive);

    $rowProp = $reflection->getProperty('row');
    $rowProp->setValue($archive, []);

    $stackProp = $reflection->getProperty('stack');
    $stackProp->setValue($archive, []);

    $lengthProp = $reflection->getProperty('length');
    $lengthProp->setValue($archive, 0);
}

$sticky = new \Typecho\Widget\Helper\Form\Element\Text(
    'sticky',
    NULL,
    NULL,
    _t('置顶文章 CID'),
    _t('填写要置顶的文章 CID，多个用英文逗号分隔，如：1,5,8')
);
$form->addInput($sticky);

<?php apply_sticky_pagination($this); ?>

//开始循环
<?php while ($this->next()): ?>
<?php endwhile; ?>

//应用置顶文章修正
<?php apply_sticky_pagination($this); ?>

<div class="post-list">

    <?php while ($this->next()): ?>

        <?php if (is_sticky_cid($this->cid)): ?>

            <!-- ========== 置顶文章 ========== -->
            <article class="post-item post-sticky">
                <div class="sticky-badge">置顶</div>
                <h2 class="post-title">
                    <a href="<?php $this->permalink(); ?>"><?php $this->title(); ?></a>
                </h2>
                    <p class="post-excerpt"><?php $this->excerpt(120); ?></p>
            </article>

        <?php else: ?>

            <!-- ========== 普通文章 ========== -->
            <article class="post-item">
                <div class="post-main">
                    <h2 class="post-title">
                        <a href="<?php $this->permalink(); ?>"><?php $this->title(); ?></a>
                    </h2>
                    <p class="post-excerpt"><?php $this->excerpt(120); ?></p>
            </article>

        <?php endif; ?>

    <?php endwhile; ?>

</div>