8.4 · 拖拽系统（Drag and Drop System）

拖拽系统（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/8.4-drag-and-drop-system

翻译时间：2026-06-09T16:09:58.742Z

翻译模型：deepseek-chat

原文字符数：20393

项目：Open WebUI (open-webui)

---

拖放系统

相关源文件

以下文件被用作生成此 wiki 页面的上下文：

• src/lib/components/chat/Tags.svelte
• src/lib/components/common/ConfirmDialog.svelte
• src/lib/components/common/DragGhost.svelte
• src/lib/components/common/Dropdown.svelte
• src/lib/components/common/Folder.svelte
• src/lib/components/layout/Navbar/Menu.svelte
• src/lib/components/layout/Sidebar.svelte
• src/lib/components/layout/Sidebar/ChatItem.svelte
• src/lib/components/layout/Sidebar/ChatMenu.svelte
• src/lib/components/layout/Sidebar/Folders.svelte
• src/lib/components/layout/Sidebar/Folders/FolderMenu.svelte
• src/lib/components/layout/Sidebar/RecursiveFolder.svelte

拖放系统使用户能够通过直观的拖放交互在侧边栏中重新组织聊天和文件夹。用户可以在文件夹之间移动聊天、重新组织文件夹层级、切换聊天的置顶状态，以及通过将 JSON 文件拖放到目标区域来导入聊天数据。

关于文件夹层级结构本身的信息，请参见文件夹系统。关于聊天项在拖放之外的操作，请参见聊天项管理。

系统架构

拖放实现由三个主要层组成：可拖动的源（聊天和文件夹）、放置目标（文件夹、置顶区域和主聊天列表），以及一个在拖放操作期间提供实时跟随光标预览的视觉反馈系统。

graph TB
    subgraph "可拖动源"
        ChatItem["ChatItem.svelte<br/>draggable=true"]
        RecursiveFolder["RecursiveFolder.svelte<br/>draggable=true"]
    end

    subgraph "放置目标"
        Sidebar["Sidebar.svelte<br/>#sidebar 放置区"]
        FolderTarget["Folder.svelte<br/>通用放置目标"]
        RecursiveFolderTarget["RecursiveFolder.svelte<br/>嵌套放置目标"]
        PinnedSection["置顶聊天区域<br/>Folder 组件"]
    end

    subgraph "视觉反馈"
        DragGhost["DragGhost.svelte<br/>跟随光标预览"]
        DraggedOverState["draggedOver 状态<br/>视觉高亮叠加层"]
    end

    subgraph "状态更新"
        UpdateChatFolder["updateChatFolderIdById()"]
        UpdateFolderParent["updateFolderParentIdById()"]
        TogglePin["toggleChatPinnedStatusById()"]
        ImportChats["importChats()"]
        InitChatList["initChatList()<br/>刷新侧边栏"]
    end

    ChatItem -->|"dragstart<br/>dragend"| DragGhost
    RecursiveFolder -->|"dragstart<br/>dragend"| DragGhost

    ChatItem -->|"drag 事件"| Sidebar
    ChatItem -->|"drag 事件"| RecursiveFolderTarget
    ChatItem -->|"drag 事件"| PinnedSection

    RecursiveFolder -->|"drag 事件"| Sidebar
    RecursiveFolder -->|"drag 事件"| RecursiveFolderTarget

    Sidebar -->|"dragover"| DraggedOverState
    FolderTarget -->|"dragover"| DraggedOverState
    RecursiveFolderTarget -->|"dragover"| DraggedOverState

    Sidebar -->|"放置聊天"| UpdateChatFolder
    Sidebar -->|"放置文件夹"| UpdateFolderParent
    RecursiveFolderTarget -->|"放置聊天"| UpdateChatFolder
    RecursiveFolderTarget -->|"放置文件夹"| UpdateFolderParent
    PinnedSection -->|"放置聊天"| TogglePin

    Sidebar -->|"放置 JSON 文件"| ImportChats
    RecursiveFolderTarget -->|"放置 JSON 文件"| ImportChats

    UpdateChatFolder --> InitChatList
    UpdateFolderParent --> InitChatList
    TogglePin --> InitChatList
    ImportChats --> InitChatList

来源：src/lib/components/layout/Sidebar.svelte:1-33, src/lib/components/layout/Sidebar.svelte:40-45, src/lib/components/layout/Sidebar/ChatItem.svelte:1-40, src/lib/components/layout/Sidebar/ChatItem.svelte:245-257, src/lib/components/layout/Sidebar/RecursiveFolder.svelte:1-50, src/lib/components/layout/Sidebar/RecursiveFolder.svelte:87-206, src/lib/components/common/Folder.svelte:1-27

可拖动源

聊天项

单个聊天项通过 ChatItem.svelte 组件实现可拖动性。每个聊天项仅在数据加载完成后才变为可拖动，以确保完整的聊天对象可用于传输。

graph LR
    subgraph "ChatItem 拖放生命周期"
        MouseOver["mouseOver = true<br/>触发 loadChat()"]
        LoadChat["loadChat()<br/>getChatById()"]
        ChatLoaded["chat 对象已填充<br/>draggable = true"]
        DragStart["onDragStart()<br/>设置 dataTransfer"]
        DragOperation["onDrag()<br/>更新 x, y 坐标"]
        DragEnd["onDragEndHandler()<br/>重置透明度"]
    end

    MouseOver --> LoadChat
    LoadChat --> ChatLoaded
    ChatLoaded --> DragStart
    DragStart --> DragOperation
    DragOperation --> DragEnd

    DragStart -->|"dataTransfer.setData()"| DataTransfer["JSON.stringify({<br/>type: 'chat',<br/>id: id<br/>})"]

    DragStart -->|"setDragImage()"| InvisibleImage["invisibleDragImage<br/>1x1 透明 PNG"]

该组件使用懒加载模式，仅在用户悬停到项目上时通过 loadChat 获取聊天数据，从而优化大型聊天列表的性能。拖放图像被设置为一个 1x1 像素的透明 PNG，以隐藏默认的浏览器拖放预览，允许自定义的 DragGhost 组件提供视觉反馈。 来源：src/lib/components/layout/Sidebar/ChatItem.svelte:107-113, src/lib/components/layout/Sidebar/ChatItem.svelte:245-257, src/lib/components/layout/Sidebar/ChatItem.svelte:1-6

文件夹项

文件夹通过 RecursiveFolder.svelte 组件实现可拖动性，使用户能够通过将文件夹拖入其他文件夹或拖回根层级来重新组织文件夹层级。

graph TB
    subgraph "RecursiveFolder 拖放实现"
        FolderElement["folderElement<br/>bind:this={folderElement}"]
        DragStartHandler["onDragStart(event)<br/>在 dragstart 时调用"]
        DataTransfer["event.dataTransfer.setData()<br/>JSON: {type: 'folder', id: folderId}"]
        SetDragImage["setDragImage(dragImage, 0, 0)<br/>1x1 透明图像"]
        DraggedState["dragged = true<br/>opacity = '0.5'"]
        OnDrag["onDrag(event)<br/>更新 x, y 位置"]
        OnDragEnd["onDragEnd(event)<br/>opacity = '1', dragged = false"]
    end

    FolderElement -->|"addEventListener('dragstart')"| DragStartHandler
    DragStartHandler --> DataTransfer
    DragStartHandler --> SetDragImage
    DragStartHandler --> DraggedState

    FolderElement -->|"addEventListener('drag')"| OnDrag
    FolderElement -->|"addEventListener('dragend')"| OnDragEnd

    OnDrag -->|"x = event.clientX<br/>y = event.clientY"| DragGhostPosition["DragGhost 组件<br/>定位在 x, y"]

文件夹拖放实现通过 parentDragged 属性防止在子文件夹已被拖动时拖动其父文件夹，该属性会沿递归文件夹树向下传播。 来源：src/lib/components/layout/Sidebar/RecursiveFolder.svelte:224-253, src/lib/components/layout/Sidebar/RecursiveFolder.svelte:58-59, src/lib/components/layout/Sidebar/RecursiveFolder.svelte:217-219

放置目标与处理程序

主侧边栏放置区

主侧边栏作为文件导入和聊天/文件夹重新组织的顶级放置目标。它区分文件放置和数据传输操作。

graph TB
    subgraph "侧边栏放置处理程序"
        OnDragOver["onDragOver(e)<br/>检查 e.dataTransfer.types"]
        CheckFileType{{"includes('Files')"}}
        SetDraggedOver["draggedOver = true"]
        OnDrop["onDrop(e)<br/>处理放置"]
        CheckDropType{{"e.dataTransfer.files?"}}

        FileHandler["inputFilesHandler(files)<br/>处理 JSON 导入"]
        ChatDropHandler["聊天/文件夹放置逻辑"]

        ParseJSON["JSON.parse(content)"]
        ImportChats["importChatHandler(chatItems)"]
        InitList["initChatList()"]
    end

    OnDragOver --> CheckFileType
    CheckFileType -->|"是"| SetDraggedOver
    CheckFileType -->|"否"| SetDraggedOver

    OnDrop --> CheckDropType
    CheckDropType -->|"是 (文件)"| FileHandler
    CheckDropType -->|"否 (数据传输)"| ChatDropHandler

    FileHandler --> ParseJSON
    ParseJSON --> ImportChats
    ImportChats --> InitList

当放置 JSON 文件时，侧边栏读取文件内容、解析它，并通过 importChatHandler 函数导入包含的聊天数据。 来源：src/lib/components/layout/Sidebar.svelte:219-239, src/lib/components/layout/Sidebar.svelte:40-45

文件夹放置目标

Folder.svelte 和 RecursiveFolder.svelte 都实现了放置目标功能，其中 RecursiveFolder 提供了更复杂的逻辑来处理文件夹层级变化和聊天移动。

graph TB
    subgraph "RecursiveFolder 放置逻辑"
        OnDrop["onDrop(e)<br/>如果 dragged 或 parentDragged 则阻止"]
        CheckItemKind{{"item.kind === 'file'"}}

        FileType{{"file.type === 'application/json'"}}
        ReadFile["FileReader.readAsText()"]
        DispatchImport["dispatch('import', {<br/>folderId, items<br/>})"]

        ParseDataTransfer["JSON.parse(dataTransfer)"]
        CheckType{{"data.type"}}

        FolderMove["type === 'folder'<br/>updateFolderParentIdById(id, folderId)"]
        ChatMove["type === 'chat'<br/>updateChatFolderIdById(chat.id, folderId)"]

        OnItemMove["onItemMove({<br/>originFolderId,<br/>targetFolderId<br/>})"]
        DispatchUpdate["dispatch('update')"]
        SetFolderItems["setFolderItems()<br/>刷新文件夹内容"]
    end

    OnDrop --> CheckItemKind
    CheckItemKind -->|"文件"| FileType
    FileType -->|"JSON"| ReadFile
    ReadFile --> DispatchImport

    CheckItemKind -->|"数据传输"| ParseDataTransfer
    ParseDataTransfer --> CheckType

    CheckType -->|"文件夹"| FolderMove
    CheckType -->|"聊天"| ChatMove

    FolderMove --> DispatchUpdate
    ChatMove --> OnItemMove
    ChatMove --> DispatchUpdate

    DispatchUpdate --> SetFolderItems

文件夹放置处理程序包含验证逻辑，以防止无效操作，例如将文件夹拖放到自身或其子代上。 来源：src/lib/components/layout/Sidebar/RecursiveFolder.svelte:87-206, src/lib/components/common/Folder.svelte:39-97

置顶聊天区域

置顶聊天区域在 Sidebar.svelte 中管理。将聊天项拖放到置顶列表区域或置顶文件夹上会触发 toggleChatPinnedStatusById 函数来更新聊天的置顶状态，并刷新置顶存储。 来源：src/lib/components/layout/Sidebar.svelte:19, src/lib/components/layout/Sidebar.svelte:41-42, src/lib/components/layout/Sidebar/ChatMenu.svelte:51-54

数据传输协议

传输数据结构

所有拖放操作都将数据序列化为 text/plain 格式的 JSON 字符串。结构根据拖动的项目类型而变化：

项目类型	数据结构	用途
聊天	{type: 'chat', id: string}	在文件夹之间移动聊天、置顶/取消置顶
文件夹	{type: 'folder', id: string}	重新组织文件夹层级
文件 (JSON)	具有 application/json MIME 类型的文件对象	导入聊天数据

graph LR
    subgraph "聊天数据传输"
        ChatDragStart["ChatItem.onDragStart()"]
        ChatData["setData('text/plain',<br/>JSON.stringify({<br/>  type: 'chat',<br/>  id: id<br/>}))"]
    end

    subgraph "文件夹数据传输"
        FolderDragStart["RecursiveFolder.onDragStart()"]
        FolderData["setData('text/plain',<br/>JSON.stringify({<br/>  type: 'folder',<br/>  id: folderId<br/>}))"]
    end

    subgraph "放置目标处理"
        GetData["getData('text/plain')"]
        ParseData["JSON.parse(dataTransfer)"]
        CheckType{{"data.type"}}
        ChatHandler["处理聊天放置"]
        FolderHandler["处理文件夹放置"]
    end

    ChatDragStart --> ChatData
    FolderDragStart --> FolderData

    ChatData --> GetData
    FolderData --> GetData

    GetData --> ParseData
    ParseData --> CheckType
    CheckType -->|"'chat'"| ChatHandler
    CheckType -->|"'folder'"| FolderHandler

id 字段是后端 API 用于执行重新组织的主要标识符。 来源：src/lib/components/layout/Sidebar/ChatItem.svelte:251-256, src/lib/components/layout/Sidebar/RecursiveFolder.svelte:229-234

视觉反馈系统

拖放幽灵组件

DragGhost.svelte 组件提供了一个自定义的跟随光标预览，在拖放操作期间出现。它显示被拖动项目的样式化预览，包含图标和名称。

graph TB
    subgraph "DragGhost 渲染"
        DraggedCondition{{"dragged && x && y"}}
        CreateGhost["创建 DragGhost 元素"]
        Position["定位在 x + 10, y + 10"]
        ContentSlot["渲染插槽内容<br/>(图标 + 项目名称)"]

        ChatGhost["聊天: 文档图标 + 标题"]
        FolderGhost["文件夹: 文件夹打开图标 + 名称"]
    end

    subgraph "幽灵生命周期"
        OnMount["onMount()<br/>appendChild 到 body"]
        UpdatePosition["拖放期间<br/>持续更新位置"]
        OnDestroy["onDestroy()<br/>从 body 中 removeChild"]
    end

    DraggedCondition -->|"true"| CreateGhost
    CreateGhost --> Position
    Position --> ContentSlot

    ContentSlot -->|"聊天项"| ChatGhost
    ContentSlot -->|"文件夹项"| FolderGhost

    CreateGhost --> OnMount
    UpdatePosition --> Position
    OnDestroy --> GhostLifecycle

幽灵元素通过在挂载时追加到 document.body 来渲染在正常组件树之外，确保它出现在所有其他 UI 元素之上，并通过绝对定位精确跟随光标。 来源：src/lib/components/layout/Sidebar/ChatItem.svelte:241-242, src/lib/components/layout/Sidebar/RecursiveFolder.svelte:35, src/lib/components/common/DragGhost.svelte:1-24

拖放悬停视觉状态

当项目被拖放到放置目标上时，放置目标会显示一个半透明叠加层，提供关于项目将被放置到哪里的清晰视觉反馈。

graph LR
    subgraph "拖放悬停状态管理"
        OnDragOver["onDragOver(e)<br/>e.preventDefault()"]
        CheckDragged{{"dragged || parentDragged"}}
        SetDraggedOver["draggedOver = true"]
        OnDragLeave["onDragLeave(e)"]
        ClearDraggedOver["draggedOver = false"]
        OnDrop["onDrop(e)"]
        ProcessDrop["处理放置逻辑"]
        ResetState["draggedOver = false"]
    end

    subgraph "视觉渲染"
        Overlay["条件渲染:<br/>绝对定位 div<br/>bg-gray-100/50 dark:bg-gray-700/20<br/>z-50 pointer-events-none"]
    end

    OnDragOver --> CheckDragged
    CheckDragged -->|"false"| SetDraggedOver
    CheckDragged -->|"true"| ClearDraggedOver
    SetDraggedOver --> Overlay

    OnDragLeave --> ClearDraggedOver
    OnDrop --> ProcessDrop
    ProcessDrop --> ResetState

叠加层使用 pointer-events-none 来防止干扰放置检测逻辑，同时保持对用户可见。 来源：src/lib/components/layout/Sidebar/RecursiveFolder.svelte:78-85, src/lib/components/layout/Sidebar/RecursiveFolder.svelte:208-215, src/lib/components/common/Folder.svelte:33-37, src/lib/components/common/Folder.svelte:134-138

状态管理与更新

API 集成

放置操作会触发 API 调用来持久化组织变更。系统为不同操作使用特定的 API 端点：

操作	API 函数	端点	参数
将聊天移动到文件夹	updateChatFolderIdById()	/chats/{id}/folder/update	chatId, folderId
更改文件夹父级	updateFolderParentIdById()	/folders/{id}/update/parent	folderId, parent_id
切换聊天置顶	toggleChatPinnedStatusById()	/chats/{id}/pin/toggle	chatId
导入聊天	importChats()	/chats/import	聊天对象数组

sequenceDiagram
    participant 用户
    participant ChatItem
    participant Folder as RecursiveFolder
    participant API_Folders as "API: /api/folders"
    participant API_Chats as "API: /api/chats"
    participant Sidebar

    用户->>ChatItem: 开始拖动聊天
    ChatItem->>ChatItem: onDragStart()<br/>设置 dataTransfer

    用户->>Folder: 放置到文件夹
    Folder->>Folder: onDrop()<br/>解析 dataTransfer
    Folder->>Folder: 检查聊天是否存在<br/>getChatById()

    alt 聊天存在
        Folder->>API_Chats: updateChatFolderIdById(chatId, folderId)
    else 聊天不存在 (导入)
        Folder->>API_Chats: importChats([chatItem])
    end

    API_Chats-->>Folder: 成功响应
    Folder->>Folder: onItemMove()<br/>通知原始文件夹
    Folder->>Folder: dispatch('update')
    Folder->>Folder: setFolderItems()<br/>刷新内容

    Folder->>Sidebar: 事件冒泡
    Sidebar->>Sidebar: initChatList()<br/>刷新所有列表
    Sidebar->>API_Chats: getChatList()
    Sidebar->>API_Chats: getPinnedChatList()

API 操作成功后，侧边栏会刷新聊天和文件夹列表以反映新的组织。 来源：src/lib/components/layout/Sidebar/RecursiveFolder.svelte:144-195, src/lib/components/layout/Sidebar.svelte:219-239, src/lib/apis/folders.ts:49, src/lib/apis/chats.ts:26, src/lib/apis/chats.ts:42, src/lib/apis/chats.ts:45

文件夹注册表模式

RecursiveFolder 组件在 folderRegistry 对象中注册自身，使父组件能够在放置操作后触发对特定文件夹的更新。

graph TB
    subgraph "文件夹注册表模式"
        OnMount["RecursiveFolder.onMount()"]
        Register["folderRegistry[folderId] = {<br/>  setFolderItems: () => {...}<br/>}"]

        DropOperation["将聊天放置到文件夹"]
        CheckOrigin{{"originFolderId 存在?"}}
        CallRegistry["folderRegistry[originFolderId]<br/>.setFolderItems()"]
        RefreshOrigin["原始文件夹刷新<br/>其聊天列表"]

        TargetRefresh["目标文件夹<br/>setFolderItems()"]
    end

    OnMount --> Register

    DropOperation --> CheckOrigin
    CheckOrigin -->|"是"| CallRegistry
    CallRegistry --> RefreshOrigin

    DropOperation --> TargetRefresh

此模式确保当聊天从一个文件夹移动到另一个文件夹时，原始文件夹和目标文件夹都会更新其显示的内容，而无需完全刷新侧边栏。 来源：src/lib/components/layout/Sidebar/RecursiveFolder.svelte:257-261, src/lib/components/layout/Sidebar/RecursiveFolder.svelte:186-190, src/lib/components/layout/Sidebar/Folders.svelte:26-30

Sortable.js 集成

侧边栏还使用 Sortable 库专门用于在非移动设备上重新组织置顶菜单项（如笔记、工作区等）。

graph LR
    subgraph "Sortable 实现"
        Init["initPinnedMenuSortable()"]
        El["#pinned-menu-items-list"]
        Update["onUpdate(event)"]
        Store["settings.set()"]
        API["updateUserSettings()"]
    end

    Init --> El
    El --> Update
    Update --> Store
    Store --> API

这为静态菜单项提供了高性能、原生感觉的重新组织，与聊天/文件夹拖放系统不同。 来源：src/lib/components/layout/Sidebar.svelte:4, src/lib/components/layout/Sidebar.svelte:152-169