@unif/react-native-chat 3.2.4 → 3.3.0

package/src/components/MessageList/MessageList.tsx

@@ -1,19 +1,25 @@
-import { useCallback, useImperativeHandle, useMemo, useRef } from 'react';
+import {
+  useCallback,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+} from 'react';
 import type { RefAttributes } from 'react';
-import { FlatList, View } from 'react-native';
+import { FlatList, StyleSheet, View } from 'react-native';
 import type { ListRenderItemInfo } from 'react-native';
-import {
-  Button,
-  IconButton,
-  Spinner,
-  useThemedStyles,
-} from '@unif/react-native-design';
+import { Button, useThemedStyles } from '@unif/react-native-design';
 import { DEFAULT_END_THRESHOLD } from './constants';
 import { createStyles } from './styles';
 import { useWebPrependAnchor } from './webPrependAnchor';
 import { useMessageListScroll } from './useMessageListScroll';
 import { MessageListRow } from './MessageListRow';
-import type { MessageListHandle, MessageListProps } from './types';
+import { MessageListEndButton } from './MessageListEndButton';
+import type {
+  MessageListCellProps,
+  MessageListHandle,
+  MessageListProps,
+} from './types';
 
 const MAINTAIN_VISIBLE_POSITION = { minIndexForVisible: 0 };
 
@@ -44,16 +50,27 @@ export function MessageList<T>({
 }: MessageListProps<T> & RefAttributes<MessageListHandle>) {
   const styles = useThemedStyles(createStyles);
   const listRef = useRef<FlatList<T>>(null);
+  const listTestID = useRef(testID);
+  listTestID.current = testID;
+  const contentStyle = StyleSheet.flatten(contentContainerStyle);
   const keys = useMemo(() => items.map(keyExtractor), [items, keyExtractor]);
   const { getRowNativeID, preservingPrependRef, cancelPrependPreservation } =
     useWebPrependAnchor({ listRef, itemsIdentity: items, keys });
   const {
     atEnd,
+    anchorMinimumHeight,
+    anchorToItem,
+    onCellLayout,
+    onItemLayout,
+    onCellUnmount,
+    onFooterLayout,
+    onScrollToIndexFailed,
     scrollToEnd,
     onLayout,
     onContentSizeChange,
     onScroll,
     onUserScrollBegin,
+    onMomentumScrollBegin,
     onScrollEndDrag,
     onMomentumScrollEnd,
   } = useMessageListScroll({
@@ -63,16 +80,68 @@ export function MessageList<T>({
     followOutput,
     endThreshold,
     onAtEndChange,
+    hasFooter: !!footer,
+    contentMinimumHeight: contentStyle?.minHeight,
+    contentBottomPadding:
+      contentStyle?.paddingBottom ??
+      contentStyle?.paddingVertical ??
+      contentStyle?.padding,
     preservingPrependRef,
     cancelPrependPreservation,
   });
-  useImperativeHandle(ref, () => ({ scrollToEnd }), [scrollToEnd]);
+  useImperativeHandle(ref, () => ({ scrollToEnd, anchorToItem }), [
+    scrollToEnd,
+    anchorToItem,
+  ]);
+
+  const CellRenderer = useCallback(
+    function MessageListCell({
+      cellKey,
+      index,
+      children,
+      style: cellStyle,
+      onLayout: reportLayout,
+      onFocusCapture,
+    }: MessageListCellProps<T>) {
+      const currentIndex = useRef(index);
+      currentIndex.current = index;
+      useLayoutEffect(
+        () => () => onCellUnmount(cellKey, currentIndex.current),
+        [cellKey]
+      );
+      return (
+        <View
+          style={cellStyle}
+          onFocusCapture={onFocusCapture}
+          testID={
+            listTestID.current
+              ? `${listTestID.current}-cell-${encodeURIComponent(cellKey)}`
+              : undefined
+          }
+          onLayout={(event) => {
+            reportLayout?.(event);
+            onCellLayout(cellKey, index, event.nativeEvent.layout);
+          }}
+        >
+          {children}
+        </View>
+      );
+    },
+    [onCellLayout, onCellUnmount]
+  );
 
   const renderRow = useCallback(
     ({ item, index }: ListRenderItemInfo<T>) => (
       <MessageListRow
         item={item}
         index={index}
+        itemKey={keys[index]!}
+        onItemLayout={onItemLayout}
+        testID={
+          testID
+            ? `${testID}-item-${encodeURIComponent(keys[index]!)}`
+            : undefined
+        }
         previous={renderSeparator ? items[index - 1] : undefined}
         nativeID={getRowNativeID(keys[index]!)}
         renderItem={renderItem}
@@ -80,7 +149,16 @@ export function MessageList<T>({
         extraData={extraData}
       />
     ),
-    [extraData, getRowNativeID, items, keys, renderItem, renderSeparator]
+    [
+      extraData,
+      getRowNativeID,
+      items,
+      keys,
+      onItemLayout,
+      renderItem,
+      renderSeparator,
+      testID,
+    ]
   );
 
   const history = hasEarlier && onRequestEarlier;
@@ -103,8 +181,9 @@ export function MessageList<T>({
     [hasHeader, header, history, loadingEarlier, onRequestEarlier]
   );
   const listFooter = useMemo(
-    () => (footer ? <View>{footer}</View> : undefined),
-    [footer]
+    () =>
+      footer ? <View onLayout={onFooterLayout}>{footer}</View> : undefined,
+    [footer, onFooterLayout]
   );
   const listEmpty = useMemo(() => (empty ? <>{empty}</> : undefined), [empty]);
   return (
@@ -117,14 +196,21 @@ export function MessageList<T>({
         keyExtractor={keyExtractor}
         extraData={extraData}
         renderItem={renderRow}
+        CellRendererComponent={CellRenderer}
         ListHeaderComponent={listHeader}
         ListFooterComponent={listFooter}
         ListEmptyComponent={listEmpty}
         maintainVisibleContentPosition={
-          items.length > 0 ? MAINTAIN_VISIBLE_POSITION : undefined
+          items.length > 0 && anchorMinimumHeight === undefined
+            ? MAINTAIN_VISIBLE_POSITION
+            : undefined
         }
         keyboardDismissMode={keyboardDismissMode}
-        contentContainerStyle={contentContainerStyle}
+        contentContainerStyle={
+          anchorMinimumHeight
+            ? [contentContainerStyle, { minHeight: anchorMinimumHeight }]
+            : contentContainerStyle
+        }
         showsVerticalScrollIndicator={showsVerticalScrollIndicator}
         keyboardShouldPersistTaps="handled"
         scrollEventThrottle={16}
@@ -132,30 +218,16 @@ export function MessageList<T>({
         onContentSizeChange={onContentSizeChange}
         onScroll={onScroll}
         onScrollBeginDrag={onUserScrollBegin}
-        onMomentumScrollBegin={onUserScrollBegin}
+        onMomentumScrollBegin={onMomentumScrollBegin}
         onScrollEndDrag={onScrollEndDrag}
         onMomentumScrollEnd={onMomentumScrollEnd}
+        onScrollToIndexFailed={onScrollToIndexFailed}
       />
       {showScrollToEnd && items.length > 0 && !atEnd ? (
-        <View style={styles.returnToEnd} pointerEvents="box-none">
-          {scrollToEndBusy ? (
-            <View style={styles.returnProgress} pointerEvents="none">
-              <Spinner size={44} thickness={2} />
-            </View>
-          ) : null}
-          <IconButton
-            icon="arrow-down"
-            accessibilityLabel={
-              scrollToEndBusy ? '回到最新消息，正在处理' : '回到最新消息'
-            }
-            variant="ghost"
-            size="md"
-            surfaceSize={36}
-            iconSize={18}
-            style={styles.returnButton}
-            onPress={() => scrollToEnd()}
-          />
-        </View>
+        <MessageListEndButton
+          busy={scrollToEndBusy}
+          onPress={() => scrollToEnd()}
+        />
       ) : null}
     </View>
   );

package/src/components/MessageList/MessageListEndButton.tsx

@@ -0,0 +1,61 @@
+import { useEffect, useRef } from 'react';
+import { Animated, View } from 'react-native';
+import {
+  IconButton,
+  Reveal,
+  Spinner,
+  usePrefersReducedMotion,
+  useThemedStyles,
+} from '@unif/react-native-design';
+import { createStyles } from './styles';
+import type { MessageListEndButtonProps } from './types';
+
+export function MessageListEndButton({
+  busy,
+  onPress,
+}: MessageListEndButtonProps) {
+  const styles = useThemedStyles(createStyles);
+  const reducedMotion = usePrefersReducedMotion();
+  const scale = useRef(new Animated.Value(reducedMotion ? 1 : 0.8)).current;
+  useEffect(() => {
+    if (reducedMotion) {
+      scale.setValue(1);
+      return;
+    }
+    const animation = Animated.spring(scale, {
+      toValue: 1,
+      friction: 6,
+      tension: 120,
+      useNativeDriver: true,
+    });
+    animation.start();
+    return () => animation.stop();
+  }, [reducedMotion, scale]);
+  return (
+    <View style={styles.returnToEnd} pointerEvents="box-none">
+      <Reveal>
+        <Animated.View
+          style={[styles.returnVisual, { transform: [{ scale }] }]}
+        >
+          {busy ? (
+            <View style={styles.returnProgress} pointerEvents="none">
+              <Spinner size={44} thickness={2} />
+            </View>
+          ) : null}
+          <IconButton
+            icon="arrow-down"
+            accessibilityLabel={
+              busy ? '回到最新消息，正在处理' : '回到最新消息'
+            }
+            variant="ghost"
+            size="md"
+            surfaceSize={36}
+            iconSize={18}
+            style={styles.returnButton}
+            onPress={onPress}
+          />
+        </Animated.View>
+      </Reveal>
+    </View>
+  );
+}

package/src/components/MessageList/MessageListRow.tsx

@@ -1,29 +1,29 @@
 import { memo } from 'react';
 import { View } from 'react-native';
-import type { MessageListProps } from './types';
-
-interface MessageListRowProps<T> extends Pick<
-  MessageListProps<T>,
-  'renderItem' | 'renderSeparator' | 'extraData'
-> {
-  item: T;
-  previous: T | undefined;
-  index: number;
-  nativeID: string;
-}
+import type { MessageListRowProps } from './types';
 
 function MessageListRowContent<T>({
   item,
   previous,
   index,
   nativeID,
+  itemKey,
+  testID,
+  onItemLayout,
   renderItem,
   renderSeparator,
 }: MessageListRowProps<T>) {
   return (
     <View nativeID={nativeID}>
       {index > 0 && renderSeparator ? renderSeparator(previous!, item) : null}
-      {renderItem(item, index)}
+      <View
+        testID={testID}
+        onLayout={(event) =>
+          onItemLayout(itemKey, index, event.nativeEvent.layout.y)
+        }
+      >
+        {renderItem(item, index)}
+      </View>
     </View>
   );
 }

package/src/components/MessageList/index.ts

@@ -1,5 +1,6 @@
 export { MessageList } from './MessageList';
 export type {
+  MessageListAnchorOptions,
   MessageListHandle,
   MessageListProps,
   MessageListScrollOptions,

package/src/components/MessageList/styles.ts

@@ -14,6 +14,12 @@ export const createStyles = (colors: ColorTokens, shadows: ShadowTokens) =>
       justifyContent: 'center',
     },
     returnProgress: StyleSheet.absoluteFill,
+    returnVisual: {
+      width: 44,
+      height: 44,
+      alignItems: 'center',
+      justifyContent: 'center',
+    },
     returnButton: {
       alignSelf: 'center',
       borderRadius: 18,

package/src/components/MessageList/types.ts

@@ -1,11 +1,23 @@
-import type { ReactNode } from 'react';
-import type { ScrollViewProps, StyleProp, ViewStyle } from 'react-native';
+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 {
   scrollToEnd(options?: MessageListScrollOptions): void;
+  /** 按稳定 key 等待真实布局并顶锚；用户拖动、回到末尾或目标删除时结束。 */
+  anchorToItem(key: string, options?: MessageListAnchorOptions): void;
 }
 export interface MessageListProps<T> {
   items: readonly T[];
@@ -33,8 +45,46 @@ export interface MessageListProps<T> {
   testID?: string;
 }
 export interface ListMeasurements {
+  width: number;
   viewport: number;
   content: number;
   offset: number;
   hasContentSize: boolean;
 }
+export type MessageListCellProps<T> = ComponentProps<
+  NonNullable<FlatListProps<T>['CellRendererComponent']>
+>;
+export interface MessageListRowProps<T> extends Pick<
+  MessageListProps<T>,
+  'renderItem' | 'renderSeparator' | 'extraData'
+> {
+  item: T;
+  previous: T | undefined;
+  index: number;
+  itemKey: string;
+  nativeID: string;
+  testID?: string;
+  onItemLayout(key: string, index: number, y: number): void;
+}
+export interface MessageListItemLayout {
+  index: number;
+  cell?: LayoutRectangle;
+  itemY?: number;
+}
+export interface MessageListAnchorRequest {
+  key: string;
+  topOffset: number;
+  animated: boolean;
+  seen: boolean;
+  locatedAt?: number;
+  offset?: number;
+  viewport?: number;
+  settled?: boolean;
+}
+export interface MessageListPendingScroll extends MessageListScrollOptions {
+  contentBeforeRelease?: number;
+}
+export interface MessageListEndButtonProps {
+  busy: boolean;
+  onPress(): void;
+}