From e4d4fc846eb613f3525b6944cabe5f9bb9e313c8 Mon Sep 17 00:00:00 2001 From: Ryan Wang Date: Fri, 10 Jul 2026 22:02:38 +0800 Subject: [PATCH] Document pinned filtering for PostFinder list --- docs/developer-guide/theme/api-changelog.md | 4 ++++ docs/developer-guide/theme/finder-apis/post.md | 7 +++++-- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/developer-guide/theme/api-changelog.md b/docs/developer-guide/theme/api-changelog.md index 2da8a277..297343ee 100644 --- a/docs/developer-guide/theme/api-changelog.md +++ b/docs/developer-guide/theme/api-changelog.md @@ -9,6 +9,10 @@ description: 记录每一个版本的主题 API 变更记录，方便开发者 在 2.26.0 中，主题可以通过 `templates/layout.html` 提供 `html(head, content)` 片段，让插件前台页面复用当前主题的页面外壳。Halo 会在主题安装、更新或重载后检查这个模板，并通过 `Theme.status.pageLayout` 暴露 `SUPPORTED`、`MISSING` 或 `INVALID` 状态；未适配或校验异常时，使用布局契约的插件页面会回退到 Halo 内置布局。详细文档可查阅：[页面布局契约](../../developer-guide/theme/page-layout.md)。 +### 文章 Finder API > `list({...})` 支持按置顶状态筛选 + +在 2.26.0 中，文章 Finder API 的 `list({...})` 方法新增了可选的 `pinned` 参数。设置为 `true` 时仅返回置顶文章，设置为 `false` 时仅返回非置顶文章；不传时保持原有查询行为。详细文档可查阅：[文章 Finder API#list](../../developer-guide/theme/finder-apis/post.md#list)。 + ## 2.25.0 ### 表单定义 > `select` 选项支持图标和描述 diff --git a/docs/developer-guide/theme/finder-apis/post.md b/docs/developer-guide/theme/finder-apis/post.md index c49def61..2d63b606 100644 --- a/docs/developer-guide/theme/finder-apis/post.md +++ b/docs/developer-guide/theme/finder-apis/post.md @@ -217,13 +217,14 @@ postFinder.list({ tagName: 'fake-tag', categoryName: 'fake-category', ownerName: 'fake-owner', + pinned: true, sort: {'spec.publishTime,desc', 'metadata.creationTimestamp,asc'} }); ``` ### 描述 -统一参数的文章列表查询方法，支持分页、标签、分类、创建者、排序等参数，且均为可选参数。 +统一参数的文章列表查询方法，支持分页、标签、分类、创建者、置顶状态、排序等参数，且均为可选参数。 可以使用此方法来代替 `list(page, size)`、`listByCategory(page, size, categoryName)`、`listByTag(page, size, tag)`、`listByOwner(page, size, owner)` 方法。 @@ -234,7 +235,8 @@ postFinder.list({ 3. `tagName:string` - 标签唯一标识 `metadata.name` 4. `categoryName:string` - 分类唯一标识 `metadata.name` 5. `ownerName:string` - 创建者用户名 `name` -6. `sort:string[]` - 排序字段，格式为 `字段名,排序方式`，排序方式可选值为 `asc` 或 `desc`，如 `spec.publishTime,desc`，传递时需要使用 `{}` 形式并用逗号分隔表示数组。 +6. `pinned:boolean` - 置顶状态，`true` 仅返回置顶文章，`false` 仅返回非置顶文章；不传时不按置顶状态筛选 +7. `sort:string[]` - 排序字段，格式为 `字段名,排序方式`，排序方式可选值为 `asc` 或 `desc`，如 `spec.publishTime,desc`，传递时需要使用 `{}` 形式并用逗号分隔表示数组。 ### 返回值 @@ -249,6 +251,7 @@ postFinder.list({ tagName: 'fake-tag', categoryName: 'fake-category', ownerName: 'fake-owner', + pinned: true, sort: {'spec.publishTime,desc', 'metadata.creationTimestamp,asc'} })}">