> For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt.

# API 变更日志

## 2.26.0

### 文章分类 > 层级关系改用 `spec.parent`

从 Halo 2.26.0 开始，文章分类通过子分类的 `spec.parent` 记录层级关系。`spec.children` 已弃用，仅为旧数据兼容而保留，不会随分类层级调整继续更新。主题需要获取分类树或直接子分类时，应使用 [`categoryFinder.listAsTree(name)`](https://docs.halo.run/developer-guide/theme/finder-apis/category.md#listastreename)。

### 导航菜单 > 层级关系改用 `spec.parent`

从 Halo 2.26.0 开始，菜单项通过 `MenuItem.spec.menuName` 归属菜单，并通过 `MenuItem.spec.parent` 记录层级关系。`Menu.spec.menuItems` 和 `MenuItem.spec.children` 已弃用，仅为旧数据兼容而保留。主题应使用 `menuFinder` 返回的 `MenuVo.menuItems` 和 `MenuItemVo.children` 渲染菜单树。详细文档可查阅：[导航菜单 Finder API](https://docs.halo.run/developer-guide/theme/finder-apis/menu.md)。

### 主题支持提供 ESM UI 扩展

主题可以继续复用插件的 `PluginModule` 契约扩展 Console 和 UC。从 Halo 2.26.0 开始，主题 UI provider 支持 ESM、异步 JavaScript 和 CSS 分块，并与插件使用相同的共享运行时依赖和失败隔离机制；已有 IIFE 主题 UI 产物继续兼容。详细文档请参考 [UI 扩展](https://docs.halo.run/developer-guide/theme/ui-plugin.md)。

### 主题目录结构 > 新增页面布局契约

在 2.26.0 中，主题可以通过 `templates/layout.html` 提供 `html(head, content)` 片段，让插件前台页面复用当前主题的页面外壳。Halo 会在主题安装、更新或重载后检查这个模板，并通过 `Theme.status.pageLayout` 暴露 `SUPPORTED`、`MISSING` 或 `INVALID` 状态；未适配或校验异常时，使用布局契约的插件页面会回退到 Halo 内置布局。详细文档可查阅：[页面布局契约](https://docs.halo.run/developer-guide/theme/page-layout.md)。

### 文章 Finder API > `list({...})` 支持按置顶状态筛选

在 2.26.0 中，文章 Finder API 的 `list({...})` 方法新增了可选的 `pinned` 参数。设置为 `true` 时仅返回置顶文章，设置为 `false` 时仅返回非置顶文章；不传时保持原有查询行为。详细文档可查阅：[文章 Finder API#list](https://docs.halo.run/developer-guide/theme/finder-apis/post.md#list)。

## 2.25.0

### 表单定义 > `select` 选项支持图标和描述

在 2.25.0 中，`select` 表单类型的选项对象新增了 `icon` 与 `description` 字段，可在下拉选项中展示图标和辅助说明；使用远程动态数据源时，也可以通过 `requestOption.iconField` 与 `requestOption.descriptionField` 映射响应字段。详细文档可查阅：[表单定义#select](https://docs.halo.run/developer-guide/form-schema.md#select)。

### 主题目录结构 > 新增根目录预览图

在 2.25.0 中，主题可以在根目录提供 `screenshot.png`、`screenshot.jpeg`、`screenshot.jpg` 或 `screenshot.webp` 作为 Console 主题预览图。Halo 会按此顺序识别第一个可读文件，并将访问地址写入 `Theme.status.screenshot`。详细文档可查阅：[目录结构](https://docs.halo.run/developer-guide/theme/structure.md)。

### 模板表达式对象 > 新增 `#halo.matchVersion(constraint)` 方法

在 2.25.0 中，我们为主题模板新增了 `#halo.matchVersion(constraint)` 方法，用于判断当前运行的 Halo 版本是否满足指定的语义化版本范围。主题开发者可以用它为依赖新版 Halo 能力的模板片段添加条件渲染，从而避免仅为局部功能提高整个主题的 `spec.requires` 版本要求。详细文档可查阅：[全局变量#halo.matchVersion](https://docs.halo.run/developer-guide/theme/global-variables.md#halomatchversionconstraint)。

### 文章 Finder API > 新增 `cursorByCategory(postName)` 方法

我们为文章 Finder API 新增了 `cursorByCategory(postName)` 方法，用于获取当前文章主分类下的上一篇 / 下一篇文章。主分类为文章 `spec.categories` 中的第一个分类，且只匹配同一分类，不会包含子分类中的文章。

同时，Public API `GET /apis/api.content.halo.run/v1alpha1/posts/{name}/navigation` 新增了可选的 `scope=category` 查询参数，用于获取同一主分类下的文章导航。详细文档可查阅：[文章 Finder API#cursorByCategory](https://docs.halo.run/developer-guide/theme/finder-apis/post.md#cursorbycategorypostname)。

## 2.24.1

### 文章 Finder API > 新增 `random(maxSize)` 方法

在 2.24.1 中，我们为文章 Finder API 新增了 `random(maxSize)` 方法，用于随机获取文章列表。详细文档可查阅：[文章 Finder API#random](https://docs.halo.run/developer-guide/theme/finder-apis/post.md#randommaxsize)。

## 2.23.0

### 表单定义 > Iconify 表单类型新增 `sizing` 参数

在 2.23.0 中，Iconify 表单类型默认不再显示图标大小选项，如果需要让用户设置图标大小，可以配置 `sizing` 参数，详细文档可查阅：[表单定义#Iconify](https://docs.halo.run/developer-guide/form-schema.md#iconify)

## 2.22.8

### 表单定义 > 新增 `toggle` 表单类型

在 2.22.8 中，我们为 FormKit 表单新增了 `toggle` 组件，这是一个可以对一组图片、颜色或文字等进行选择切换的组件，详细文档可查阅：[表单定义#toggle](https://docs.halo.run/developer-guide/form-schema.md#toggle)

## 2.22.1

### 表单定义 > 新增 `switch` 表单类型

在 2.22.1 中，我们为 FormKit 表单新增了 `switch` 组件，用于定义一个功能的开关，详细文档可查阅：[表单定义#switch](https://docs.halo.run/developer-guide/form-schema.md#switch)

## 2.22.0

### 表单定义 > 新增 Iconify 图标选择器

在 2.22.0 中，我们为 FormKit 表单提供了通用的图标选择器，基于 [Iconify](https://icon-sets.iconify.design/)，详细文档可查阅：[表单定义#Iconify](https://docs.halo.run/developer-guide/form-schema.md#iconify)

### 表单定义 > 新增 `array` 表单类型

在 2.22.0 中，我们为 FormKit 表单新增了 `array` 组件，用于定义一组数据，并计划使用 `array` 组件替换原有的 `repeater` 组件。详细文档可查阅：[表单定义#array](https://docs.halo.run/developer-guide/form-schema.md#array)

### 表单定义 > 重构 `attachment` 表单类型

在 Halo 2.22 中，我们重构了原有的 attachment 表单类型，支持了预览和直接上传文件，并将旧版的表单类型更名为了 [attachmentInput](https://docs.halo.run/developer-guide/form-schema.md#attachmentinput)

### 文章 Finder API > 修改 `cursor(postName)` 返回结构

我们修改了文章 Finder API 中 `cursor(postName)` 方法的返回体结构，移除了 `current` 字段，并修改了 `previous` 和 `next` 字段类型为 `ListedPostVo`，并明确了上一篇文章是指发布时间较当前文章更早的文章，下一篇文章是指发布时间较当前文章更新的文章。详细文档可查阅：[文章 Finder API#cursor](https://docs.halo.run/developer-guide/theme/finder-apis/post.md#cursorpostname)。