Document FormKit select option metadata

docs/developer-guide/form-schema.md

@@ -75,6 +75,13 @@ spec:
 
 自定义的选择器组件，支持静态和动态数据源，支持多选等功能。
 
+选项对象至少需要包含 `label` 与 `value`。除此之外，还可以提供 `icon` 与 `description` 用于增强下拉选项展示：
+
+- `icon`：图标图片地址，会以 `<img>` 渲染。
+- `description`：显示在 `label` 下方的说明文字，同时参与本地静态选项搜索。
+
+选中后的单选展示和多选标签仍然只显示 `label`，提交值保持为选项的 `value`，多选时提交 `value` 数组。
+
 #### 参数 {#select-params}
 
 - `options`：静态数据源。当 `action` 存在时，此参数无效。
@@ -97,6 +104,11 @@ spec:
     Record<string, unknown> & {
       label: string;
       value: string;
+      icon?: string;
+      description?: string;
+      attrs?: {
+        disabled?: boolean;
+      };
     }
   >;
   action?: string;
@@ -133,6 +145,16 @@ spec:
      */
     valueField?: PropertyPath;
 
+    /**
+     * 从 items 中解析出选项图标地址的字段名。
+     */
+    iconField?: PropertyPath;
+
+    /**
+     * 从 items 中解析出选项描述的字段名。
+     */
+    descriptionField?: PropertyPath;
+
     /**
      * 使用 value 查询详细信息时，fieldSelector 的查询参数 key，默认为 `metadata.name`。
      */
@@ -162,8 +184,12 @@ spec:
   options:
     - label: China
       value: cn
+      icon: /assets/flags/cn.svg
+      description: Chinese cuisine with rich regional styles
     - label: France
       value: fr
+      icon: /assets/flags/fr.svg
+      description: French cuisine and bakery classics
     - label: Germany
       value: de
     - label: Spain
@@ -194,6 +220,8 @@ spec:
     itemsField: items
     labelField: post.spec.title
     valueField: post.metadata.name
+    iconField: post.spec.cover
+    descriptionField: post.status.excerpt
     fieldSelectorKey: metadata.name
 ```
 

docs/developer-guide/plugin/api-changelog.md

@@ -5,6 +5,10 @@ description: 记录每一个版本的插件 API 变更记录，方便开发者
 
 ## 2.25.0
 
+### 表单定义 > `select` 选项支持图标和描述
+
+在 2.25.0 中，`select` 表单类型的选项对象新增了 `icon` 与 `description` 字段，可在下拉选项中展示图标和辅助说明；使用远程动态数据源时，也可以通过 `requestOption.iconField` 与 `requestOption.descriptionField` 映射响应字段。详细文档可查阅：[表单定义#select](../../developer-guide/form-schema.md#select)。
+
 ### 支持插件注册自定义 FormKit 输入组件
 
 在 2.25.0 中，插件可以通过 UI 入口文件的 `formkit.inputs` 注册自定义 FormKit 输入组件，并在插件提供的 FormKit Schema 中通过 `$formkit` 使用。详细文档可查阅：[FormKit 扩展](./api-reference/ui/formkit.md)。

docs/developer-guide/theme/api-changelog.md

@@ -5,6 +5,10 @@ description: 记录每一个版本的主题 API 变更记录，方便开发者
 
 ## 2.25.0
 
+### 表单定义 > `select` 选项支持图标和描述
+
+在 2.25.0 中，`select` 表单类型的选项对象新增了 `icon` 与 `description` 字段，可在下拉选项中展示图标和辅助说明；使用远程动态数据源时，也可以通过 `requestOption.iconField` 与 `requestOption.descriptionField` 映射响应字段。详细文档可查阅：[表单定义#select](../../developer-guide/form-schema.md#select)。
+
 ### 主题目录结构 > 新增根目录预览图
 
 在 2.25.0 中，主题可以在根目录提供 `screenshot.png`、`screenshot.jpeg`、`screenshot.jpg` 或 `screenshot.webp` 作为 Console 主题预览图。Halo 会按此顺序识别第一个可读文件，并将访问地址写入 `Theme.status.screenshot`。详细文档可查阅：[目录结构](../../developer-guide/theme/structure.md)。