版本：2.18

文章

getByName(postName)

postFinder.getByName(postName);

描述

根据 metadata.name 获取文章。

参数

postName:string - 文章的唯一标识 metadata.name。

返回值

#PostVo

示例

<div th:with="post = ${postFinder.getByName('post-foo')}">
  <a th:href="@{${post.status.permalink}}" th:text="${post.spec.title}"></a>
</div>

content(postName)

postFinder.content(postName);

描述

根据文章的 metadata.name 单独获取文章内容。

参数

postName:string - 文章的唯一标识 metadata.name。

返回值

#ContentVo

示例

<div th:with="content = ${postFinder.content('post-foo')}">
  <div th:utext="${content.content}"></div>
</div>

cursor(postName)

postFinder.cursor(postName);

描述

根据文章的 metadata.name 获取相邻的文章（上一篇 / 下一篇）。

参数

postName:string - 文章的唯一标识 metadata.name。

返回值

#NavigationPostVo

示例

/templates/post.html
<div th:with="postCursor = ${postFinder.cursor(post.metadata.name)}">
  <a
    th:if="${postCursor.hasPrevious()}"
    th:href="@{${postCursor.previous.status.permalink}}"
  >
    <span th:text="${postCursor.previous.spec.title}"></span>
  </a>
  <a
    th:if="${postCursor.hasNext()}"
    th:href="@{${postCursor.next.status.permalink}}"
  >
    <span th:text="${postCursor.next.spec.title}"></span>
  </a>
</div>

listAll()

postFinder.listAll();

描述

获取所有文章。

参数

无

返回值

List<#ListedPostVo>

示例

<ul th:with="posts = ${postFinder.listAll()}">
  <li th:each="post : ${posts}">
    <a th:href="@{${post.status.permalink}}" th:text="${post.spec.title}"></a>
  </li>
</ul>

list(page,size)

postFinder.list(page, size);

描述

根据分页参数获取文章列表。

参数

page:int - 分页页码，从 1 开始
size:int - 分页条数

返回值

#ListResult<ListedPostVo>

示例

<ul th:with="posts = ${postFinder.list(1,10)}">
  <li th:each="post : ${posts.items}">
    <a th:href="@{${post.status.permalink}}" th:text="${post.spec.title}"></a>
  </li>
</ul>

listByCategory(page,size,categoryName)

postFinder.listByCategory(page, size, categoryName);

描述

根据分类标识和分页参数获取文章列表。

参数

page:int - 分页页码，从 1 开始
size:int - 分页条数
categoryName:string - 文章分类唯一标识 metadata.name

返回值

#ListResult<ListedPostVo>

示例

<ul th:with="posts = ${postFinder.listByCategory(1,10,'category-foo')}">
  <li th:each="post : ${posts.items}">
    <a th:href="@{${post.status.permalink}}" th:text="${post.spec.title}"></a>
  </li>
</ul>

listByTag(page,size,tag)

postFinder.listByTag(page, size, tag);

描述

根据标签标识和分页参数获取文章列表。

参数

page:int - 分页页码，从 1 开始
size:int - 分页条数
tag:string - 文章分类唯一标识 metadata.name

返回值

#ListResult<ListedPostVo>

示例

<ul th:with="posts = ${postFinder.listByTag(1,10,'tag-foo')}">
  <li th:each="post : ${posts.items}">
    <a th:href="@{${post.status.permalink}}" th:text="${post.spec.title}"></a>
  </li>
</ul>

listByOwner(page,size,owner)

postFinder.listByOwner(page, size, owner);

描述

根据创建者用户名和分页参数获取文章列表。

参数

page:int - 分页页码，从 1 开始
size:int - 分页条数
owner:string - 创建者用户名 name

返回值

#ListResult<ListedPostVo>

示例

<ul th:with="posts = ${postFinder.listByOwner(1,10,'admin')}">
  <li th:each="post : ${posts.items}">
    <a th:href="@{${post.status.permalink}}" th:text="${post.spec.title}"></a>
  </li>
</ul>

archives(page,size)

postFinder.archives(page, size);

描述

根据分页参数获取文章归档列表。

参数

page:int - 分页页码，从 1 开始
size:int - 分页条数

返回值

#ListResult<PostArchiveVo>

示例

<th:block th:with="archives = ${postFinder.archives(1,10)}">
  <th:block th:each="archive : ${archives.items}">
    <h1 th:text="${archive.year}"></h1>
    <ul>
      <th:block th:each="month : ${archive.months}">
        <li th:each="post : ${month.posts}">
          <a th:href="@{${post.status.permalink}}" th:text="${post.spec.title}">
          </a>
        </li>
      </th:block>
    </ul>
  </th:block>
</th:block>

archives(page,size,year)

postFinder.archives(page, size, year);

描述

根据年份和分页参数获取文章归档列表。

参数

page:int - 分页页码，从 1 开始
size:int - 分页条数
year:string - 年份

返回值

#ListResult<PostArchiveVo>

示例

<th:block th:with="archives = ${postFinder.archives(1,10,'2022')}">
  <th:block th:each="archive : ${archives.items}">
    <h1 th:text="${archive.year}"></h1>
    <ul>
      <th:block th:each="month : ${archive.months}">
        <li th:each="post : ${month.posts}">
          <a th:href="@{${post.status.permalink}}" th:text="${post.spec.title}">
          </a>
        </li>
      </th:block>
    </ul>
  </th:block>
</th:block>

archives(page,size,year,month)

postFinder.archives(page, size, year, month);

描述

根据年月和分页参数获取文章归档列表。

参数

page:int - 分页页码，从 1 开始
size:int - 分页条数
year:string - 年份
month:string - 月份

返回值

#ListResult<PostArchiveVo>

示例

<th:block th:with="archives = ${postFinder.archives(1,10,'2022','11')}">
  <th:block th:each="archive : ${archives.items}">
    <h1 th:text="${archive.year}"></h1>
    <ul>
      <th:block th:each="month : ${archive.months}">
        <li th:each="post : ${month.posts}">
          <a th:href="@{${post.status.permalink}}" th:text="${post.spec.title}">
          </a>
        </li>
      </th:block>
    </ul>
  </th:block>
</th:block>

类型定义

CategoryVo

CategoryVo
{
  "metadata": {
    "name": "string",                                   // 唯一标识
    "labels": {
      "additionalProp1": "string"
    },
    "annotations": {
      "additionalProp1": "string"
    },
    "creationTimestamp": "2022-11-20T13:06:38.512Z",    // 创建时间
  },
  "spec": {
    "displayName": "string",                            // 显示名称
    "slug": "string",                                   // 别名，通常用于生成 status.permalink
    "description": "string",                            // 描述
    "cover": "string",                                  // 封面图
    "template": "string",                               // 自定义渲染模板名称
    "priority": 0,                                      // 排序字段
    "children": [                                       // 下级分类，分类的 metadata.name 集合
      "string"
    ]
  },
  "status": {
    "permalink": "string",                              // 固定链接
  },
  "postCount": 0                                        // 文章数量
}

TagVo

TagVo
{
  "metadata": {
    "name": "string",                                   // 唯一标识
    "labels": {
      "additionalProp1": "string"
    },
    "annotations": {
      "additionalProp1": "string"
    },
    "creationTimestamp": "2022-11-20T13:06:38.512Z",    // 创建时间
  },
  "spec": {
    "displayName": "string",                            // 显示名称
    "slug": "string",                                   // 别名，通常用于生成 status.permalink
    "color": "#F9fEB1",                                 // 背景颜色
    "cover": "string"                                   // 封面图
  },
  "status": {
    "permalink": "string",                              // 固定链接
  },
  "postCount": 0                                        // 文章数量
}

ContributorVo

ContributorVo
{
  "name": "string",                                   // 用户名
  "displayName": "string",                            // 显示名称
  "avatar": "string",                                 // 头像
  "bio": "string",                                    // 描述
  "permalink": "string",                              // 作者的文章归档页面链接
  "metadata": {
    "name": "string",                                 // 唯一标识
    "labels": {
      "additionalProp1": "string"
    },
    "annotations": {
      "additionalProp1": "string"
    },
    "creationTimestamp": "2022-11-20T13:06:38.512Z",  // 创建时间
  }
}

PostVo

PostVo
{
  "metadata": {
    "name": "string",                                   // 唯一标识
    "labels": {
      "additionalProp1": "string"
    },
    "annotations": {
      "additionalProp1": "string"
    },
    "creationTimestamp": "2022-11-20T12:45:43.888Z",    // 创建时间
  },
  "spec": {
    "title": "string",                                  // 标题
    "slug": "string",                                   // 别名，通常用于生成 status.permalink
    "releaseSnapshot": "string",
    "headSnapshot": "string",
    "baseSnapshot": "string",
    "owner": "string",                                  // 创建者名称，即 ContributorVo 的 metadata.name，非显示名称
    "template": "string",                               // 自定义渲染模板
    "cover": "string",                                  // 封面图
    "deleted": false,
    "publish": false,
    "publishTime": "2022-11-20T13:06:38.505Z",          // 发布时间
    "pinned": false,                                    // 是否置顶
    "allowComment": true,                               // 是否允许评论
    "visible": "PUBLIC",
    "priority": 0,
    "excerpt": {
      "autoGenerate": true,                             // 是否自动生成摘要
      "raw": "string"                                   // 摘要内容
    },
    "categories": [                                     // 分类的名称集合，即 Category 的 metadata.name 的集合
      "string"
    ],
    "tags": [                                           // 标签的名称集合，即 Tag 的 metadata.name 的集合
      "string"
    ],
    "htmlMetas": [
      {
        "additionalProp1": "string"
      }
    ]
  },
  "status": {
    "permalink": "string",                              // 固定链接
    "excerpt": "string",                                // 最终生成的摘要
    "inProgress": true,
    "lastModifyTime": "2022-11-20T13:06:38.505Z",       // 最后修改时间
    "commentsCount": 0,                                 // 评论数
    "contributors": [                                   // 贡献者名称，Contributor 的 metadata.name 的集合
      "string"
    ]
  },
  "categories": "List<#CategoryVo>",                    // 分类的集合
  "tags": "List<#TagVo>",                               // 标签的集合
  "contributors": "List<#ContributorVo>",               // 贡献者的集合
  "owner": "#ContributorVo",                            // 创建者
  "stats": {
    "visit": 0,                                         // 访问数量
    "upvote": 0,                                        // 点赞数量
    "comment": 0                                        // 评论数量
  },
  "content": "#ContentVo"                               // 内容
}

#CategoryVo
#TagVo
#ContributorVo
#ContentVo

ContentVo

ContentVo
{
  "raw": "string",                                   // 原始文本，一般用于给编辑器使用
  "content": "string"                                // 最终渲染的文本
}

NavigationPostVo

NavigationPostVo
{
  "previous": "#PostVo",                                   // 上一篇文章
  "current": "#PostVo",                                    // 当前文章
  "next": "#PostVo"                                        // 下一篇文章
}

#PostVo

ListedPostVo

ListedPostVo
{
  "metadata": {
    "name": "string",                                   // 唯一标识
    "labels": {
      "additionalProp1": "string"
    },
    "annotations": {
      "additionalProp1": "string"
    },
    "creationTimestamp": "2022-11-20T13:06:38.505Z",    // 创建时间
  },
  "spec": {
    "title": "string",                                  // 标题
    "slug": "string",                                   // 别名，通常用于生成 status.permalink
    "releaseSnapshot": "string",
    "headSnapshot": "string",
    "baseSnapshot": "string",
    "owner": "string",                                  // 创建者名称，即 ContributorVo 的 metadata.name，非显示名称
    "template": "string",                               // 自定义渲染模板
    "cover": "string",                                  // 封面图
    "deleted": false,
    "publish": false,
    "publishTime": "2022-11-20T13:06:38.505Z",          // 发布时间
    "pinned": false,                                    // 是否置顶
    "allowComment": true,                               // 是否允许评论
    "visible": "PUBLIC",
    "priority": 0,
    "excerpt": {
      "autoGenerate": true,                             // 是否自动生成摘要
      "raw": "string"                                   // 摘要内容
    },
    "categories": [                                     // 分类的名称集合，即 Category 的 metadata.name 的集合
      "string"
    ],
    "tags": [                                           // 标签的名称集合，即 Tag 的 metadata.name 的集合
      "string"
    ],
    "htmlMetas": [
      {
        "additionalProp1": "string"
      }
    ]
  },
  "status": {
    "permalink": "string",                              // 固定链接
    "excerpt": "string",                                // 最终生成的摘要
    "inProgress": true,
    "lastModifyTime": "2022-11-20T13:06:38.505Z",       // 最后修改时间
    "commentsCount": 0,                                 // 评论数
    "contributors": [                                   // 贡献者名称，Contributor 的 metadata.name 的集合
      "string"
    ]
  },
  "categories": "List<#CategoryVo>",                    // 分类的集合
  "tags": "List<#TagVo>",                               // 标签的集合
  "contributors": "List<#ContributorVo>",               // 贡献者的集合
  "owner": "#ContributorVo",                            // 创建者
  "stats": {
    "visit": 0,                                         // 访问数量
    "upvote": 0,                                        // 点赞数量
    "comment": 0                                        // 评论数量
  }
}

#CategoryVo
#TagVo
#ContributorVo

ListResult<ListedPostVo>

ListResult<ListedPostVo>
{
  "page": 0,                                   // 当前页码
  "size": 0,                                   // 每页条数
  "total": 0,                                  // 总条数
  "items": "List<#ListedPostVo>",              // 文章列表数据
  "first": true,                               // 是否为第一页
  "last": true,                                // 是否为最后一页
  "hasNext": true,                             // 是否有下一页
  "hasPrevious": true,                         // 是否有上一页
  "totalPages": 0                              // 总页数
}

#ListedPostVo

PostArchiveVo

PostArchiveVo
{
  "year": "string",
  "months": [
    {
      "month": "string",
      "posts": "#ListedPostVo"
    }
  ]
}

#ListedPostVo

ListResult<PostArchiveVo>

ListResult<PostArchiveVo>
{
  "page": 0,                                   // 当前页码
  "size": 0,                                   // 每页条数
  "total": 0,                                  // 总条数
  "items": "List<#PostArchiveVo>",             // 文章归档数据
  "first": true,                               // 是否为第一页
  "last": true,                                // 是否为最后一页
  "hasNext": true,                             // 是否有下一页
  "hasPrevious": true,                         // 是否有上一页
  "totalPages": 0                              // 总页数
}

#PostArchiveVo

getByName(postName)​

描述​

参数​

返回值​

示例​

content(postName)​

描述​

参数​

返回值​

示例​

cursor(postName)​

描述​

参数​

返回值​

示例​

listAll()​

描述​

参数​

返回值​

示例​

list(page,size)​

描述​

参数​

返回值​

示例​

listByCategory(page,size,categoryName)​

描述​

参数​

返回值​

示例​

listByTag(page,size,tag)​

描述​

参数​

返回值​

示例​

listByOwner(page,size,owner)​

描述​

参数​

返回值​

示例​

archives(page,size)​

描述​

参数​

返回值​

示例​

archives(page,size,year)​

描述​

参数​

返回值​

示例​

archives(page,size,year,month)​

描述​

参数​

返回值​

示例​

类型定义​

CategoryVo​

TagVo​

ContributorVo​

PostVo​

ContentVo​

NavigationPostVo​

ListedPostVo​

ListResult<ListedPostVo>​

PostArchiveVo​

ListResult<PostArchiveVo>​

getByName(postName)

描述

参数

返回值

示例

content(postName)

描述

参数

返回值

示例

cursor(postName)

描述

参数

返回值

示例

listAll()

描述

参数

返回值

示例

list(page,size)

描述

参数

返回值

示例

listByCategory(page,size,categoryName)

描述

参数

返回值

示例

listByTag(page,size,tag)

描述

参数

返回值

示例

listByOwner(page,size,owner)

描述

参数

返回值

示例

archives(page,size)

描述

参数

返回值

示例

archives(page,size,year)

描述

参数

返回值

示例

archives(page,size,year,month)

描述

参数

返回值

示例

类型定义

CategoryVo

TagVo

ContributorVo

PostVo

ContentVo

NavigationPostVo

ListedPostVo

ListResult<ListedPostVo>

PostArchiveVo

ListResult<PostArchiveVo>