@seakoi/native-ui 1.2.0 → 1.3.0

package/src/components/base/overflow/fixed-count-overflow.tsx

@@ -0,0 +1,71 @@
+import React, { useCallback, useEffect } from 'react';
+import { Text, View } from 'react-native';
+
+import { type useOverflowStyles } from './style';
+import type { OverflowProps } from './types';
+
+/**
+ * 固定数量模式组件
+ */
+export const FixedCountOverflow = <ItemType = unknown,>({
+  data,
+  renderItem,
+  renderRest,
+  maxCount,
+  prefix,
+  suffix,
+  style,
+  prefixStyle,
+  itemStyle,
+  suffixStyle,
+  restStyle,
+  onVisibleCountChange,
+  styles,
+  getKey,
+}: OverflowProps<ItemType> & {
+  styles: ReturnType<typeof useOverflowStyles>;
+  getKey: (item: ItemType, index: number) => React.Key;
+}) => {
+  const visibleCount = Math.min(data.length, maxCount as number);
+  const showRest = data.length > (maxCount as number);
+  const omittedData = data.slice(maxCount as number);
+
+  useEffect(() => {
+    onVisibleCountChange?.(visibleCount);
+  }, [visibleCount, onVisibleCountChange]);
+
+  const renderRestContent = useCallback(() => {
+    if (typeof renderRest === 'function') {
+      return renderRest(omittedData);
+    }
+    if (renderRest) {
+      return renderRest;
+    }
+    return <Text style={[styles.rest]}>+{omittedData.length}...</Text>;
+  }, [renderRest, omittedData, styles.rest]);
+
+  return (
+    <View style={[styles.container, style]}>
+      {/* 前缀 */}
+      {prefix && <View style={[styles.item, prefixStyle]}>{prefix}</View>}
+
+      {/* 显示固定数量的元素 */}
+      {data.slice(0, visibleCount).map((item, index) => {
+        const key = getKey(item, index);
+        return (
+          <View key={key} style={[styles.item, itemStyle]}>
+            {renderItem(item, { index })}
+          </View>
+        );
+      })}
+
+      {/* 显示剩余数量提示 */}
+      {showRest && (
+        <View style={[styles.item, restStyle]}>{renderRestContent()}</View>
+      )}
+
+      {/* 后缀 */}
+      {suffix && <View style={[styles.item, suffixStyle]}>{suffix}</View>}
+    </View>
+  );
+};

package/src/components/base/overflow/index.ts

@@ -0,0 +1,2 @@
+export * from './overflow';
+export type * from './types';

package/src/components/base/overflow/overflow.tsx

@@ -0,0 +1,60 @@
+import { isNumber } from 'lodash-es';
+import React, { useCallback } from 'react';
+
+import { AllModeOverflow } from './all-mode-overflow';
+import { FixedCountOverflow } from './fixed-count-overflow';
+import { ResponsiveOverflow } from './responsive-overflow';
+import { useOverflowStyles } from './style';
+import type { OverflowProps } from './types';
+
+/**
+ * Overflow 组件
+ *
+ * 利用 onLayout 在渲染前触发的特性，实现单次渲染的溢出处理组件
+ * 固定数量模式直接渲染，响应式模式通过预先计算确定最终显示状态
+ *
+ * @param props - 组件属性
+ * @returns React 元素
+ */
+export const Overflow = <ItemType = unknown,>(props: OverflowProps<ItemType>) => {
+  const { maxCount = 'responsive', itemKey } = props;
+
+  const styles = useOverflowStyles({ maxCount });
+
+  /**
+   * 获取元素唯一标识
+   */
+  const getKey = useCallback(
+    (item: ItemType, index: number): React.Key => {
+      if (typeof itemKey === 'function') {
+        return itemKey(item, index);
+      }
+      if (
+        itemKey &&
+        typeof item === 'object' &&
+        item !== null &&
+        typeof itemKey === 'string'
+      ) {
+        const value = (item as Record<string, unknown>)[itemKey as string];
+        return typeof value === 'string' || typeof value === 'number'
+          ? value
+          : index;
+      }
+      return index;
+    },
+    [itemKey],
+  );
+
+  // 固定数量模式
+  if (isNumber(maxCount)) {
+    return <FixedCountOverflow {...props} styles={styles} getKey={getKey} />;
+  }
+
+  // 全部显示模式
+  if (maxCount === 'all') {
+    return <AllModeOverflow {...props} styles={styles} getKey={getKey} />;
+  }
+
+  // 响应式模式
+  return <ResponsiveOverflow {...props} styles={styles} getKey={getKey} />;
+};

package/src/components/base/overflow/responsive-overflow.tsx

@@ -0,0 +1,349 @@
+import { useMemoizedFn } from 'ahooks';
+import React, { useEffect, useRef, useState } from 'react';
+import { type LayoutChangeEvent, Text, View } from 'react-native';
+
+import { type useOverflowStyles } from './style';
+import type { OverflowProps } from './types';
+
+/**
+ * 测量数据 - 存储所有测量的宽度信息
+ */
+interface MeasurementData {
+  container: number;
+  items: Map<React.Key, number>;
+  prefix: number;
+  suffix: number;
+  rest: number;
+}
+
+/**
+ * 计算结果 - 存储基于测量数据计算出的显示状态
+ */
+interface CalculationResult {
+  visibleCount: number;
+  showRest: boolean;
+}
+
+/**
+ * 响应式 Overflow 组件
+ * 只有在 props 变化时才重新测量，onLayout 不直接触发测量
+ */
+export const ResponsiveOverflow = <ItemType = unknown,>({
+  data,
+  renderItem,
+  renderRest,
+  prefix,
+  suffix,
+  style,
+  prefixStyle,
+  itemStyle,
+  suffixStyle,
+  restStyle,
+  onVisibleCountChange,
+  itemsWidthTolerance = 0,
+  styles,
+  getKey,
+}: OverflowProps<ItemType> & {
+  styles: ReturnType<typeof useOverflowStyles>;
+  getKey: (item: ItemType, index: number) => React.Key;
+}) => {
+  // 测量数据
+  const measurementDataRef = useRef<MeasurementData>({
+    container: 0,
+    items: new Map(),
+    prefix: 0,
+    suffix: 0,
+    rest: 0,
+  });
+
+  // 计算结果
+  const calculationResultRef = useRef<CalculationResult>({
+    visibleCount: 0,
+    showRest: false,
+  });
+
+  // 上一次的结果（用于测量期间的显示优化）
+  const previousResultRef = useRef<CalculationResult>({
+    visibleCount: 0,
+    showRest: false,
+  });
+
+  // 测量完成标记
+  const measurementFlags = useRef({
+    container: false,
+    prefix: false,
+    suffix: false,
+    rest: false,
+    items: new Set<React.Key>(),
+  });
+
+  // 状态管理
+  const [, forceUpdate] = useState({});
+  const [remeasureKey, setRemeasureKey] = useState(0);
+  const isComplete = useRef(false);
+
+  const triggerRerender = useMemoizedFn(() => forceUpdate({}));
+  /**
+   * 重置所有测量状态
+   */
+  const resetMeasurement = useMemoizedFn(() => {
+    if (!isComplete.current) {
+      return;
+    }
+    // 保存当前结果作为上一次的结果
+    previousResultRef.current = { ...calculationResultRef.current };
+
+    measurementDataRef.current = {
+      container: 0,
+      items: new Map(),
+      prefix: 0,
+      suffix: 0,
+      rest: 0,
+    };
+
+    calculationResultRef.current = {
+      visibleCount: 0,
+      showRest: false,
+    };
+
+    isComplete.current = false;
+
+    measurementFlags.current = {
+      container: false,
+      prefix: false,
+      suffix: false,
+      rest: false,
+      items: new Set<React.Key>(),
+    };
+
+    setRemeasureKey(prev => prev + 1);
+  });
+
+  /**
+   * 检查是否所有必要的测量都已完成
+   */
+  const isAllMeasurementsComplete = (): boolean => {
+    const flags = measurementFlags.current;
+
+    if (!flags.container || !flags.rest) return false;
+    if (prefix && !flags.prefix) return false;
+    if (suffix && !flags.suffix) return false;
+
+    // 检查所有元素是否都已测量
+    for (let i = 0; i < data.length; i++) {
+      const key = getKey(data[i], i);
+      if (!flags.items.has(key)) return false;
+    }
+
+    return true;
+  };
+
+  /**
+   * 计算最终显示状态
+   */
+  const calculateDisplayState = (
+    measurementData: MeasurementData,
+  ): CalculationResult => {
+    const { container, items, prefix, suffix, rest } = measurementData;
+
+    if (!container || data.length === 0) {
+      return { visibleCount: 0, showRest: false };
+    }
+
+    const availableWidth = container - prefix - suffix;
+    let currentWidth = 0;
+    let visibleCount = 0;
+
+    // 计算所有元素的总宽度
+    let totalItemsWidth = 0;
+    for (let i = 0; i < data.length; i++) {
+      const key = getKey(data[i], i);
+      const itemWidth = items.get(key) || 0;
+      totalItemsWidth += itemWidth;
+    }
+
+    // 如果所有元素都能放下（考虑容差）
+    if (totalItemsWidth <= availableWidth + itemsWidthTolerance) {
+      return {
+        visibleCount: data.length,
+        showRest: false,
+      };
+    }
+
+    // 需要截断，从前往后累积宽度
+    for (let i = 0; i < data.length; i++) {
+      const key = getKey(data[i], i);
+      const itemWidth = items.get(key) || 0;
+
+      // 检查加上当前元素和rest节点是否会超出
+      if (currentWidth + itemWidth + rest > availableWidth) {
+        // 如果是第一个元素就超出，至少显示一个
+        visibleCount = i === 0 ? 1 : i;
+        break;
+      }
+
+      currentWidth += itemWidth;
+      visibleCount = i + 1;
+    }
+
+    return {
+      visibleCount,
+      showRest: visibleCount < data.length,
+    };
+  };
+
+  /**
+   * 完成测量并更新结果
+   */
+  const completeMeasurement = useMemoizedFn(() => {
+    if (!isAllMeasurementsComplete()) return;
+
+    const result = calculateDisplayState(measurementDataRef.current);
+
+    calculationResultRef.current = result;
+    isComplete.current = true;
+    previousResultRef.current = { ...result };
+
+    onVisibleCountChange?.(result.visibleCount);
+    triggerRerender();
+  });
+
+  // 影响布局的 props 变化时标记需要重新计算
+  useEffect(() => {
+    resetMeasurement();
+  }, [
+    data,
+    renderItem,
+    renderRest,
+    prefix,
+    suffix,
+    style,
+    prefixStyle,
+    itemStyle,
+    suffixStyle,
+    restStyle,
+    onVisibleCountChange,
+    itemsWidthTolerance,
+    styles,
+    getKey,
+  ]);
+
+  /**
+   * 布局测量处理函数
+   */
+  const createLayoutHandler = useMemoizedFn(
+    (elementType: keyof MeasurementData, itemKey?: React.Key) =>
+      (event: LayoutChangeEvent) => {
+        // 测量完成后不再更新数据
+        if (isComplete.current) {
+          return;
+        }
+        const { width } = event.nativeEvent.layout;
+
+        // 更新测量数据和标记
+        if (elementType === 'items') {
+          measurementFlags.current.items.add(itemKey!);
+          measurementDataRef.current.items.set(itemKey!, width);
+        } else {
+          measurementFlags.current[elementType] = true;
+          measurementDataRef.current[elementType] = width;
+        }
+
+        // 检查是否可以完成测量
+        completeMeasurement();
+      },
+  );
+
+  /**
+   * 渲染 Rest 内容
+   */
+  const renderRestContent = () => {
+    const omittedData = data.slice(calculationResultRef.current.visibleCount);
+
+    if (typeof renderRest === 'function') {
+      return renderRest(omittedData);
+    }
+    if (renderRest) {
+      return renderRest;
+    }
+    return <Text style={[styles.rest, restStyle]}>+{omittedData.length}...</Text>;
+  };
+
+  return (
+    <View
+      key={remeasureKey}
+      onLayout={createLayoutHandler('container')}
+      style={[styles.container, style]}
+    >
+      {/* 前缀 */}
+      {prefix && (
+        <View
+          onLayout={createLayoutHandler('prefix')}
+          style={[styles.item, prefixStyle]}
+        >
+          {prefix}
+        </View>
+      )}
+
+      {/* 元素列表 */}
+      {data.map((item, index) => {
+        const key = getKey(item, index);
+
+        // 测量完成后，不渲染超出可见范围的元素
+        if (
+          isComplete.current &&
+          index >= calculationResultRef.current.visibleCount
+        ) {
+          return null;
+        }
+
+        // 测量期间，如果有上一次的结果且当前元素超出上一次的可见范围，需要隐藏
+        const shouldHideInMeasurement =
+          !isComplete.current &&
+          previousResultRef.current.visibleCount > 0 &&
+          index >= previousResultRef.current.visibleCount;
+
+        return (
+          <View
+            key={key}
+            onLayout={createLayoutHandler('items', key)}
+            style={[
+              styles.item,
+              itemStyle,
+              shouldHideInMeasurement && styles.hidden,
+            ]}
+          >
+            {renderItem(item, { index })}
+          </View>
+        );
+      })}
+
+      {/* Rest节点 - 测量期间始终渲染以获取宽度，测量完成后根据需要渲染 */}
+      {!isComplete.current || calculationResultRef.current.showRest ? (
+        <View
+          onLayout={createLayoutHandler('rest')}
+          style={[
+            styles.item,
+            restStyle,
+            // 测量期间隐藏，测量完成后根据 showRest 决定是否隐藏
+            !isComplete.current &&
+              !previousResultRef.current.showRest &&
+              styles.hidden,
+          ]}
+        >
+          {renderRestContent()}
+        </View>
+      ) : null}
+
+      {/* 后缀 */}
+      {suffix && (
+        <View
+          onLayout={createLayoutHandler('suffix')}
+          style={[styles.item, suffixStyle]}
+        >
+          {suffix}
+        </View>
+      )}
+    </View>
+  );
+};

package/src/components/base/overflow/style/index.ts

@@ -0,0 +1,32 @@
+import { createThemedStyles } from '#native-provider';
+
+/**
+ * 创建样式
+ */
+export const useOverflowStyles = createThemedStyles((theme, { maxCount }) => ({
+  container: {
+    flexDirection: 'row',
+    flexWrap: maxCount === 'responsive' ? 'nowrap' : 'wrap',
+    overflow: 'hidden',
+    width: '100%',
+  },
+  item: {
+    flexShrink: 0,
+    paddingHorizontal: theme.spacing.xxs / 2,
+    paddingVertical: theme.spacing.xxs / 4,
+  },
+  rest: {
+    backgroundColor: theme.palette.gray1,
+    borderRadius: theme.roundness.sm,
+    paddingHorizontal: theme.spacing.xs,
+    height: '100%',
+    display: 'flex',
+    alignItems: 'center',
+    color: theme.palette.fontGray3,
+  },
+  hidden: {
+    opacity: 0,
+    pointerEvents: 'none',
+    position: 'absolute',
+  },
+}));

package/src/components/base/overflow/types.ts

@@ -0,0 +1,75 @@
+import type React from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+
+/**
+ * Overflow 组件属性
+ */
+export interface OverflowProps<ItemType = unknown> {
+  /**
+   * 数据源
+   */
+  data: ItemType[];
+  /**
+   * 获取元素唯一标识
+   * @default (item, index) => index
+   */
+  itemKey?: keyof ItemType | ((item: ItemType, index: number) => React.Key);
+  /**
+   * 渲染单个元素
+   * @param item 数据项
+   * @param info 渲染信息（索引）
+   */
+  renderItem: (item: ItemType, info: { index: number }) => React.ReactNode;
+  /**
+   * 渲染"更多"节点
+   * @param omittedItems 被折叠的元素数组
+   * @default (items) => `+${items.length}...`
+   */
+  renderRest?: React.ReactNode | ((omittedItems: ItemType[]) => React.ReactNode);
+  /**
+   * 最大显示数量
+   * - 'responsive': 响应式模式,根据容器宽度自动计算
+   * - 'all': 显示所有内容,不进行任何截断
+   * - number: 固定显示数量
+   * @default 'responsive'
+   */
+  maxCount?: number | 'responsive' | 'all';
+  /**
+   * 前缀元素
+   */
+  prefix?: React.ReactNode;
+  /**
+   * 后缀元素
+   */
+  suffix?: React.ReactNode;
+  /**
+   * 容器样式
+   */
+  style?: StyleProp<ViewStyle>;
+  /**
+   * 前缀元素样式
+   */
+  prefixStyle?: StyleProp<ViewStyle>;
+  /**
+   * 数据项元素样式
+   */
+  itemStyle?: StyleProp<ViewStyle>;
+  /**
+   * 后缀元素样式
+   */
+  suffixStyle?: StyleProp<ViewStyle>;
+  /**
+   * "更多"节点样式
+   */
+  restStyle?: StyleProp<ViewStyle>;
+  /**
+   * 可见元素数量变化回调
+   * @param visibleCount 当前可见的元素数量
+   */
+  onVisibleCountChange?: (visibleCount: number) => void;
+  /**
+   * 在响应式模式下,当元素总宽度超出容器宽度但在容差范围内时,仍然显示全部元素而不截断
+   * @default 0
+   */
+  itemsWidthTolerance?: number;
+}

package/src/components/base/picker/picker-content.tsx

@@ -11,21 +11,35 @@ import {
 import type { Any } from '#shared/utils';
 
 import { PickerContext } from './picker-context';
+import { usePickerContentStyles } from './style';
 
+/**
+ * Picker 内容组件的属性接口
+ * 继承自 Modal 组件,排除 visible 和 children 属性
+ */
 export interface PickerContentProps
   extends Omit<ModalProps, 'visible' | 'children'> {
+  /** 是否隐藏头部关闭图标 */
   hiddenHeaderCloseIcon?: boolean;
+  /** 头部标题内容 */
   headerTitle?: React.ReactNode;
+  /** 头部样式 */
   headerStyle?: StyleProp<ViewStyle>;
+  /** 子元素,可以是 React 元素或渲染函数 */
   children?:
     | React.ReactElement
     | ((props: {
+        /** 当前选中的值 */
         value: Any;
+        /** 值变化回调函数 */
         onChange?: (value: Any) => void;
       }) => React.ReactElement);
+  /** 内容区域样式 */
+  style?: StyleProp<ViewStyle>;
 }
 
 export const PickerContent: React.FC<PickerContentProps> = ({
+  style,
   children,
   headerTitle,
   headerStyle,
@@ -33,22 +47,23 @@ export const PickerContent: React.FC<PickerContentProps> = ({
   ...modalProps
 }) => {
   const context = useContext(PickerContext);
+  const styles = usePickerContentStyles();
 
   let childNode: React.ReactElement<Any> | null = null;
 
+  const injectToChildrenProps = {
+    value: context?.value,
+    onChange: context?.onChange,
+  };
+
   if (React.isValidElement(children)) {
-    childNode = React.cloneElement<Any>(children, {
-      value: context?.value,
-      onChange: context?.onChange,
-    });
+    childNode = React.cloneElement<Any>(children, injectToChildrenProps);
   } else if (typeof children === 'function') {
-    childNode = children({
-      value: context?.value,
-      onChange: context?.onChange,
-    });
+    childNode = children(injectToChildrenProps);
   }
   useEffect(() => {
     context?.setDisabled?.(!!childNode?.props?.disabled);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [childNode?.props?.disabled, context?.setDisabled]);
 
   return (
@@ -60,7 +75,7 @@ export const PickerContent: React.FC<PickerContentProps> = ({
         {...modalProps}
         visible={!!context?.visible}
       >
-        <Flex vertical align="stretch" gap={16} style={{ flex: 1, padding: 16 }}>
+        <Flex vertical align="stretch" gap={16} style={[styles.container, style]}>
           <ModalHeader
             title={headerTitle}
             style={headerStyle}