zkit-ui 2.0.3 → 2.0.5

package/README.md

@@ -121,6 +121,7 @@ function Demo() {
 - Sheet：通用方向弹层（H5 bottom/top/left/right 自绘，iOS/Android bottom 内部走原生 TrueSheet）
 - LoadingService：全局加载 HUD 服务（handle 状态模型、Promise 绑定、Android 无 elevation 残影路径）
 - ImagePreview：全屏图片预览（声明式 open/value 状态模型 + 全局 imagePreview.open 服务）
+- NativeImagePreview：原生共享转场图片预览（真实缩略图锚点 + 原生 viewer 手势链路）
 - Picker：底部滚轮选择器（单列/级联、确认提交、iOS 原生 wheel）
 - AddressCascader：省市区级联选择（内置中国数据）
 - DatePicker：年/月/日日期选择（空值、范围、精度与确认提交语义）
@@ -209,6 +210,61 @@ imagePreview.open({ images, index: 0 });
 
 `ImagePreview` 使用 `open/defaultOpen/onOpenChange` 管理显隐，使用 `value/defaultValue/onChange` 管理当前图片索引。全局 `imagePreview.open()` 返回 handle，可通过 `handle.result` 获取关闭原因和最终索引；`ZKitProvider` 已内置 `ImagePreviewProvider`。
 
+### NativeImagePreview 用法
+
+```tsx
+import { Image, StyleSheet, View, type ImageSourcePropType } from 'react-native';
+import { NativeImagePreview, type NativeImagePreviewItemDescriptor } from 'zkit-ui/native-image-preview';
+
+const items: NativeImagePreviewItemDescriptor[] = [
+  { id: 'cover', source: require('./cover.png'), width: 1200, height: 900 },
+  { id: 'detail', source: 'https://example.com/detail.jpg' },
+  { 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 DemoNativeImagePreview() {
+  return (
+    <NativeImagePreview items={items} colorScheme="dark" edgeToEdge>
+      <View style={styles.grid}>
+        {items.map((item, index) => {
+          const thumbnailSource = getThumbnailSource(item);
+          if (!thumbnailSource) return null;
+
+          return (
+            <View key={item.id ?? index} style={styles.tile}>
+              <NativeImagePreview.Item index={index} style={StyleSheet.absoluteFill}>
+                <Image source={thumbnailSource} style={styles.thumbnail} />
+              </NativeImagePreview.Item>
+            </View>
+          );
+        })}
+      </View>
+    </NativeImagePreview>
+  );
+}
+
+const styles = StyleSheet.create({
+  grid: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+  },
+  tile: {
+    aspectRatio: 1,
+    width: '33.333%',
+  },
+  thumbnail: {
+    ...StyleSheet.absoluteFillObject,
+  },
+});
+```
+
+`NativeImagePreview` 不是 `ImagePreview` 的命令式替代品，而是面向真实缩略图锚点的原生共享转场组件。`items` 顺序必须和 `NativeImagePreview.Item index` 对齐，`Item` 内必须渲染真实图片节点；iOS / Android 走原生 viewer，原生模块未注册时不会降级到普通 `ImagePreview`，需要重建 native app。Web 仅渲染子节点，不提供预览能力。
+
 ### 目录与导出
 
 - 组件放在 `src/ui/`（一组件一文件为主；复杂组件可拆同名子文件）

package/android/build.gradle

@@ -0,0 +1,100 @@
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+apply plugin: 'maven-publish'
+
+group = 'cn.fontree.zkit.ui'
+version = '1.0.0'
+
+buildscript {
+  def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
+  if (expoModulesCorePlugin.exists()) {
+    apply from: expoModulesCorePlugin
+    applyKotlinExpoModulesCorePlugin()
+  }
+
+  // Simple helper that allows the root project to override versions declared by this library.
+  ext.safeExtGet = { prop, fallback ->
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+  }
+
+  // Ensures backward compatibility
+  ext.getKotlinVersion = {
+    if (ext.has("kotlinVersion")) {
+      ext.kotlinVersion()
+    } else {
+      ext.safeExtGet("kotlinVersion", "1.8.10")
+    }
+  }
+
+  repositories {
+    mavenCentral()
+    maven { url 'https://jitpack.io' }
+  }
+
+  dependencies {
+    classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${getKotlinVersion()}")
+  }
+}
+
+afterEvaluate {
+  publishing {
+    publications {
+      release(MavenPublication) {
+        from components.release
+      }
+    }
+    repositories {
+      maven {
+        url = mavenLocal().url
+      }
+    }
+  }
+}
+
+android {
+  compileSdkVersion safeExtGet("compileSdkVersion", 33)
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = JavaVersion.VERSION_17.majorVersion
+  }
+
+  namespace "cn.fontree.zkit.ui.preview"
+  defaultConfig {
+    minSdkVersion safeExtGet("minSdkVersion", 21)
+    targetSdkVersion safeExtGet("targetSdkVersion", 34)
+    versionCode 1
+    versionName "1.0.0"
+  }
+  lintOptions {
+    abortOnError false
+  }
+  publishing {
+    singleVariant("release") {
+      withSourcesJar()
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+}
+
+dependencies {
+  def GLIDE_VERSION = "4.16.0"
+  implementation 'com.facebook.react:react-android'
+  implementation 'androidx.appcompat:appcompat:1.7.0'
+
+  implementation project(':expo-modules-core')
+  implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:${getKotlinVersion()}"
+  implementation "com.github.bumptech.glide:glide:${GLIDE_VERSION}"
+  implementation 'androidx.viewpager2:viewpager2:1.1.0'
+  implementation 'androidx.recyclerview:recyclerview:1.4.0'
+  implementation 'com.github.chrisbanes:PhotoView:2.3.0'
+  implementation 'androidx.media3:media3-exoplayer:1.5.1'
+  implementation 'androidx.media3:media3-ui:1.5.1'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/java/cn/fontree/zkit/ui/preview/GaleriaModule.kt

@@ -0,0 +1,43 @@
+package cn.fontree.zkit.ui.preview
+
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+class GaleriaModule : Module() {
+    override fun definition() = ModuleDefinition {
+        Name("ZKitNativeImagePreview")
+
+        View(GaleriaView::class) {
+            Events(
+                "onIndexChange"
+            )
+            Prop("theme") { view: GaleriaView, theme: Theme ->
+                view.theme = theme
+            }
+            Prop("items") { view: GaleriaView, items: Array<Map<String, Any?>> ->
+                view.items = items.toList()
+            }
+            Prop("urls") { view: GaleriaView, urls: Array<String> ->
+                view.urls = urls
+            }
+            Prop("index") { view: GaleriaView, index: Int ->
+                view.initialIndex = index
+            }
+            Prop("galleryId") { view: GaleriaView, galleryId: String? ->
+                view.galleryId = galleryId
+            }
+            Prop("disableHiddenOriginalImage") { view: GaleriaView, disableHiddenOriginalImage: Boolean ->
+                view.disableHiddenOriginalImage = disableHiddenOriginalImage
+            }
+            Prop("edgeToEdge") { view: GaleriaView, edgeToEdge: Boolean ->
+                view.edgeToEdge = edgeToEdge
+            }
+            Prop("transitionOffsetY") { view: GaleriaView, transitionOffsetY: Int? ->
+                view.transitionOffsetY = transitionOffsetY
+            }
+            Prop("transitionOffsetX") { view: GaleriaView, transitionOffsetX: Int? ->
+                view.transitionOffsetX = transitionOffsetX
+            }
+        }
+    }
+}

package/android/src/main/java/cn/fontree/zkit/ui/preview/GaleriaView.kt

@@ -0,0 +1,305 @@
+package cn.fontree.zkit.ui.preview
+
+import android.app.Activity
+import android.content.Context
+import android.content.ContextWrapper
+import android.view.View
+import android.view.ViewGroup
+import android.widget.ImageView
+import androidx.activity.ComponentActivity
+import androidx.activity.OnBackPressedCallback
+import expo.modules.kotlin.viewevent.EventDispatcher
+
+enum class Theme(val value: String) {
+    Dark("dark"),
+    Light("light")
+}
+
+class GaleriaView(context: Context) : ViewGroup(context) {
+    var urls: Array<String>? = null
+    var items: List<Map<String, Any?>> = emptyList()
+    var theme: Theme = Theme.Dark
+    var initialIndex: Int = 0
+        set(value) {
+            field = value
+            bindSourceImageView()
+        }
+    var galleryId: String? = null
+        set(value) {
+            field = value
+            bindSourceImageView()
+        }
+    var disableHiddenOriginalImage = false
+    var edgeToEdge = false
+    var transitionOffsetY: Int? = null
+    var transitionOffsetX: Int? = 0
+    val onIndexChange by EventDispatcher()
+
+    private var sourceImageView: ImageView? = null
+    private var observedSourceImageView: ImageView? = null
+    private var sourceImageLayoutListener: View.OnLayoutChangeListener? = null
+    private var sourceImageAttachListener: View.OnAttachStateChangeListener? = null
+    private var overlayView: GalleryViewerOverlayView? = null
+    private var overlayBackCallback: OnBackPressedCallback? = null
+
+    override fun onAttachedToWindow() {
+        super.onAttachedToWindow()
+        bindSourceImageView()
+    }
+
+    override fun onLayout(changed: Boolean, left: Int, top: Int, right: Int, bottom: Int) {
+        for (i in 0 until childCount) {
+            val child = getChildAt(i)
+            child.layout(0, 0, width, height)
+        }
+        bindSourceImageView()
+    }
+
+    override fun onDetachedFromWindow() {
+        overlayView?.dismissImmediately()
+        overlayView = null
+        overlayBackCallback?.remove()
+        overlayBackCallback = null
+        super.onDetachedFromWindow()
+        unregisterSourceImageView()
+    }
+
+    private fun scopedGalleryId(): String? = galleryId?.takeIf { it.isNotBlank() }
+
+    private fun transitionNameForIndex(index: Int): String {
+        return GallerySharedElementNames.forIndex(scopedGalleryId(), index)
+    }
+
+    private fun transitionNameForItem(item: GalleryMediaItem): String {
+        return GallerySharedElementNames.forItem(scopedGalleryId(), item)
+    }
+
+    private fun bindSourceImageView() {
+        val imageView = findImageView(this)
+        if (imageView == null) {
+            unregisterSourceImageView()
+            return
+        }
+
+        val previousSourceImageView = sourceImageView
+        if (previousSourceImageView != null && previousSourceImageView !== imageView) {
+            clearSourceImageObserver()
+            if (!isSourceImageViewUsable(previousSourceImageView)) {
+                GallerySourceViewRegistry.unregisterView(previousSourceImageView)
+            }
+        }
+
+        sourceImageView = imageView
+        imageView.setOnClickListener {
+            openViewer(imageView)
+        }
+        registerSourceImageViewWhenReady(imageView)
+    }
+
+    private fun openViewer(sourceView: ImageView) {
+        val mediaItems = buildMediaItems()
+        if (mediaItems.isEmpty()) {
+            return
+        }
+        if (overlayView != null) {
+            return
+        }
+        val safeIndex = initialIndex.coerceIn(0, mediaItems.lastIndex)
+        val activity = getActivity(context) ?: return
+        val overlayHost = activity.window.decorView as? ViewGroup
+            ?: activity.findViewById<ViewGroup>(android.R.id.content)
+            ?: return
+        val sourceKey = transitionNameForItem(mediaItems[safeIndex])
+        GallerySourceViewRegistry.register(sourceKey, sourceView)
+        val overlay = GalleryViewerOverlayView(
+            activity,
+            mediaItems,
+            safeIndex,
+            theme == Theme.Light,
+            scopedGalleryId(),
+            object : GalleryViewerOverlayView.Listener {
+                override fun onOverlayDismissed() {
+                    if (overlayView != null) {
+                        overlayView = null
+                    }
+                    overlayBackCallback?.remove()
+                    overlayBackCallback = null
+                }
+
+                override fun onOverlayIndexChange(index: Int) {
+                    onIndexChange(mapOf("currentIndex" to index))
+                }
+            }
+        )
+        overlayView = overlay
+        overlayHost.addView(overlay)
+        if (activity is ComponentActivity) {
+            overlayBackCallback?.remove()
+            overlayBackCallback = object : OnBackPressedCallback(true) {
+                override fun handleOnBackPressed() {
+                    overlayView?.requestClose()
+                }
+            }.also { callback ->
+                activity.onBackPressedDispatcher.addCallback(callback)
+            }
+        }
+    }
+
+    private fun buildMediaItems(): List<GalleryMediaItem> {
+        if (items.isNotEmpty()) {
+            return items.mapIndexedNotNull { index, data ->
+                val type = data["type"] as? String ?: return@mapIndexedNotNull null
+                val url = data["url"] as? String ?: return@mapIndexedNotNull null
+                if (type.lowercase() == "video") {
+                    val poster = data["poster"] as? String ?: url
+                    GalleryMediaItem(index.toString(), GalleryMediaItem.MediaType.VIDEO, url, poster)
+                } else {
+                    GalleryMediaItem(index.toString(), GalleryMediaItem.MediaType.IMAGE, url, url)
+                }
+            }
+        }
+        val rawUrls = urls ?: return emptyList()
+        return rawUrls.mapIndexed { index, url ->
+            GalleryMediaItem(index.toString(), GalleryMediaItem.MediaType.IMAGE, url, url)
+        }
+    }
+
+    private fun findImageView(view: View): ImageView? {
+        var bestImageView: ImageView? = null
+        var bestScore = Int.MIN_VALUE
+
+        fun visit(candidate: View) {
+            if (candidate is ImageView) {
+                val score = sourceImageViewScore(candidate)
+                if (score > bestScore) {
+                    bestImageView = candidate
+                    bestScore = score
+                }
+            }
+            if (candidate is ViewGroup) {
+                for (i in 0 until candidate.childCount) {
+                    visit(candidate.getChildAt(i))
+                }
+            }
+        }
+
+        visit(view)
+        return bestImageView
+    }
+
+    private fun registerSourceImageViewWhenReady(imageView: ImageView) {
+        val transitionName = transitionNameForIndex(initialIndex)
+        if (isSourceImageViewUsable(imageView)) {
+            clearSourceImageObserver(imageView)
+            GallerySourceViewRegistry.register(transitionName, imageView)
+            return
+        }
+
+        observeSourceImageView(imageView)
+    }
+
+    private fun observeSourceImageView(imageView: ImageView) {
+        if (observedSourceImageView === imageView && sourceImageLayoutListener != null) {
+            return
+        }
+
+        clearSourceImageObserver()
+        observedSourceImageView = imageView
+        val layoutListener = View.OnLayoutChangeListener { view, _, _, _, _, _, _, _, _ ->
+            val observed = view as? ImageView ?: return@OnLayoutChangeListener
+            if (sourceImageView !== observed) {
+                clearSourceImageObserver(observed)
+                return@OnLayoutChangeListener
+            }
+            if (isSourceImageViewUsable(observed)) {
+                registerSourceImageViewWhenReady(observed)
+            }
+        }
+        val attachListener = object : View.OnAttachStateChangeListener {
+            override fun onViewAttachedToWindow(view: View) {
+                val observed = view as? ImageView ?: return
+                if (sourceImageView !== observed) {
+                    clearSourceImageObserver(observed)
+                    return
+                }
+                registerSourceImageViewWhenReady(observed)
+            }
+
+            override fun onViewDetachedFromWindow(view: View) = Unit
+        }
+        sourceImageLayoutListener = layoutListener
+        sourceImageAttachListener = attachListener
+        imageView.addOnLayoutChangeListener(layoutListener)
+        imageView.addOnAttachStateChangeListener(attachListener)
+        imageView.post {
+            if (sourceImageView !== imageView) {
+                return@post
+            }
+            if (isSourceImageViewUsable(imageView)) {
+                registerSourceImageViewWhenReady(imageView)
+            }
+        }
+    }
+
+    private fun isSourceImageViewUsable(imageView: ImageView): Boolean {
+        return imageView.isAttachedToWindow && imageView.width > 0 && imageView.height > 0
+    }
+
+    private fun sourceImageViewScore(imageView: ImageView): Int {
+        var score = 0
+        if (imageView.isAttachedToWindow) {
+            score += 16
+        }
+        if (imageView.width > 0 && imageView.height > 0) {
+            score += 16
+        }
+        if (imageView.visibility == View.VISIBLE) {
+            score += 16
+        }
+        if (imageView.isShown) {
+            score += 16
+        }
+        if (imageView.drawable != null) {
+            score += 8
+        }
+        if (imageView === sourceImageView) {
+            score += 1
+        }
+        return score
+    }
+
+    private fun clearSourceImageObserver(imageView: ImageView? = null) {
+        val observed = observedSourceImageView ?: return
+        if (imageView != null && observed !== imageView) {
+            return
+        }
+        sourceImageLayoutListener?.let { listener ->
+            observed.removeOnLayoutChangeListener(listener)
+        }
+        sourceImageAttachListener?.let { listener ->
+            observed.removeOnAttachStateChangeListener(listener)
+        }
+        sourceImageLayoutListener = null
+        sourceImageAttachListener = null
+        observedSourceImageView = null
+    }
+
+    private fun getActivity(context: Context): Activity? {
+        var current = context
+        while (current is ContextWrapper) {
+            if (current is Activity) {
+                return current
+            }
+            current = current.baseContext
+        }
+        return null
+    }
+
+    private fun unregisterSourceImageView() {
+        clearSourceImageObserver()
+        sourceImageView?.let { imageView ->
+            GallerySourceViewRegistry.unregisterView(imageView)
+        }
+        sourceImageView = null
+    }
+}