zkit-ui 2.0.4 → 2.0.6

package/src/services/ImagePreviewService/README.md

@@ -2,6 +2,8 @@
 
 `ImagePreview` 是全屏图片预览基础件，支持 iOS / Android / Web 的统一声明式使用，也提供 `imagePreview.open()` 作为全局命令式入口。
 
+如果需要从真实缩略图原生共享转场到全屏 viewer，请使用 `NativeImagePreview`。`ImagePreview` 适合普通命令式预览，`NativeImagePreview` 适合相册九宫格、瀑布流和商品图集这类有稳定图片锚点的场景。
+
 ## 设计取舍
 
 - 核心是声明式组件：`open/defaultOpen` 控制显隐，`value/defaultValue/onChange` 控制当前图片索引。
@@ -60,6 +62,23 @@ console.log(result.reason, result.value);
 - `renderHeader/renderFooter/renderOverlay`：自定义顶部、底部和覆盖层内容。
 - `onClose`：关闭动画结束后触发，返回最终索引、图片和关闭原因。
 
+## NativeImagePreview 关系
+
+```tsx
+import { NativeImagePreview } from 'zkit-ui/native-image-preview';
+
+<NativeImagePreview items={items} colorScheme="dark">
+  <NativeImagePreview.Item index={0}>
+    <Image source={thumbnailSource} />
+  </NativeImagePreview.Item>
+</NativeImagePreview>;
+```
+
+两者不要混用成同一个本地封装：
+
+- `ImagePreview`：普通全屏预览，支持声明式 `open/value` 和命令式 `imagePreview.open()`。
+- `NativeImagePreview`：共享转场预览，需要包住真实缩略图节点，iOS / Android 走原生 viewer，Web 走 H5 viewer。
+
 ## 手动确认点
 
 - Android：Modal 返回键、下滑关闭后的状态回收、超长图/大图内存表现。

package/src/types.d.ts

@@ -0,0 +1 @@
+declare module '*.css';

package/src/ui/NativeImagePreview/NativeImagePreview.tsx

@@ -0,0 +1,146 @@
+import { requireNativeView } from 'expo';
+import * as React from 'react';
+import { Platform, View, useColorScheme } from 'react-native';
+import type { StyleProp, ViewStyle } from 'react-native';
+import {
+  controlEdgeToEdgeValues,
+  isEdgeToEdge,
+} from 'react-native-is-edge-to-edge';
+import { NativeImagePreviewContext } from './context';
+import type {
+  NativeImagePreviewChangeEvent,
+  NativeImagePreviewComponent,
+  NativeImagePreviewItemProps,
+  NativeImagePreviewNativeItem,
+  NativeImagePreviewProps,
+} from './types';
+import {
+  clampPreviewIndex,
+  normalizeNativeImagePreviewItems,
+  resolveNativeImagePreviewColorScheme,
+  toNativePreviewItems,
+} from './utils';
+
+type NativePreviewViewProps = {
+  children: React.ReactElement;
+  index: number;
+  style?: StyleProp<ViewStyle>;
+  previewGroupId: string;
+  items: readonly NativeImagePreviewNativeItem[];
+  theme: 'dark' | 'light';
+  edgeToEdge: boolean;
+  closeIconName?: string;
+  onIndexChange?: (event: NativeImagePreviewChangeEvent) => void;
+};
+
+const NativePreviewView = requireNativeView<NativePreviewViewProps>(
+  'ZKitNativeImagePreview'
+);
+
+const ANDROID_EDGE_TO_EDGE = Platform.OS === 'android' ? isEdgeToEdge() : false;
+
+function createPreviewGroupId() {
+  return `zkit-native-image-preview-${Date.now().toString(36)}-${Math.random()
+    .toString(36)
+    .slice(2, 10)}`;
+}
+
+const NativeImagePreviewRoot = React.memo(function NativeImagePreview({
+  children,
+  colorScheme = 'dark',
+  disabled = false,
+  edgeToEdge = false,
+  items,
+  nativeProps,
+  onChange,
+}: NativeImagePreviewProps) {
+  const systemColorScheme = useColorScheme();
+  const previewGroupIdRef = React.useRef<string | null>(null);
+  if (previewGroupIdRef.current == null) {
+    previewGroupIdRef.current = createPreviewGroupId();
+  }
+
+  const resolvedItems = React.useMemo(
+    () => normalizeNativeImagePreviewItems(items),
+    [items]
+  );
+  const nativeItems = React.useMemo(
+    () => toNativePreviewItems(resolvedItems),
+    [resolvedItems]
+  );
+  const resolvedColorScheme = resolveNativeImagePreviewColorScheme(colorScheme, systemColorScheme);
+  const contextValue = React.useMemo(
+    () => ({
+      previewGroupId: previewGroupIdRef.current!,
+      items: resolvedItems,
+      nativeItems,
+      colorScheme: resolvedColorScheme,
+      disabled,
+      edgeToEdge,
+      nativeProps,
+      onChange,
+    }),
+    [disabled, edgeToEdge, nativeItems, nativeProps, onChange, resolvedColorScheme, resolvedItems]
+  );
+
+  return (
+    <NativeImagePreviewContext.Provider value={contextValue}>
+      {children}
+    </NativeImagePreviewContext.Provider>
+  );
+});
+
+const NativeImagePreviewItem = React.memo(function NativeImagePreviewItem({
+  children,
+  disabled = false,
+  index,
+  onChange,
+  style,
+}: NativeImagePreviewItemProps) {
+  const context = React.useContext(NativeImagePreviewContext);
+
+  const handleIndexChange = React.useCallback(
+    (event: NativeImagePreviewChangeEvent) => {
+      if (!context) return;
+
+      const value = event.nativeEvent.currentIndex;
+      const meta = {
+        reason: 'swipe' as const,
+        item: context.items[value] ?? null,
+        nativeEvent: event,
+      };
+      context.onChange?.(value, meta);
+      onChange?.(value, meta);
+    },
+    [context, onChange]
+  );
+
+  if (!context || context.disabled || disabled || context.nativeItems.length === 0) {
+    return <View style={style}>{children}</View>;
+  }
+
+  const resolvedEdgeToEdge = ANDROID_EDGE_TO_EDGE || context.edgeToEdge;
+
+  if (__DEV__ && Platform.OS === 'android') {
+    controlEdgeToEdgeValues({ edgeToEdge: resolvedEdgeToEdge });
+  }
+
+  return (
+    <NativePreviewView
+      closeIconName={context.nativeProps?.iosCloseIconName}
+      edgeToEdge={resolvedEdgeToEdge}
+      previewGroupId={context.previewGroupId}
+      index={clampPreviewIndex(index, context.nativeItems.length)}
+      items={context.nativeItems}
+      onIndexChange={handleIndexChange}
+      style={style}
+      theme={context.colorScheme}
+    >
+      {children}
+    </NativePreviewView>
+  );
+});
+
+export const NativeImagePreview = Object.assign(NativeImagePreviewRoot, {
+  Item: NativeImagePreviewItem,
+}) as NativeImagePreviewComponent;

package/src/ui/NativeImagePreview/NativeImagePreview.web.tsx

@@ -0,0 +1,201 @@
+/// <reference lib="dom" />
+
+import './web/styles.css';
+
+import * as React from 'react';
+import { View, useColorScheme } from 'react-native';
+import { clampPreviewIndex, normalizeNativeImagePreviewItems, resolveNativeImagePreviewColorScheme } from './utils';
+import type {
+  NativeImagePreviewChangeMeta,
+  NativeImagePreviewComponent,
+  NativeImagePreviewItemProps,
+  NativeImagePreviewProps,
+  NativeImagePreviewResolvedItem,
+} from './types';
+import { createNativeImagePreviewWeb } from './web/viewer';
+import type {
+  NativeImagePreviewWebChangeMeta,
+  NativeImagePreviewWebController,
+  NativeImagePreviewWebMediaItem,
+} from './web/types';
+
+type SourceElement = HTMLElement | null;
+
+type NativeImagePreviewWebContextValue = {
+  disabled: boolean;
+  items: readonly NativeImagePreviewResolvedItem[];
+  open: (
+    index: number,
+    onItemChange?: (value: number, meta: NativeImagePreviewChangeMeta) => void
+  ) => void;
+  sourceElementsRef: { current: SourceElement[] };
+};
+
+const NativeImagePreviewWebContext =
+  React.createContext<NativeImagePreviewWebContextValue | null>(null);
+
+const WebView = View as unknown as React.ElementType;
+
+function toWebPreviewItems(
+  items: readonly NativeImagePreviewResolvedItem[]
+): NativeImagePreviewWebMediaItem[] {
+  return items.map(({ alt, height, id, poster, type, url, width }) => ({
+    alt: alt ?? id,
+    height,
+    id,
+    poster,
+    type,
+    url,
+    width,
+  }));
+}
+
+function findPreviewSourceElement(element: SourceElement): SourceElement {
+  if (!element) return null;
+  if (element instanceof HTMLImageElement || element instanceof HTMLVideoElement) {
+    return element;
+  }
+  return element.querySelector('img, video') ?? element;
+}
+
+function toChangeMeta(
+  meta: NativeImagePreviewWebChangeMeta,
+  items: readonly NativeImagePreviewResolvedItem[]
+): NativeImagePreviewChangeMeta {
+  return {
+    reason: meta.reason,
+    item: items[meta.index] ?? null,
+  };
+}
+
+const NativeImagePreviewRoot = React.memo(function NativeImagePreview({
+  children,
+  colorScheme = 'dark',
+  disabled = false,
+  items,
+  onChange,
+}: NativeImagePreviewProps) {
+  const systemColorScheme = useColorScheme();
+  const controllerRef = React.useRef<NativeImagePreviewWebController | null>(null);
+  const sourceElementsRef = React.useRef<SourceElement[]>([]);
+  const resolvedItems = React.useMemo(
+    () => normalizeNativeImagePreviewItems(items),
+    [items]
+  );
+  const webItems = React.useMemo(
+    () => toWebPreviewItems(resolvedItems),
+    [resolvedItems]
+  );
+  const resolvedColorScheme = resolveNativeImagePreviewColorScheme(colorScheme, systemColorScheme);
+
+  React.useEffect(() => {
+    const controller = createNativeImagePreviewWeb();
+    controllerRef.current = controller;
+
+    return () => {
+      controller.destroy();
+      controllerRef.current = null;
+    };
+  }, []);
+
+  const open = React.useCallback<NativeImagePreviewWebContextValue['open']>(
+    (index, onItemChange) => {
+      const controller = controllerRef.current;
+      if (disabled || !controller || webItems.length === 0) return;
+
+      const value = clampPreviewIndex(index, webItems.length);
+      const getSourceElement = (nextIndex: number) =>
+        findPreviewSourceElement(sourceElementsRef.current[nextIndex] ?? null);
+
+      void controller.open({
+        getSourceElement,
+        index: value,
+        items: webItems,
+        objectFit: 'cover',
+        sourceElement: getSourceElement(value),
+        sourceImageSize: resolvedItems[value]
+          ? {
+              width: resolvedItems[value].width ?? 0,
+              height: resolvedItems[value].height ?? 0,
+            }
+          : null,
+        sourceObjectFit: 'cover',
+        sourceVisibility: 'hidden',
+        theme: resolvedColorScheme,
+        onChange: (nextValue, meta) => {
+          const changeMeta = toChangeMeta(meta, resolvedItems);
+          onChange?.(nextValue, changeMeta);
+          onItemChange?.(nextValue, changeMeta);
+        },
+      });
+    },
+    [disabled, onChange, resolvedColorScheme, resolvedItems, webItems]
+  );
+
+  const contextValue = React.useMemo<NativeImagePreviewWebContextValue>(
+    () => ({
+      disabled,
+      items: resolvedItems,
+      open,
+      sourceElementsRef,
+    }),
+    [disabled, open, resolvedItems]
+  );
+
+  return (
+    <NativeImagePreviewWebContext.Provider value={contextValue}>
+      {children}
+    </NativeImagePreviewWebContext.Provider>
+  );
+});
+
+const NativeImagePreviewItem = React.memo(function NativeImagePreviewItem({
+  children,
+  disabled = false,
+  index,
+  onChange,
+  style,
+}: NativeImagePreviewItemProps) {
+  const context = React.useContext(NativeImagePreviewWebContext);
+  const sourceRef = React.useCallback(
+    (node: SourceElement) => {
+      if (!context) return;
+      context.sourceElementsRef.current[index] = node;
+    },
+    [context, index]
+  );
+  const itemDisabled = !context || context.disabled || disabled || context.items.length === 0;
+
+  const open = React.useCallback(() => {
+    if (itemDisabled) return;
+    context.open(index, onChange);
+  }, [context, index, itemDisabled, onChange]);
+
+  const handleKeyDown = React.useCallback(
+    (event: React.KeyboardEvent) => {
+      if (itemDisabled) return;
+      if (event.key !== 'Enter' && event.key !== ' ') return;
+      event.preventDefault();
+      open();
+    },
+    [itemDisabled, open]
+  );
+
+  return (
+    <WebView
+      ref={sourceRef}
+      aria-label={itemDisabled ? undefined : 'Open image preview'}
+      onClick={itemDisabled ? undefined : open}
+      onKeyDown={itemDisabled ? undefined : handleKeyDown}
+      role={itemDisabled ? undefined : 'button'}
+      style={style}
+      tabIndex={itemDisabled ? undefined : 0}
+    >
+      {children}
+    </WebView>
+  );
+});
+
+export const NativeImagePreview = Object.assign(NativeImagePreviewRoot, {
+  Item: NativeImagePreviewItem,
+}) as NativeImagePreviewComponent;

package/src/ui/NativeImagePreview/README.md

@@ -0,0 +1,111 @@
+# NativeImagePreview
+
+`NativeImagePreview` 是强调真实缩略图锚点与共享转场体验的图片预览组件。它和普通 `ImagePreview` 服务分工不同：`ImagePreview` 适合命令式打开图片；`NativeImagePreview` 适合从真实缩略图自然过渡到全屏 viewer，并在 iOS / Android 上走原生手势、缩放、滑动和拖拽关闭路径，在 Web 上走 H5 共享转场 viewer。
+
+## 适用场景
+
+- 相册九宫格、瀑布流、商品图集这类有真实缩略图锚点的页面。
+- 需要从缩略图拾取到全屏 viewer，再从 viewer 顺滑回到原缩略图的位置。
+- 需要原生 pinch / pan / swipe / drag-to-close 手势链路，而不是普通 Modal 图片预览。
+
+如果只是从富文本、消息流或按钮命令式打开图片，用 `ImagePreview` 或 `imagePreview.open()` 更合适。
+
+## 基础用法
+
+```tsx
+import { Image, type ImageSourcePropType } from 'react-native';
+import { NativeImagePreview, type NativeImagePreviewItemDescriptor } from 'zkit-ui/native-image-preview';
+
+const items: NativeImagePreviewItemDescriptor[] = [
+  { id: 'photo-a', source: require('./photo-a.png') },
+  { id: 'photo-b', source: require('./photo-b.png'), width: 1200, height: 900 },
+  { id: 'clip', type: 'video', url: videoUrl, poster: require('./poster.png') },
+];
+
+function getThumbnailSource(item: NativeImagePreviewItemDescriptor): ImageSourcePropType | undefined {
+  const source = item.poster ?? item.source;
+  return typeof source === 'string' ? { uri: source } : source;
+}
+
+export function Demo() {
+  return (
+    <NativeImagePreview items={items} colorScheme="dark">
+      {items.map((item, index) => {
+        const thumbnailSource = getThumbnailSource(item);
+        if (!thumbnailSource) return null;
+
+        return (
+          <NativeImagePreview.Item index={index} key={item.id ?? index}>
+            <Image source={thumbnailSource} />
+          </NativeImagePreview.Item>
+        );
+      })}
+    </NativeImagePreview>
+  );
+}
+```
+
+`NativeImagePreview.Item` 必须包住真实图片节点，原生层会从内部找到 `UIImageView` / `ImageView` 作为转场锚点。不要用普通 `View` 替代缩略图，否则共享转场会退化。
+
+## 推荐数据模型
+
+```ts
+type NativeImagePreviewItem =
+  | string
+  | ImageSourcePropType
+  | {
+      id?: string;
+      type?: 'image' | 'video';
+      source?: string | ImageSourcePropType;
+      url?: string;
+      poster?: string | ImageSourcePropType;
+      width?: number;
+      height?: number;
+    };
+```
+
+- 图片可以只传 `source`，也可以用字符串 URL。
+- 视频必须传 `type: 'video'` 和 `url`，`poster` 用于缩略图和过渡封面。
+- `id` 用于稳定媒体身份；不传时会回退为索引字符串。
+- `width / height` 是媒体元信息，帮助 viewer 更稳定地计算布局。
+
+## Props
+
+### NativeImagePreview
+
+- `items`：图片或媒体集合，顺序必须和 `NativeImagePreview.Item index` 对齐。
+- `colorScheme`：viewer 明暗外观，支持 `dark / light / system`，默认 `dark`。
+- `disabled`：禁用所有锚点预览。
+- `edgeToEdge`：Android edge-to-edge 预览，默认关闭；系统已处于 edge-to-edge 时会自动启用。
+- `nativeProps.iosCloseIconName`：iOS 关闭按钮 SF Symbol 名称。
+- `onChange(value, meta)`：viewer 滑动到新索引时触发。
+
+### NativeImagePreview.Item
+
+- `index`：当前缩略图在 `items` 中的索引。
+- `disabled`：禁用当前锚点。
+- `style`：锚点容器样式，常用 `StyleSheet.absoluteFill` 覆盖图片卡片。
+- `onChange(value, meta)`：仅当前锚点打开的 viewer 发生索引变化时触发。
+
+## 与 ImagePreview 的区别
+
+```tsx
+import { imagePreview } from 'zkit-ui/image-preview';
+
+imagePreview.open({ images, index: 0 });
+```
+
+`ImagePreview` 是普通全屏预览服务，适合没有稳定缩略图锚点的命令式场景。`NativeImagePreview` 是声明式共享转场组件，必须就地包住真实图片节点。两者不要混成同一个封装，否则很容易把共享转场退化成普通弹层。
+
+## 平台行为
+
+- iOS / Android：使用原生 viewer 和真实图片锚点，主打共享转场、缩放、滑动和拖拽关闭。
+- Web：使用 H5 viewer 和真实 DOM 图片锚点，支持共享转场、缩放、滑动、视频播放和拖拽关闭。
+- 首次接入或变更原生依赖后需要重新构建 native app；仅刷新 JS bundle 不会注册新的原生 ViewManager。
+- 原生模块未注册时不会降级到 `ImagePreview`。这是 native 接入或构建错误，需要重新安装依赖并重建 native app。
+
+## 手动确认点
+
+- iOS：缩略图拾取和回落位置、快速左右滑、视频封面、横竖屏、安全区、关闭按钮。
+- Android：edge-to-edge、返回键、快速滑动、列表复用、视频页、普通机型掉帧情况。
+- 列表场景：确保 `items` 顺序、`Item index` 和缩略图渲染顺序稳定一致。

package/src/ui/NativeImagePreview/context.tsx

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import type {
+  NativeImagePreviewChangeMeta,
+  NativeImagePreviewNativeItem,
+  NativeImagePreviewNativeProps,
+  NativeImagePreviewResolvedItem,
+  NativeImagePreviewResolvedColorScheme,
+} from './types';
+
+export type NativeImagePreviewContextValue = {
+  previewGroupId: string;
+  items: readonly NativeImagePreviewResolvedItem[];
+  nativeItems: readonly NativeImagePreviewNativeItem[];
+  colorScheme: NativeImagePreviewResolvedColorScheme;
+  disabled: boolean;
+  edgeToEdge: boolean;
+  nativeProps?: NativeImagePreviewNativeProps;
+  onChange?: (value: number, meta: NativeImagePreviewChangeMeta) => void;
+};
+
+export const NativeImagePreviewContext =
+  React.createContext<NativeImagePreviewContextValue | null>(null);

package/src/ui/NativeImagePreview/index.tsx

@@ -0,0 +1,18 @@
+export { NativeImagePreview } from './NativeImagePreview';
+export type {
+  NativeImagePreviewChangeEvent,
+  NativeImagePreviewChangeEventPayload,
+  NativeImagePreviewChangeMeta,
+  NativeImagePreviewChangeReason,
+  NativeImagePreviewColorScheme,
+  NativeImagePreviewComponent,
+  NativeImagePreviewItem,
+  NativeImagePreviewItemDescriptor,
+  NativeImagePreviewItemProps,
+  NativeImagePreviewMediaType,
+  NativeImagePreviewNativeProps,
+  NativeImagePreviewProps,
+  NativeImagePreviewResolvedItem,
+  NativeImagePreviewResolvedColorScheme,
+  NativeImagePreviewSource,
+} from './types';

package/src/ui/NativeImagePreview/types.ts

@@ -0,0 +1,94 @@
+import type * as React from 'react';
+import type {
+  ImageSourcePropType,
+  NativeSyntheticEvent,
+  StyleProp,
+  ViewStyle,
+} from 'react-native';
+
+export type NativeImagePreviewResolvedColorScheme = 'dark' | 'light';
+export type NativeImagePreviewColorScheme =
+  | NativeImagePreviewResolvedColorScheme
+  | 'system';
+export type NativeImagePreviewMediaType = 'image' | 'video';
+export type NativeImagePreviewSource = ImageSourcePropType | string;
+
+export type NativeImagePreviewItemDescriptor = {
+  id?: string;
+  alt?: string;
+  type?: NativeImagePreviewMediaType;
+  url?: string;
+  source?: NativeImagePreviewSource;
+  poster?: NativeImagePreviewSource;
+  width?: number;
+  height?: number;
+};
+
+export type NativeImagePreviewItem =
+  | NativeImagePreviewSource
+  | NativeImagePreviewItemDescriptor;
+
+export type NativeImagePreviewResolvedItem = {
+  id: string;
+  type: NativeImagePreviewMediaType;
+  url: string;
+  poster?: string;
+  width?: number;
+  height?: number;
+  alt?: string;
+  raw: NativeImagePreviewItem;
+};
+
+export type NativeImagePreviewNativeItem = {
+  id: string;
+  type: NativeImagePreviewMediaType;
+  url: string;
+  poster?: string;
+  width?: number;
+  height?: number;
+};
+
+export type NativeImagePreviewChangeReason = 'api' | 'swipe';
+
+export type NativeImagePreviewChangeEventPayload = {
+  currentIndex: number;
+};
+
+export type NativeImagePreviewChangeEvent =
+  NativeSyntheticEvent<NativeImagePreviewChangeEventPayload>;
+
+export type NativeImagePreviewChangeMeta = {
+  reason: NativeImagePreviewChangeReason;
+  item: NativeImagePreviewResolvedItem | null;
+  nativeEvent?: NativeImagePreviewChangeEvent;
+};
+
+export type NativeImagePreviewNativeProps = {
+  iosCloseIconName?: string;
+};
+
+export type NativeImagePreviewProps = {
+  items: readonly NativeImagePreviewItem[];
+  children: React.ReactNode;
+  colorScheme?: NativeImagePreviewColorScheme;
+  disabled?: boolean;
+  edgeToEdge?: boolean;
+  nativeProps?: NativeImagePreviewNativeProps;
+  onChange?: (value: number, meta: NativeImagePreviewChangeMeta) => void;
+};
+
+export type NativeImagePreviewItemProps = {
+  index: number;
+  children: React.ReactElement;
+  disabled?: boolean;
+  style?: StyleProp<ViewStyle>;
+  onChange?: (value: number, meta: NativeImagePreviewChangeMeta) => void;
+};
+
+export type NativeImagePreviewComponent = React.MemoExoticComponent<
+  (props: NativeImagePreviewProps) => React.ReactElement
+> & {
+  Item: React.MemoExoticComponent<
+    (props: NativeImagePreviewItemProps) => React.ReactElement
+  >;
+};