滑動操作列表

行動裝置慣用的滑動操作列表：向右拖曳露出綠色封存層、向左露出紅色刪除層，超過門檻時圖示彈跳放大並自動執行，項目飛出後收合離場；桌面上 hover 或鍵盤聚焦時會顯示按鈕 fallback，不依賴拖曳手勢。

載入預覽⋯

Playground

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

觸發門檻（px）threshold

列表寬度className

<SwipeActionList />

安裝

npx shadcn@latest add https://webberui.com/r/swipe-action-list.json

或在 components.json 設定 registries 後，改用 @webberui/swipe-action-list 安裝。

安裝依賴後，從 registry JSON（/r/swipe-action-list.json 的 files[0].content）複製 swipe-action-list.tsx 原始碼到你的 components/ui/ 目錄：

npm install motion lucide-react clsx tailwind-merge

使用

import { SwipeActionList } from "@/components/ui/swipe-action-list";

<SwipeActionList
  items={[
    {
      id: "msg-1",
      title: "林雅婷",
      description: "設計稿已更新，麻煩幫我看一下",
      meta: "09:24",
    },
  ]}
  onArchive={(item) => console.log("封存", item.id)}
  onDelete={(item) => console.log("刪除", item.id)}
/>

Props

Prop	型別	預設值	說明
`items`	`SwipeActionItem[]`	—	列表資料，項目被封存/刪除後會從內部列表移除
`onArchive`	`(item: SwipeActionItem) => void`	—	右滑（或按封存鈕）超過門檻時觸發
`onDelete`	`(item: SwipeActionItem) => void`	—	左滑（或按刪除鈕）超過門檻時觸發
`threshold`	`number`	`96`	觸發動作所需的拖曳距離門檻（px）
`className`	`string`	—	透傳到外層容器

SwipeActionItem 欄位：

欄位	型別	預設值	說明
`id`	`string`	—	唯一識別碼，作為 React key 與動作回呼的參數
`title`	`string`	—	項目主標題（頭像縮寫取自第一個字）
`description`	`string`	—	次要描述文字，過長會單行截斷
`meta`	`string`	—	右側輔助資訊，例如時間或標籤
`hue`	`number`	依 `id` 推導	頭像漸層色相（0-360）

可及性

桌面 hover 或鍵盤 Tab 聚焦時顯示封存/刪除按鈕 fallback（含中文 aria-label），完整功能不依賴拖曳手勢
每次封存/刪除透過 aria-live="polite" 區域播報結果（如「已封存『林雅婷』」）
使用者系統開啟「減少動態效果」時，省略飛出與收合動畫，項目直接移除
拖曳僅鎖定水平軸並保留 touch-pan-y，不阻擋頁面垂直捲動
兩側動作層為純視覺提示，對輔助科技隱藏（aria-hidden）

滑動操作列表

Playground

安裝

使用

Props

可及性

On this page