简体中文 | English

react-bottom-lock

适用于聊天与流式界面的 React 吸底滚动 Hook。

安装

pnpm add react-bottom-lock

使用

普通滚动容器

import { useStickToBottom } from 'react-bottom-lock';

function ChatList({ children }: { children: React.ReactNode }) {
  const sticky = useStickToBottom();

  return (
    <div ref={sticky.scrollRef} style={{ height: 480, overflow: 'auto' }}>
      <div ref={sticky.contentRef}>{children}</div>
    </div>
  );
}

react-virtuoso

import { Virtuoso } from 'react-virtuoso';
import { useVirtualStickToBottom } from 'react-bottom-lock';

function Timeline({ items }: { items: string[] }) {
  const { scrollRef, notifyContentHeight } = useVirtualStickToBottom();

  return (
    <Virtuoso
      data={items}
      scrollerRef={scrollRef}
      totalListHeightChanged={notifyContentHeight}
      followOutput={false}
      itemContent={(index, item) => <div>{item}</div>}
    />
  );
}

react-window

import { useEffect, useLayoutEffect } from 'react';
import {
  List,
  useDynamicRowHeight,
  useListCallbackRef,
  type RowComponentProps,
} from 'react-window';
import { useVirtualStickToBottom } from 'react-bottom-lock';

function Row({ index, items, style }: RowComponentProps<{ items: string[] }>) {
  return <div style={style}>{items[index]}</div>;
}

function Timeline({ items }: { items: string[] }) {
  const { scrollRef, notifyContentHeight } = useVirtualStickToBottom();
  const [listApi, listRef] = useListCallbackRef(null);
  const rowHeight = useDynamicRowHeight({ defaultRowHeight: 96 });
  const syncHeight = () => {
    const element = listApi?.element;
    if (element) {
      notifyContentHeight(element.scrollHeight);
    }
  };

  useEffect(() => {
    scrollRef(listApi?.element ?? null);

    return () => {
      scrollRef(null);
    };
  }, [listApi, scrollRef]);

  useLayoutEffect(() => {
    syncHeight();
  });

  return (
    <List
      listRef={listRef}
      onResize={syncHeight}
      rowComponent={Row}
      rowCount={items.length}
      rowHeight={rowHeight}
      rowProps={{ items }}
    />
  );
}

@tanstack/react-virtual

import { useLayoutEffect, useRef } from 'react';
import { useVirtualizer } from '@tanstack/react-virtual';
import { useVirtualStickToBottom } from 'react-bottom-lock';

function Timeline({ items }: { items: string[] }) {
  const parentRef = useRef<HTMLDivElement | null>(null);
  const { scrollRef, contentRef, notifyContentHeight } =
    useVirtualStickToBottom();

  const virtualizer = useVirtualizer({
    count: items.length,
    estimateSize: () => 96,
    getScrollElement: () => parentRef.current,
  });
  const virtualItems = virtualizer.getVirtualItems();
  const totalSize = virtualizer.getTotalSize();

  useLayoutEffect(() => {
    notifyContentHeight(totalSize);
  }, [notifyContentHeight, totalSize]);

  return (
    <div
      ref={(node) => {
        parentRef.current = node;
        scrollRef(node);
      }}
      style={{ height: 480, overflow: 'auto' }}
    >
      <div
        ref={contentRef}
        style={{ height: totalSize, position: 'relative' }}
      >
        {virtualItems.map((virtualRow) => (
          <div
            key={virtualRow.key}
            data-index={virtualRow.index}
            ref={virtualizer.measureElement}
            style={{
              position: 'absolute',
              top: 0,
              left: 0,
              width: '100%',
              transform: `translateY(${virtualRow.start}px)`,
            }}
          >
            {items[virtualRow.index]}
          </div>
        ))}
      </div>
    </div>
  );
}

API

useStickToBottom(options?)

Options

参数	类型	默认值	说明
bottomOffset	number	70	距离底部多少像素内仍视为“接近底部”。
initial	StickToBottomAnimation | boolean	true	首次测量时是否自动吸底，以及使用哪种动画。传 false 可关闭首次自动吸底。
resize	StickToBottomAnimation	undefined	内容高度继续增长时，自动追底所使用的动画。未传时会合并当前配置，最终回退到默认弹簧配置。
retainAnimationMs	number	350	自动追底后的保留时长，避免异步布局抖动过早结束滚动。
fallbackPollInterval	number | false	false	备用轮询间隔，适合接入某些不会可靠触发 ResizeObserver 的场景。
targetScrollTop	(targetScrollTop: number, context: ScrollContext) => number	undefined	自定义最终目标 scrollTop，返回值会被自动夹在合法滚动范围内。

Returns

返回值	类型	说明
scrollRef	RefCallback<HTMLElement | null>	绑定滚动容器。
contentRef	RefCallback<HTMLElement | null>	绑定内容容器，用于监听内容高度变化。
notifyContentHeight	(height: number) => void	当外部已知内容高度变化、但 DOM 还没法稳定测到时，可手动通知。
measure	() => void	主动触发一次重新测量。
scrollToTop	(options?: ScrollToOptions | 'instant' | 'smooth') => Promise<boolean>	主动滚到顶部。
scrollToBottom	(options?: ScrollToOptions | 'instant' | 'smooth') => Promise<boolean>	主动滚到底部。
stopScroll	() => void	中断当前自动滚动，并把状态标记为已脱离吸底。
isAtBottom	boolean	当前是否仍保持底部锁定。
isNearBottom	boolean	当前是否位于 bottomOffset 阈值内。
escapedFromLock	boolean	用户是否已主动脱离吸底。
state	StickToBottomState	内部运行态。

ScrollToOptions

参数	类型	默认值	说明
animation	StickToBottomAnimation	undefined	本次滚动使用的动画。未传时会沿用 Hook 当前配置。
wait	boolean | number	false	传 true 会等到下一帧再开始；传数字则表示等待对应毫秒数。
ignoreEscapes	boolean	false	滚动过程中是否忽略用户脱离锁定的动作。
preserveScrollPosition	boolean	false	是否尽量保留当前滚动意图，而不是立刻重置为吸底或脱离状态。
duration	number | Promise<void>	0	滚动到位后保留动画状态多久；也可以传一个 Promise，在其完成前保持动画状态。

useVirtualStickToBottom(options?)

返回值	类型	说明
scrollRef	RefCallback<HTMLElement | Window | null>	绑定虚拟列表暴露出的滚动容器引用。支持元素滚动和 Window 级滚动。
notifyContentHeight	(height: number) => void	当虚拟列表总高度变化时通知 Hook，可直接绑定给对应库的总高度回调。

示例

pnpm install
pnpm --dir example dev

pnpm --dir example test

致谢

本项目的思路参考了 stackblitz-labs/use-stick-to-bottom。如需分发或二次改造，请保留 NOTICE.md 中的归属说明。

License

MIT