跳至主要内容

檔案上傳與拖放

<Chatbot> 內建圖片與文件上傳，使用者也可以直接把檔案拖放進聊天視窗。 下方 demo 連到真實的 bot provider，所以你可以實際選檔、預覽、拖放。

資訊

上傳需要真實的 botProviderEndpoint。在 preview mode（botProviderEndpoint: "skip"）下， 上傳按鈕仍會顯示，但輸入框會被停用、檔案不會真的上傳。

上傳開關

把圖片或文件直接拖進右側聊天視窗，會出現拖放區覆蓋層。送出前可在輸入框上方預覽縮圖／檔名。

目前設定

{
  "enableUpload": true,
  "enableDocumentUpload": true
}
聊天機器人載入中…

兩個上傳開關​

Prop在 footer 顯示接受的檔案
enableUpload圖片上傳按鈕JPEG / JPG / PNG / GIF / WebP
enableDocumentUpload文件上傳按鈕PDF、Office、CSV、PPT、MP3 / MP4、HTML / XML / TXT / JSON

當同時啟用 3 個以上的按鈕（含 enableExport）時，footer 會把它們摺疊成一個「+」選單。

檔案限制​

類型允許的格式單檔上限數量上限
圖片JPEG / JPG / PNG / GIF / WebP20MB10 張
文件PDF、Office、CSV、PPT、MP3 / MP4、HTML / XML / TXT / JSON20MB10 個

超過限制的檔案會被擋下並顯示錯誤提示。

送出訊息時會夾帶什麼​

使用者選檔後，SDK 會立即非同步上傳，並在輸入框上方顯示預覽（圖片縮圖／文件清單）。 送出訊息時，這些資訊會放進 SendMessageParams：

欄位說明
blobIds上傳成功的檔案 blob id（圖片與文件皆有）
filePreviewUrls圖片的本地預覽 URL
documentNames文件的原始檔名

你可以用 onBeforeSendMessage 在送出前讀取或修改這些欄位。

程式範例​

import { Chatbot } from "@asgard-js/react";

export function Demo() {
  return (
    <Chatbot
      title="檔案上傳 Demo"
      config={{ botProviderEndpoint: BOT_PROVIDER_ENDPOINT }}
      customChannelId="file-upload-demo"
      enableUpload
      enableDocumentUpload
    />
  );
}

自訂拖放：useFileDropContext​

拖放行為由 <Chatbot> 內建處理：拖曳檔案到視窗上方時會顯示拖放區覆蓋層， 放開後檔案會自動分類成圖片／文件並進入上傳流程。

如果你做了自訂 footer 或想自行接管拖放區，可以用 useFileDropContext：

import { useFileDropContext } from "@asgard-js/react";

function CustomDropZone() {
  const {
    droppedFiles,
    isDraggingOver,
    setDroppedFiles,
    setIsDraggingOver,
    clearDroppedFiles,
  } = useFileDropContext();

  // isDraggingOver：使用者是否正拖曳檔案到視窗上方
  // droppedFiles：放開後的 File[]
  // setDroppedFiles / clearDroppedFiles：自行注入或清空待處理檔案
  return null;
}
欄位 / 方法說明
droppedFiles目前拖放進來、待處理的 File[]
isDraggingOver使用者是否正拖曳檔案到視窗上方
setDroppedFiles以程式設定待處理檔案
setIsDraggingOver以程式設定拖曳狀態（自訂覆蓋層用）
clearDroppedFiles清空待處理檔案

也看看​

  • 功能開關 — 一次切換 enableUpload / enableExport / enableDocumentUpload
  • 送出前處理 — 在送出前讀取 blobIds / documentNames
  • 自訂 Footer — 自己組輸入列時如何接上傳與拖放