對話捲動容器

AI 對話與聊天室最難處理的往往不是訊息本身，而是捲軸：回覆逐字串流時要一路貼著底部，使用者往上翻舊訊息時又不能被硬拉回去；往上載入更早的訊息時，畫面不能突然跳一大段。這個容器把這些行為一次做好——在底部附近就平滑跟隨新內容，離開底部則在下方浮出「新訊息」膠囊；捲到頂部會觸發載入並補償捲動位置；另外提供命令式 API，可以捲到底部或捲到任一則訊息並短暫高亮。

Playground

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

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

<ChatScroller/>

    </div>
  );
}

安裝

使用

import * as React from "react";
import {
  ChatScroller,
  type ChatScrollerHandle,
} from "@/components/ui/chat-scroller";

export function Conversation({ messages, hasMore, loadOlder }) {
  const scrollerRef = React.useRef<ChatScrollerHandle>(null);

  return (
    <>
      <ChatScroller
        ref={scrollerRef}
        className="h-[480px] p-4"
        hasMore={hasMore}
        onLoadMore={loadOlder}
        onAtBottomChange={(atBottom) => console.log("atBottom", atBottom)}
      >
        {messages.map((m) => (
          <ChatScroller.Message key={m.id} id={m.id} className="py-1.5">
            {m.text}
          </ChatScroller.Message>
        ))}
      </ChatScroller>

      <button
        type="button"
        onClick={() =>
          scrollerRef.current?.scrollToMessage("m3", { highlight: true })
        }
      >
        跳到第 3 則
      </button>
    </>
  );
}

Props

ChatScrollerHandle

ChatScrollerScrollToMessageOptions

ChatScroller.Message

另外具名匯出 ChatScrollerProps、ChatScrollerHandle、ChatScrollerScrollToMessageOptions、ChatScrollerMessageProps 型別。

細節

• 初次掛載直接到底：在第一次繪製前把 scrollTop 設為 scrollHeight，不播動畫，使用者不會看到從頂部滑下來的過程
• 跟隨或提示：用 ResizeObserver 觀察內容容器（不是捲動容器）。內容長高時，若變化前在底部就以 duration 毫秒的 ease-out 補間跟到底；串流中每個字都會觸發一次，前一段補間還沒結束就從目前位置重新起算，不會抖動。若不在底部則不動，改為浮出新訊息膠囊
• 自寫補間，不用 CSS smooth：scroll-behavior: smooth 的時長由瀏覽器決定、無法控制，這裡一律用 requestAnimationFrame 補間；距離超過一個視窗高度時改用 longDuration。補間途中只要使用者滾輪、觸控或按 PageUp 等捲動鍵，補間立即取消，以使用者的位置為準
• 載入歷史不跳位：觸發 onLoadMore 前記下 scrollHeight 與 scrollTop，新訊息插入頂部後把增加的高度補回 scrollTop，畫面上正在看的訊息停在原處。overflow-anchor: auto 只當輔助（Safari 不支援），實際補償不依賴它
• 高亮：scrollToMessage 的 highlight 直接在目標節點加上 bg-amber-100/60 dark:bg-amber-500/10，淡入、停留後淡出，1.2 秒後移除，訊息元件不需要配合

可及性

• 捲動容器為 role="log"、aria-live="polite"、aria-relevant="additions"，螢幕閱讀器會讀出新加入的訊息；aria-label 預設「對話紀錄」
• 捲動容器 tabIndex={0}，可用鍵盤聚焦後以方向鍵、PageUp／PageDown 捲動，聚焦時顯示 focus-visible 外框；載入歷史期間設 aria-busy
• 新訊息膠囊是 type="button"，aria-label 含未讀數與「捲到最新」；點擊後焦點交回捲動容器，不會因膠囊消失而遺失
• 載入中的 spinner 為 role="status"，附「正在載入較早的訊息」的隱藏文字
• 使用者系統開啟「減少動態效果」時，所有捲動（跟隨、跳到最新、跳到訊息）都瞬間完成，膠囊只淡入淡出不位移縮放，高亮也直接上色不漸變