zkit-ui 2.0.3 → 2.0.5

package/ios/GalleryViewer/GaleriaViewerTransitionCoordinator.swift

@@ -0,0 +1,312 @@
+import UIKit
+
+private final class GaleriaTransitionSnapshotView: UIView {
+    private let imageView = UIImageView()
+
+    init(image: UIImage) {
+        super.init(frame: .zero)
+        backgroundColor = .clear
+        clipsToBounds = true
+        isUserInteractionEnabled = false
+
+        imageView.image = image
+        imageView.backgroundColor = .clear
+        imageView.contentMode = .scaleToFill
+        addSubview(imageView)
+    }
+
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    func updateImage(_ image: UIImage) {
+        imageView.image = image
+    }
+
+    func applyContentFrame(_ frame: CGRect) {
+        imageView.frame = frame
+    }
+}
+
+final class GaleriaViewerTransitionCoordinator {
+    private weak var containerView: UIView?
+    private weak var hiddenAnchorView: UIView?
+    private weak var hiddenPageView: GaleriaViewerPageView?
+    private var activeSnapshotView: UIView?
+
+    init(containerView: UIView) {
+        self.containerView = containerView
+    }
+
+    static func aspectFitRect(for imageSize: CGSize, in bounds: CGRect) -> CGRect {
+        guard imageSize.width > 0, imageSize.height > 0 else { return bounds }
+
+        let widthRatio = bounds.width / imageSize.width
+        let heightRatio = bounds.height / imageSize.height
+        let scale = min(widthRatio, heightRatio)
+        let fittedSize = CGSize(
+            width: imageSize.width * scale,
+            height: imageSize.height * scale
+        )
+
+        return CGRect(
+            x: bounds.midX - fittedSize.width * 0.5,
+            y: bounds.midY - fittedSize.height * 0.5,
+            width: fittedSize.width,
+            height: fittedSize.height
+        )
+    }
+
+    func performOpenTransition(
+        from sourceView: UIImageView?,
+        to pageView: GaleriaViewerPageView?,
+        backgroundView: UIView,
+        contentView: UIView,
+        completion: @escaping () -> Void
+    ) {
+        guard let containerView = containerView else {
+            completion()
+            return
+        }
+
+        restoreHiddenViews()
+        activeSnapshotView?.removeFromSuperview()
+        activeSnapshotView = nil
+
+        backgroundView.alpha = 0
+        contentView.alpha = 0
+
+        flushLayoutForSharedElementSampling(of: sourceView)
+        guard let sourceView = sourceView, let sourceState = sourceView.galeriaSharedElementState() else {
+            animateSimpleAppearance(
+                backgroundView: backgroundView,
+                contentView: contentView,
+                completion: completion
+            )
+            return
+        }
+
+        let snapshotView = makeSnapshot(from: sourceState)
+        apply(sourceState.geometry, to: snapshotView)
+        containerView.addSubview(snapshotView)
+        activeSnapshotView = snapshotView
+
+        hiddenAnchorView = sourceView
+        sourceView.alpha = 0
+        pageView?.setMediaHidden(true)
+        hiddenPageView = pageView
+
+        let animateIntoPage: (Bool) -> Void = { [weak self] isReady in
+            guard let self = self, let containerView = self.containerView else {
+                completion()
+                return
+            }
+
+            let windowBounds = containerView.window?.bounds ?? UIScreen.main.bounds
+            let targetGeometry: GaleriaSharedElementGeometry
+            if isReady, let pageState = pageView?.sharedElementState() {
+                targetGeometry = pageState.geometry
+            } else if let pageView = pageView {
+                targetGeometry = pageView.defaultTransitionGeometry(in: windowBounds)
+            } else {
+                targetGeometry = self.defaultGeometry(for: sourceState.image.size, in: windowBounds)
+            }
+
+            UIView.animate(
+                withDuration: 0.32,
+                delay: 0,
+                usingSpringWithDamping: 0.94,
+                initialSpringVelocity: 0.08,
+                options: [.curveEaseInOut, .allowUserInteraction]
+            ) {
+                backgroundView.alpha = 1
+                self.apply(targetGeometry, to: snapshotView)
+            } completion: { _ in
+                self.restoreHiddenViews()
+                contentView.alpha = 1
+                snapshotView.removeFromSuperview()
+                self.activeSnapshotView = nil
+                completion()
+            }
+        }
+
+        guard let pageView = pageView else {
+            animateIntoPage(false)
+            return
+        }
+
+        waitUntilReady(pageView: pageView, timeout: 0.42) { ready in
+            animateIntoPage(ready)
+        }
+    }
+
+    func performCloseTransition(
+        from pageView: GaleriaViewerPageView?,
+        to anchorView: UIImageView?,
+        backgroundView: UIView,
+        contentView: UIView,
+        completion: @escaping () -> Void
+    ) {
+        guard let containerView = containerView else {
+            completion()
+            return
+        }
+
+        restoreHiddenViews()
+        activeSnapshotView?.removeFromSuperview()
+        activeSnapshotView = nil
+
+        guard
+            let pageView,
+            let pageState = pageView.sharedElementState()
+        else {
+            animateSimpleDismissal(
+                backgroundView: backgroundView,
+                contentView: contentView,
+                completion: completion
+            )
+            return
+        }
+
+        let snapshotView = makeSnapshot(from: pageState)
+        apply(pageState.geometry, to: snapshotView)
+        containerView.addSubview(snapshotView)
+        activeSnapshotView = snapshotView
+
+        hiddenPageView = pageView
+        pageView.setMediaHidden(true)
+
+        var targetGeometry: GaleriaSharedElementGeometry?
+        flushLayoutForSharedElementSampling(of: anchorView)
+        if let anchorView = anchorView, let anchorState = anchorView.galeriaSharedElementState() {
+            hiddenAnchorView = anchorView
+            anchorView.alpha = 0
+            targetGeometry = anchorState.geometry
+        }
+
+        UIView.animate(
+            withDuration: 0.24,
+            delay: 0,
+            options: [.curveEaseInOut, .allowUserInteraction]
+        ) {
+            backgroundView.alpha = 0
+            contentView.alpha = 0
+            if let targetGeometry = targetGeometry {
+                self.apply(targetGeometry, to: snapshotView)
+            } else {
+                snapshotView.alpha = 0
+                snapshotView.transform = CGAffineTransform(scaleX: 0.92, y: 0.92)
+            }
+        } completion: { [weak self] _ in
+            self?.restoreHiddenViews()
+            snapshotView.removeFromSuperview()
+            self?.activeSnapshotView = nil
+            completion()
+        }
+    }
+
+    private func animateSimpleAppearance(
+        backgroundView: UIView,
+        contentView: UIView,
+        completion: @escaping () -> Void
+    ) {
+        UIView.animate(
+            withDuration: 0.18,
+            delay: 0,
+            options: [.curveEaseOut, .allowUserInteraction]
+        ) {
+            backgroundView.alpha = 1
+            contentView.alpha = 1
+        } completion: { _ in
+            completion()
+        }
+    }
+
+    private func animateSimpleDismissal(
+        backgroundView: UIView,
+        contentView: UIView,
+        completion: @escaping () -> Void
+    ) {
+        UIView.animate(
+            withDuration: 0.18,
+            delay: 0,
+            options: [.curveEaseIn, .allowUserInteraction]
+        ) {
+            backgroundView.alpha = 0
+            contentView.alpha = 0
+        } completion: { _ in
+            completion()
+        }
+    }
+
+    private func waitUntilReady(
+        pageView: GaleriaViewerPageView,
+        timeout: TimeInterval,
+        completion: @escaping (Bool) -> Void
+    ) {
+        let deadline = CACurrentMediaTime() + timeout
+        var lastStableState: GaleriaSharedElementState?
+        var stableFrameCount = 0
+
+        func poll() {
+            pageView.layoutIfNeeded()
+            if let currentState = pageView.sharedElementState() {
+                if let lastStableState = lastStableState, lastStableState.approximatelyEquals(currentState) {
+                    stableFrameCount += 1
+                } else {
+                    lastStableState = currentState
+                    stableFrameCount = 1
+                }
+
+                if stableFrameCount >= 2 {
+                    completion(true)
+                    return
+                }
+            }
+            if CACurrentMediaTime() >= deadline {
+                completion(false)
+                return
+            }
+            DispatchQueue.main.asyncAfter(deadline: .now() + 0.016, execute: poll)
+        }
+
+        poll()
+    }
+
+    private func frameInContainer(fromWindowFrame windowFrame: CGRect) -> CGRect {
+        guard let containerView = containerView else { return windowFrame }
+        return containerView.convert(windowFrame, from: nil)
+    }
+
+    private func flushLayoutForSharedElementSampling(of imageView: UIImageView?) {
+        imageView?.superview?.layoutIfNeeded()
+        imageView?.layoutIfNeeded()
+        containerView?.layoutIfNeeded()
+    }
+
+    private func makeSnapshot(from state: GaleriaSharedElementState) -> GaleriaTransitionSnapshotView {
+        GaleriaTransitionSnapshotView(image: state.image)
+    }
+
+    private func apply(_ geometry: GaleriaSharedElementGeometry, to snapshotView: GaleriaTransitionSnapshotView) {
+        snapshotView.frame = frameInContainer(fromWindowFrame: geometry.visibleFrameInWindow)
+        snapshotView.applyContentFrame(geometry.contentFrameInVisibleBounds)
+        snapshotView.layer.cornerRadius = geometry.cornerRadius
+    }
+
+    private func defaultGeometry(for imageSize: CGSize, in windowBounds: CGRect) -> GaleriaSharedElementGeometry {
+        let visibleFrame = Self.aspectFitRect(for: imageSize, in: windowBounds)
+        return GaleriaSharedElementGeometry(
+            visibleFrameInWindow: visibleFrame,
+            contentFrameInVisibleBounds: CGRect(origin: .zero, size: visibleFrame.size),
+            cornerRadius: 0
+        )
+    }
+
+    private func restoreHiddenViews() {
+        hiddenAnchorView?.alpha = 1
+        hiddenAnchorView = nil
+        hiddenPageView?.setMediaHidden(false)
+        hiddenPageView = nil
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zkit-ui",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "private": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -87,6 +87,11 @@
       "react-native": "./dist/ui/LinkedScroll/index.js",
       "default": "./dist/ui/LinkedScroll/index.js"
     },
+    "./native-image-preview": {
+      "types": "./dist/ui/NativeImagePreview/index.d.ts",
+      "react-native": "./dist/ui/NativeImagePreview/index.js",
+      "default": "./dist/ui/NativeImagePreview/index.js"
+    },
     "./loading-spinner": {
       "types": "./dist/ui/LoadingSpinner/index.d.ts",
       "react-native": "./dist/ui/LoadingSpinner/index.js",
@@ -176,7 +181,9 @@
     "url": "https://github.com/Concur-max/zkit/issues"
   },
   "files": [
+    "android",
     "dist",
+    "expo-module.config.json",
     "src",
     "ios",
     "react-native.config.js",
@@ -186,24 +193,18 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
-  "scripts": {
-    "build": "node scripts/build.cjs",
-    "verify:entrypoints": "node scripts/verify-entrypoints.cjs",
-    "verify": "pnpm run build && pnpm run verify:entrypoints",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepack": "pnpm run build",
-    "prepublishOnly": "pnpm run build"
-  },
   "dependencies": {
     "@vant/area-data": "^2.1.0",
     "dayjs": "^1.11.13",
+    "react-native-is-edge-to-edge": "^1.1.6",
     "react-native-toast-message": "^2.3.3",
-    "zkit-tools": "workspace:*"
+    "zkit-tools": "1.0.1"
   },
   "peerDependencies": {
     "@expo/vector-icons": "*",
     "@lodev09/react-native-true-sheet": "*",
     "@shopify/flash-list": "*",
+    "expo": "*",
     "expo-image": "*",
     "expo-linear-gradient": "*",
     "lottie-react-native": "*",
@@ -218,10 +219,10 @@
   },
   "devDependencies": {
     "@expo/vector-icons": "^15.1.1",
-    "@lodev09/react-native-true-sheet": "workspace:*",
     "@shopify/flash-list": "^2.3.1",
     "@types/react": "~19.1.17",
     "dayjs": "^1.11.13",
+    "expo": "~54.0.31",
     "expo-image": "~3.0.11",
     "expo-linear-gradient": "~15.0.8",
     "lottie-react-native": "7.3.2",
@@ -234,6 +235,13 @@
     "react-native-svg": "^15.12.1",
     "react-native-worklets": "0.5.1",
     "sonner-native": "^0.22.2",
-    "typescript": "~5.9.3"
+    "typescript": "~5.9.3",
+    "@lodev09/react-native-true-sheet": "3.10.0"
+  },
+  "scripts": {
+    "build": "node scripts/build.cjs",
+    "verify:entrypoints": "node scripts/verify-entrypoints.cjs",
+    "verify": "pnpm run build && pnpm run verify:entrypoints",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   }
-}
+}

package/src/all.ts

@@ -238,6 +238,24 @@ export type {
   LinkedScrollSectionRenderContext,
   LinkedScrollValue,
 } from './ui/LinkedScroll/index';
+export { NativeImagePreview } from './ui/NativeImagePreview/index';
+export type {
+  NativeImagePreviewChangeEvent,
+  NativeImagePreviewChangeEventPayload,
+  NativeImagePreviewChangeMeta,
+  NativeImagePreviewChangeReason,
+  NativeImagePreviewColorScheme,
+  NativeImagePreviewComponent,
+  NativeImagePreviewItem,
+  NativeImagePreviewItemDescriptor,
+  NativeImagePreviewItemProps,
+  NativeImagePreviewMediaType,
+  NativeImagePreviewNativeProps,
+  NativeImagePreviewProps,
+  NativeImagePreviewResolvedItem,
+  NativeImagePreviewResolvedColorScheme,
+  NativeImagePreviewSource,
+} from './ui/NativeImagePreview/index';
 export { ThemeProvider } from './theme/ThemeProvider';
 export { useTheme } from './theme/useTheme';
 export type { Theme, ThemeOverride } from './theme/types';

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。
+
 ## 手动确认点
 
 - Android：Modal 返回键、下滑关闭后的状态回收、超长图/大图内存表现。

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>;
+  galleryId: 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 createGalleryId() {
+  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 galleryIdRef = React.useRef<string | null>(null);
+  if (galleryIdRef.current == null) {
+    galleryIdRef.current = createGalleryId();
+  }
+
+  const resolvedItems = React.useMemo(
+    () => normalizeNativeImagePreviewItems(items),
+    [items]
+  );
+  const nativeItems = React.useMemo(
+    () => toNativePreviewItems(resolvedItems),
+    [resolvedItems]
+  );
+  const resolvedColorScheme = resolveNativeImagePreviewColorScheme(colorScheme, systemColorScheme);
+  const contextValue = React.useMemo(
+    () => ({
+      galleryId: galleryIdRef.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}
+      galleryId={context.galleryId}
+      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,37 @@
+import * as React from 'react';
+import { View } from 'react-native';
+import type {
+  NativeImagePreviewComponent,
+  NativeImagePreviewItemProps,
+  NativeImagePreviewProps,
+} from './types';
+
+let didWarnUnsupportedWeb = false;
+
+function warnUnsupportedWeb() {
+  if (!__DEV__ || didWarnUnsupportedWeb) return;
+
+  didWarnUnsupportedWeb = true;
+  console.warn(
+    '[zkit-ui][NativeImagePreview] Native shared-transition preview is only available in iOS and Android native builds.'
+  );
+}
+
+const NativeImagePreviewRoot = React.memo(function NativeImagePreview({
+  children,
+}: NativeImagePreviewProps) {
+  React.useEffect(warnUnsupportedWeb, []);
+
+  return <>{children}</>;
+});
+
+const NativeImagePreviewItem = React.memo(function NativeImagePreviewItem({
+  children,
+  style,
+}: NativeImagePreviewItemProps) {
+  return <View style={style}>{children}</View>;
+});
+
+export const NativeImagePreview = Object.assign(NativeImagePreviewRoot, {
+  Item: NativeImagePreviewItem,
+}) as NativeImagePreviewComponent;