AI Tool Call Card

Playground

即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。

<AiToolCallCard />

安裝

npx shadcn@latest add https://webberui.com/r/ai-tool-call-card.json

npm install motion lucide-react clsx tailwind-merge

使用

import { AiToolCallCard } from "@/components/ui/ai-tool-call-card";

<AiToolCallCard
  name="search_web"
  status="running"
  description="搜尋文件庫以回答使用者問題"
  args={{ query: "webber ui motion", top_k: 5 }}
/>;

status 由你的 agent 執行流程驅動，值變更時卡片會自動過渡：圓形指示器的圖示彈入、狀態文字上下翻轉、外框顏色平滑染色。

狀態轉換

把 status 綁到工具呼叫的實際生命週期即可，元件負責所有過場動畫：

const [status, setStatus] = useState<ToolCallStatus>("pending");

async function call() {
  setStatus("running");
  try {
    const result = await runTool();
    setStatus("success");
  } catch {
    setStatus("error");
  }
}

進入 error 時，非受控模式會自動展開以露出錯誤訊息。

展開參數與結果

提供 args 時卡片可展開；result（成功時）與 error（失敗時）分別顯示在對應段落。展開狀態支援受控與非受控雙模式：

<AiToolCallCard
  name="run_sql"
  status="success"
  args={{ table: "orders", limit: 100 }}
  result={<pre>{JSON.stringify(rows, null, 2)}</pre>}
  expanded={open}
  onExpandedChange={setOpen}
/>

Props

細節

• 圓形指示器以 AnimatePresence 依 status 切換圖示：舊圖示縮退、新圖示以 spring 彈入
• 狀態文字使用翻轉窗（overflow 遮罩），舊值上翻出、新值自下方翻入
• 外框與指示器底色以 transition-colors 平滑染色（var(--wb-duration-normal,300ms)）
• 執行中時底線出現不定量的亮帶掃動，代表工具仍在運作
• 展開區以 height: auto 過渡開闔，內容淡入

可及性

• 卡片內含 role="status" 的 aria-live="polite" 純文字，狀態變更時朗讀「名稱：狀態」
• 所有動畫節點皆 aria-hidden，不重複朗讀
• 可展開時，標題列為 <button>，帶 aria-expanded / aria-controls，支援鍵盤操作與 focus ring
• 使用者開啟「減少動態效果」時：指示器停止旋轉、翻轉改為淡入淡出、進度帶隱藏、展開改為即時切換，DOM 結構維持一致（掛載後才切換，避免 hydration 不一致）