Document pinned filtering for PostFinder list

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` 选项支持图标和描述

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'}
 })}">
   <li th:each="post : ${posts.items}">