From 8642b4e2574ba53d021d4ad2c6e998f326f2fc71 Mon Sep 17 00:00:00 2001
From: Ryan Wang <i@ryanc.cc>
Date: Sun, 21 Dec 2025 21:44:40 +0800
Subject: [PATCH] Update docs for attachment form type refactor in 2.22 (#534)

---
 docs/developer-guide/form-schema.md          | 30 ++++++++++++++++++++
 docs/developer-guide/plugin/api-changelog.md |  4 +++
 docs/developer-guide/theme/api-changelog.md  |  6 +++-
 3 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/docs/developer-guide/form-schema.md b/docs/developer-guide/form-schema.md
index 4a7e55f..9586c73 100644
--- a/docs/developer-guide/form-schema.md
+++ b/docs/developer-guide/form-schema.md
@@ -413,6 +413,36 @@ UI 效果：
 
 #### 描述
 
+:::info
+在 Halo 2.22 中，我们重构了原有的 attachment 表单类型，支持了预览和直接上传文件，并将旧版的表单类型更名为了 [attachmentInput](#attachmentinput)。
+:::
+
+附件类型的输入框，支持预览附件、直接上传文件、从附件库选择。
+
+#### 参数
+
+- `accepts`：文件类型，数据类型为 `string[]`
+- `width`：预览区域宽度
+- `aspectRatio`：预览区域长宽比，比如 `1/1`、`16/9`
+- `multiple`：是否支持多选，设置为 `true` 之后，数据结构为字符串数组
+
+#### 示例
+
+```yaml
+- $formkit: attachment
+  name: logo
+  label: Logo
+  accepts:
+    - "image/png"
+    - "video/mp4"
+    - "audio/*"
+  value: ""
+```
+
+### attachmentInput
+
+#### 描述
+
 附件类型的输入框，支持直接调用附件库弹框选择附件。
 
 ****#### 参数
diff --git a/docs/developer-guide/plugin/api-changelog.md b/docs/developer-guide/plugin/api-changelog.md
index 88fec36..98ecec8 100644
--- a/docs/developer-guide/plugin/api-changelog.md
+++ b/docs/developer-guide/plugin/api-changelog.md
@@ -151,3 +151,7 @@ Extension.create({
 可直接移除 `getDraggable` 扩展点，不再使用，也无需考虑兼容性问题。
 
 关于 `getDraggableMenuItems` 扩展点的详细文档可查阅：[拖拽菜单扩展](./extension-points/ui/default-editor-extension-create.md#5-拖拽菜单扩展)
+
+### 表单定义 > 重构 `attachment` 表单类型
+
+在 Halo 2.22 中，我们重构了原有的 attachment 表单类型，支持了预览和直接上传文件，并将旧版的表单类型更名为了 [attachmentInput](../form-schema.md#attachmentinput)
diff --git a/docs/developer-guide/theme/api-changelog.md b/docs/developer-guide/theme/api-changelog.md
index d59e928..fba2818 100644
--- a/docs/developer-guide/theme/api-changelog.md
+++ b/docs/developer-guide/theme/api-changelog.md
@@ -9,10 +9,14 @@ description: 记录每一个版本的主题 API 变更记录，方便开发者
 
 在 2.22.0 中，我们为 FormKit 表单提供了通用的图标选择器，基于 [Iconify](https://icon-sets.iconify.design/)，详细文档可查阅：[表单定义#Iconify](../../developer-guide/form-schema.md#iconify)
 
-### 表单定义 > 新增 `array` 组件
+### 表单定义 > 新增 `array` 表单类型
 
 在 2.22.0 中，我们为 FormKit 表单新增了 `array` 组件，用于定义一组数据，并计划使用 `array` 组件替换原有的 `repeater` 组件。详细文档可查阅：[表单定义#array](../../developer-guide/form-schema.md#array)
 
+### 表单定义 > 重构 `attachment` 表单类型
+
+在 Halo 2.22 中，我们重构了原有的 attachment 表单类型，支持了预览和直接上传文件，并将旧版的表单类型更名为了 [attachmentInput](../form-schema.md#attachmentinput)
+
 ### 文章 Finder API > 修改 `cursor(postName)` 返回结构
 
 我们修改了文章 Finder API 中 `cursor(postName)` 方法的返回体结构，移除了 `current` 字段，并修改了 `previous` 和 `next` 字段类型为 `ListedPostVo`，并明确了上一篇文章是指发布时间较当前文章更早的文章，下一篇文章是指发布时间较当前文章更新的文章。详细文档可查阅：[文章 Finder API#cursor](../../developer-guide/theme/finder-apis/post.md#cursor)。