文章分类

除另行注明外，本页 API 自 Halo 2.0.0 起可用。

getByName(name)

categoryFinder.getByName(name);

配合分类选择器使用

通常建议配合主题设置和分类选择器使用，让用户自行选择所需的分类。

描述

根据 metadata.name 获取文章分类。

参数

name:string - 分类的唯一标识 metadata.name。

返回值

#CategoryVo

示例

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

getByNames(names)

categoryFinder.getByNames(names);

配合分类选择器使用

通常建议配合主题设置和分类选择器使用，让用户自行选择所需的分类。

描述

根据一组 metadata.name 获取文章分类。

参数

names:List<string> - 分类的唯一标识 metadata.name 的集合。

返回值

List<#CategoryVo>

示例

<div
  th:with="categories = ${categoryFinder.getByNames({'category-foo', 'category-bar'})}"
>
  <a
    th:each="category : ${categories}"
    th:href="@{${category.status.permalink}}"
    th:text="${category.spec.displayName}"
  ></a>
</div>

list(page,size)

categoryFinder.list(page, size);

描述

根据分页参数获取分类列表。

参数

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

返回值

#ListResult<CategoryVo>

示例

<ul th:with="categories = ${categoryFinder.list(1,10)}">
  <li th:each="category : ${categories.items}">
    <a
      th:href="@{${category.status.permalink}}"
      th:text="${category.spec.displayName}"
    ></a>
  </li>
</ul>

listAll()

categoryFinder.listAll();

描述

获取所有文章分类。

参数

无

返回值

List<#CategoryVo>

示例

<ul th:with="categories = ${categoryFinder.listAll()}">
  <li th:each="category : ${categories}">
    <a
      th:href="@{${category.status.permalink}}"
      th:text="${category.spec.displayName}"
    ></a>
  </li>
</ul>

listAsTree()

categoryFinder.listAsTree();

描述

获取所有文章分类的多层级结构。

参数

无

返回值

List<#CategoryTreeVo>

示例

<div th:with="categories = ${categoryFinder.listAsTree()}">
  <ul>
    <li
      th:replace="~{modules/category-tree :: single(categories=${categories})}"
    />
  </ul>
</div>

/templates/category-tree.html

<ul th:fragment="next (categories)">
  <li th:fragment="single (categories)" th:each="category : ${categories}">
    <a th:href="@{${category.status.permalink}}">
      <span th:text="${category.spec.displayName}"> </span>
    </a>
    <th:block th:if="${not #lists.isEmpty(category.children)}">
      <th:block
        th:replace="~{modules/category-tree :: next (categories=${category.children})}"
      ></th:block>
    </th:block>
  </li>
</ul>

listAsTree(name)

categoryFinder.listAsTree(name);

描述

根据分类的 metadata.name 获取以该分类为根节点的多层级结构。返回列表的第一个元素是指定的根分类，其 children 包含直接子分类；分类不存在时返回空列表。

引入版本：2.1.0

参数

name:string - 根分类的唯一标识 metadata.name。

返回值

List<#CategoryTreeVo>

示例

<div th:with="categories = ${categoryFinder.listAsTree('category-foo')}">
  <ul th:if="${not #lists.isEmpty(categories)}">
    <li th:each="child : ${categories[0].children}">
      <a
        th:href="@{${child.status.permalink}}"
        th:text="${child.spec.displayName}"
      ></a>
    </li>
  </ul>
</div>

从 Halo 2.26.0 开始，分类层级以 Category.spec.parent 为准。不要通过已弃用的 Category.spec.children 获取子分类；该字段仅为旧数据兼容而保留，不会随层级调整继续更新。

getParentByName(name)

categoryFinder.getParentByName(name);

描述

根据分类的 metadata.name 获取其直接父分类。当前分类没有有效父分类时返回空值。

引入版本：2.12.0

参数

name:string - 当前分类的唯一标识 metadata.name。

返回值

#CategoryVo

示例

<div th:with="parent = ${categoryFinder.getParentByName('category-child')}">
  <a
    th:if="${parent != null}"
    th:href="@{${parent.status.permalink}}"
    th:text="${parent.spec.displayName}"
  ></a>
</div>

getBreadcrumbs(name)

categoryFinder.getBreadcrumbs("category-foo");

描述

获取分类树结构的路径节点，可以通过此方法来构建面包屑导航。

引入版本：2.17.0

参数

name:string - 分类的唯一标识 metadata.name，必填。

返回值

List<#CategoryVo>

示例

<div>
  <th:block
    th:each="category,stats : ${categoryFinder.getBreadcrumbs(category.metadata?.name)}"
  >
    <a
      th:href="@{${category.status.permalink}}"
      th:text="${category.spec.displayName}"
    ></a>
    <span th:if="${!stats.last}">/</span>
  </th:block>
</div>

类型定义

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, // 排序字段
    "parent": "string", // 父分类的 metadata.name，根分类为空
    "children": [
      // 已弃用，仅用于兼容旧数据，不再表示当前分类层级
      "string",
    ],
  },
  "status": {
    "permalink": "string", // 固定链接
  },
  "postCount": 0, // 文章数量
}

ListResult<CategoryVo>

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

#CategoryVo

CategoryTreeVo

{
  "metadata": {
    "name": "string", // 唯一标识
    "labels": {
      "additionalProp1": "string",
    },
    "annotations": {
      "additionalProp1": "string",
    },
    "creationTimestamp": "2022-11-20T14:18:49.230Z", // 创建时间
  },
  "spec": {
    "displayName": "string", // 显示名称
    "slug": "string", // 别名，通常用于生成 status.permalink
    "description": "string", // 描述
    "cover": "string", // 封面图
    "template": "string", // 自定义渲染模板名称
    "priority": 0, // 排序字段
    "parent": "string", // 父分类的 metadata.name，根分类为空
    "children": [
      // 已弃用，仅用于兼容旧数据，不再表示当前分类层级
      "string",
    ],
  },
  "status": {
    "permalink": "string", // 固定链接
  },
  "children": "List<#CategoryTreeVo>", // 下级分类，CategoryTreeVo 的集合
  "parentName": "string",
  "postCount": 0, // 文章数量
}

#CategoryTreeVo

文章分类#

#getByName(name)

#描述

#参数

#返回值

#示例

#getByNames(names)

#描述

#参数

#返回值

#示例

#list(page,size)

#描述

#参数

#返回值

#示例

#listAll()

#描述

#参数

#返回值

#示例

#listAsTree()

#描述

#参数

#返回值

#示例

#listAsTree(name)

#描述

#参数

#返回值

#示例

#getParentByName(name)

#描述

#参数

#返回值

#示例

#getBreadcrumbs(name)

#描述

#参数

#返回值

#示例

#类型定义

#CategoryVo

#ListResult<CategoryVo>

#CategoryTreeVo

文章分类

getByName(name)

描述

参数

返回值

示例

getByNames(names)

描述

参数

返回值

示例

list(page,size)

描述

参数

返回值

示例

listAll()

描述

参数

返回值

示例

listAsTree()

描述

参数

返回值

示例

listAsTree(name)

描述

参数

返回值

示例

getParentByName(name)

描述

参数

返回值

示例

getBreadcrumbs(name)

描述

参数

返回值

示例

类型定义

CategoryVo

ListResult<CategoryVo>

CategoryTreeVo