跳到主要内容

MessageList 消息列表

有界虚拟列表,支持历史前插与末尾跟随。

交互示例​

交互示例加载中…

用法​

<View style={{ height: 480 }}>
<MessageList
items={messages}
keyExtractor={(item) => item.id}
renderItem={(item) => <Message text={item.text} />}
hasEarlier={hasEarlier}
onRequestEarlier={loadEarlier}
/>
</View>

行为与接入​

父容器必须提供有界高度,避免嵌套在同方向的无界 ScrollView 中。数据类型由调用方决定,renderItem 可以返回 Message 或任意自定义行。

contentContainerStyle 只调整列表内容布局,可用于页面消息留白和空态居中;style 仍只调整外层视口。keyboardDismissMode 支持 RN 的 interactive,默认 on-drag。showsVerticalScrollIndicator 默认 false。离开末尾后的返回入口复用 Design IconButton variant="glass",保留 36 的视觉圆、44 的触达区,中文可访问名称仍是“回到最新消息”。玻璃材质与平台降级由 Design 提供,不影响滚动动作。

onScroll 可接收 RN 原生滚动事件,用于导航背景等外部展示联动。组件先维护内部滚动位置与末尾状态,再交付同一事件;替换或移除回调不会改变列表的跟随、拖动和定位策略。通过 event.nativeEvent.contentOffset.y 读取纵向偏移,回调不作为业务已读或分页请求依据。

更新消息时创建新的 items 数组,并保留未变化项的引用。列表会复用未变化行;流式场景可用 useCallback 保持 keyExtractor、renderItem 和 renderSeparator 稳定。行依赖选中状态等外部数据时,通过 extraData 通知更新;不能原地修改 items 后期待列表自动识别变化。

默认从 initialPosition="end" 开始,followOutput="whenAtEnd" 仅在用户位于末尾时跟随新增内容;阅读历史时不会强行跳到最新。纯前插保持当前可见内容的位置。

空列表中的动态 header 和 empty 不参与消息锚点保持,避免加载占位切换时产生原生滚动偏移;消息到达后恢复位置保持。

历史入口需要同时提供 hasEarlier 与 onRequestEarlier;加载状态由 loadingEarlier 控制。滚动不会自动发起历史请求。ref 的 scrollToEnd() 可显式回到末尾。切换会话时用 React key 重建实例。离开前可用 ref.getScrollPosition() 读取位置,再将结果作为下次的 initialPosition。近末尾返回 'end',阅读历史时返回列表纵向布局偏移。尚无可用位置时返回 undefined,仍在恢复的数值偏移会原样返回。

非负有限偏移在首次非空布局后恢复。虚拟列表分批测量时会继续向目标移动。首次非空数据保持不变时,end 初值定位到这批历史的最后一行。若初始化期间追加了新消息,则按 followOutput 处理,never 保留当时位置。内容变短时停在实际末尾。手动滚动、显式回到末尾或顶锚操作会接手当前位置。负数及非有限值按默认末尾处理。

发送后的顶锚​

ref.anchorToItem(key, { topOffset: 8, animated: true }) 以稳定的 item key 指定正文起点。topOffset 默认 0,animated 默认 true。组件先取得真实 cell 与正文相对位置(包含外部 header、内容留白,避开 renderSeparator),必要时撑开列表底部,等原生内容尺寸确认可达后再定位。

const id = createLocalMessageId();
setMessages((current) => [...current, { id, text }]);
listRef.current?.anchorToItem(id, { topOffset: 8 });

请求可以先于本次受控 items 提交。后续同项正文增长不会追到尾部,视口或目标前方布局变化则保持其顶端位置。屏外项先通过 FlatList 公开定位入口进入渲染窗口,最终位置仍以真实测量为准。Jest 的布局事件测试不代替设备长列表与键盘验证。

自动顶锚期间暂停前插位置补偿,避免两个滚动机制重复调整。用户拖动或滚轮移动后停止自动定位,恢复可见内容保持,但保留必要的底部撑高;后续视口变化只调整所需空间,不把用户拉回锚点或末尾。真实内容填满保留空间后自然释放撑高,恢复普通跟随规则。调用 scrollToEnd()、目标出现后又被移除,或列表实例卸载时清除本请求及撑高。删除后再加入同 key 不会复活旧请求;需要新定位时再次调用。回到末尾等待撑高撤除后的真实内容尺寸,不落到之前制造的空白。重新打开会话使用新列表实例,仍按 initialPosition 默认从历史末尾开始。

定位点是 renderItem 返回内容的起点。一个 item 包含多个子消息时,调用方应选中确实以目标消息开头的 item;组件不猜测业务卡片或组内哪一段是最新用户输入,也不生成消息身份。

scrollToEndBusy 默认 false,外部正在生成内容时可显示 44 的进度外环并提供中文状态名称;按钮仍可滚动,不将生成状态变成禁用。空内容不增加阻断弹性布局的包层,欢迎页和加载占位分别由场景决定居中或从顶部排列。

输入区悬浮在列表上方时,将其实际占用高度传给 scrollToEndBottomInset,返回最新消息的按钮随之上移。内容末尾留白仍通过 contentContainerStyle.paddingBottom 由页面设置;本属性不改变滚动、顶锚或跟随输出规则。负数和非有限值按 0 处理。

API​

查看完整 TypeScript 类型

以下内容由包根公开类型生成,与当前源码保持一致。

import type { ComponentProps, ReactNode } from 'react';

import type {
FlatListProps,
LayoutRectangle,
ScrollViewProps,
StyleProp,
ViewStyle,
} from 'react-native';

export interface MessageListScrollOptions {
animated?: boolean;
}

export interface MessageListAnchorOptions extends MessageListScrollOptions {
/** 正文顶端距列表视口顶部的留白,默认 0。 */
topOffset?: number;
}

export interface MessageListHandle {
/** 近末尾返回 end,阅读历史时返回列表纵向偏移,位置尚不可用时返回 undefined。 */
getScrollPosition(): 'end' | number | undefined;
scrollToEnd(options?: MessageListScrollOptions): void;
/** 按稳定 key 等待真实布局并顶锚;用户拖动、回到末尾或目标删除时结束。 */
anchorToItem(key: string, options?: MessageListAnchorOptions): void;
}

export interface MessageListProps<T> {
items: readonly T[];
keyExtractor(item: T): string;
renderItem(item: T, index: number): ReactNode;
extraData?: unknown;
header?: ReactNode;
footer?: ReactNode;
empty?: ReactNode;
renderSeparator?(previous: T, next: T): ReactNode;
/** 初次进入可传已记录的非负有限偏移,无效数值按 end 处理。 */
initialPosition?: 'start' | 'end' | number;
/** 控制内容更新跟尾;视口变化仍保持原先的末尾或阅读位置。 */
followOutput?: 'whenAtEnd' | 'never';
endThreshold?: number;
showScrollToEnd?: boolean;
/** 外部仍在生成内容时显示返回入口的进度外环,不影响滚动操作。 */
scrollToEndBusy?: boolean;
/** 悬浮输入区占据的高度;仅调整返回入口位置,正文留白由 contentContainerStyle 提供。 */
scrollToEndBottomInset?: number;
onAtEndChange?(atEnd: boolean): void;
/** 内部滚动位置维护完成后交付同一原生事件,不改变跟随或定位策略。 */
onScroll?: ScrollViewProps['onScroll'];
hasEarlier?: boolean;
loadingEarlier?: boolean;
onRequestEarlier?(): void;
keyboardDismissMode?: ScrollViewProps['keyboardDismissMode'];
contentContainerStyle?: StyleProp<ViewStyle>;
showsVerticalScrollIndicator?: boolean;
style?: StyleProp<ViewStyle>;
testID?: string;
}