From 714ff9141956f67b8350c84aee175fbd0ffd8b4c Mon Sep 17 00:00:00 2001
From: Ryan Wang <i@ryanc.cc>
Date: Thu, 6 Nov 2025 21:27:18 +0800
Subject: [PATCH] Update attachment selector docs for mediaType support (#523)

---
 docs/developer-guide/plugin/api-changelog.md  | 13 ++++++++
 .../ui/attachment-selector-create.md          | 30 +++++++++++++------
 2 files changed, 34 insertions(+), 9 deletions(-)

diff --git a/docs/developer-guide/plugin/api-changelog.md b/docs/developer-guide/plugin/api-changelog.md
index 6c4784d..45aa1b0 100644
--- a/docs/developer-guide/plugin/api-changelog.md
+++ b/docs/developer-guide/plugin/api-changelog.md
@@ -21,3 +21,16 @@ description: 记录每一个版本的插件 API 变更记录，方便开发者
    1. `core:plugin:configMap:updated`：用于监听插件配置变更
 
 详细文档可查阅：[共享工具库](./api-reference/ui/shared.md)
+
+### UI 扩展点 > 附件选择选项卡类型更新
+
+在 2.22.0 中，我们为 `AttachmentLike` 复合类型添加了 `mediaType` 字段，用于区分文件类型，方便在插入到文章时显示正确的媒体类型，如不填写，所选择的文件将作为链接插入到编辑器，所以实现了此扩展点的插件都需要进行改动，具体步骤：
+
+1. 升级依赖
+
+   ```bash
+   pnpm install @halo-dev/console-shared@2.22.0
+   ```
+
+2. 提升 [plugin.yaml#spec.requires](./basics/manifest.md#字段详解) 版本为 `>=2.22.0`。
+3. 按照[最新文档](./extension-points/ui/attachment-selector-create.md)修改插件代码
diff --git a/docs/developer-guide/plugin/extension-points/ui/attachment-selector-create.md b/docs/developer-guide/plugin/extension-points/ui/attachment-selector-create.md
index 4f719da..ea0400c 100644
--- a/docs/developer-guide/plugin/extension-points/ui/attachment-selector-create.md
+++ b/docs/developer-guide/plugin/extension-points/ui/attachment-selector-create.md
@@ -10,6 +10,9 @@ description: 扩展附件选择组件的选项卡 - attachment:selector:create
 ## 定义方式
 
 ```ts
+import { definePlugin, type AttachmentSelectProvider } from "@halo-dev/console-shared"
+import { markRaw } from "vue"
+import FooComponent from "./src/FooComponent.vue"
 export default definePlugin({
   extensionPoints: {
     "attachment:selector:create": (): AttachmentSelectProvider[]| Promise<AttachmentSelectProvider[]> => {
@@ -56,14 +59,16 @@ export interface AttachmentSelectProvider {
     }>();
     ```
 
+`AttachmentLike` 是一个复合类型，可以是 Halo 附件模型数据、文件链接字符串、或者简单类型对象，类型定义：
+
 ```ts title="AttachmentLike"
-export type AttachmentLike =
-  | Attachment
-  | string
-  | {
-      url: string;
-      type: string;
-    };
+type AttachmentLike = Attachment | AttachmentSimple | string;
+interface AttachmentSimple {
+  url: string;            // 文件链接
+  mediaType?: string;     // 文件类型，如 image/png、video/*，如不填写，将被作为链接插入到文章
+  alt?: string;           // 代替文本
+  caption?: string;       // 说明文本
+}
 ```
 
 ## 示例
@@ -97,6 +102,9 @@ export default definePlugin({
 
 ```vue title="StickerSelectorProvider.vue"
 <script lang="ts" setup>
+import type { AttachmentLike, AttachmentSimple } from '@halo-dev/console-shared';
+import { ref } from 'vue';
+
 const props = withDefaults(
   defineProps<{
     selected: AttachmentLike[];
@@ -110,19 +118,22 @@ const emit = defineEmits<{
   (event: "update:selected", attachments: AttachmentLike[]): void;
 }>();
 
-const stickers = [
+const stickers: AttachmentSimple[] = [
   {
     url: "https://picsum.photos/200?random=1",
+    mediaType: "image/*"
   },
   {
     url: "https://picsum.photos/200?random=2",
+    mediaType: "image/*"
   },
   {
     url: "https://picsum.photos/200?random=3",
+    mediaType: "image/*"
   },
 ];
 
-const selectedStickers = ref<Set<String>>(new Set());
+const selectedStickers = ref<Set<string>>(new Set());
 
 const handleSelect = async (url: string) => {
   if (selectedStickers.value.has(url)) {
@@ -143,4 +154,5 @@ const handleSelect = async (url: string) => {
 
 ## 实现案例
 
+- [https://github.com/halo-sigs/plugin-image-stream](https://github.com/halo-sigs/plugin-image-stream)
 - [https://github.com/halo-sigs/plugin-unsplash](https://github.com/halo-sigs/plugin-unsplash)