zkit-ui 2.0.4 → 2.0.5

package/src/ui/NativeImagePreview/README.md

@@ -0,0 +1,111 @@
+# NativeImagePreview
+
+`NativeImagePreview` 是强调原生共享转场体验的图片预览组件。它和普通 `ImagePreview` 服务分工不同：`ImagePreview` 适合命令式打开图片；`NativeImagePreview` 适合从真实缩略图自然过渡到全屏 viewer，并在 iOS / Android 上走原生手势、缩放、滑动和拖拽关闭路径。
+
+## 适用场景
+
+- 相册九宫格、瀑布流、商品图集这类有真实缩略图锚点的页面。
+- 需要从缩略图拾取到全屏 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 和真实图片锚点，主打共享转场、缩放、滑动和拖拽关闭。
+- 首次接入或变更原生依赖后需要重新构建 native app；仅刷新 JS bundle 不会注册新的原生 ViewManager。
+- 原生模块未注册时不会降级到 `ImagePreview`。这是 native 接入或构建错误，需要重新安装依赖并重建 native app。
+- Web：仅保留子节点渲染，不提供预览能力，也不会模拟普通 `ImagePreview`。
+
+## 手动确认点
+
+- 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 = {
+  galleryId: 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,92 @@
+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;
+  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;
+  raw: NativeImagePreviewItem;
+};
+
+export type NativeImagePreviewNativeItem = {
+  id: string;
+  type: NativeImagePreviewMediaType;
+  url: string;
+  poster?: string;
+  width?: number;
+  height?: number;
+};
+
+export type NativeImagePreviewChangeReason = '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
+  >;
+};

package/src/ui/NativeImagePreview/utils.ts

@@ -0,0 +1,107 @@
+import {
+  Image,
+  type ColorSchemeName,
+  type ImageSourcePropType,
+} from 'react-native';
+import type {
+  NativeImagePreviewColorScheme,
+  NativeImagePreviewItem,
+  NativeImagePreviewItemDescriptor,
+  NativeImagePreviewNativeItem,
+  NativeImagePreviewResolvedItem,
+  NativeImagePreviewResolvedColorScheme,
+  NativeImagePreviewSource,
+} from './types';
+
+function isDescriptor(
+  item: NativeImagePreviewItem
+): item is NativeImagePreviewItemDescriptor {
+  if (item == null || typeof item !== 'object' || Array.isArray(item)) return false;
+  return (
+    'source' in item ||
+    'url' in item ||
+    'poster' in item ||
+    'type' in item ||
+    'id' in item
+  );
+}
+
+export function resolvePreviewSourceUri(
+  source: NativeImagePreviewSource | undefined
+) {
+  if (source == null) return undefined;
+  if (typeof source === 'string') return source;
+
+  const normalizedSource = Array.isArray(source) ? source[0] : source;
+  const resolved = Image.resolveAssetSource(normalizedSource as ImageSourcePropType);
+  return resolved?.uri;
+}
+
+function normalizePreviewItem(
+  item: NativeImagePreviewItem,
+  index: number
+): NativeImagePreviewResolvedItem | null {
+  if (isDescriptor(item)) {
+    const type = item.type ?? 'image';
+    const sourceUrl = resolvePreviewSourceUri(item.source);
+    const url = item.url ?? sourceUrl;
+    if (!url) return null;
+
+    const poster = resolvePreviewSourceUri(item.poster) ?? (type === 'video' ? sourceUrl : undefined);
+
+    return {
+      id: item.id ?? `${index}`,
+      type,
+      url,
+      poster,
+      width: item.width,
+      height: item.height,
+      raw: item,
+    };
+  }
+
+  const url = resolvePreviewSourceUri(item);
+  if (!url) return null;
+
+  return {
+    id: `${index}`,
+    type: 'image',
+    url,
+    raw: item,
+  };
+}
+
+export function normalizeNativeImagePreviewItems(
+  items: readonly NativeImagePreviewItem[]
+) {
+  return items
+    .map((item, index) => normalizePreviewItem(item, index))
+    .filter((item): item is NativeImagePreviewResolvedItem => item != null);
+}
+
+export function toNativePreviewItems(
+  items: readonly NativeImagePreviewResolvedItem[]
+): NativeImagePreviewNativeItem[] {
+  return items.map(({ id, type, url, poster, width, height }) => ({
+    id,
+    type,
+    url,
+    poster,
+    width,
+    height,
+  }));
+}
+
+export function clampPreviewIndex(index: number, length: number) {
+  if (!Number.isFinite(index)) return 0;
+  return Math.max(0, Math.min(Math.round(index), Math.max(0, length - 1)));
+}
+
+export function resolveNativeImagePreviewColorScheme(
+  colorScheme: NativeImagePreviewColorScheme | undefined,
+  systemColorScheme: ColorSchemeName
+): NativeImagePreviewResolvedColorScheme {
+  if (colorScheme === 'light' || colorScheme === 'dark') return colorScheme;
+  if (colorScheme === 'system') return systemColorScheme === 'light' ? 'light' : 'dark';
+  return 'dark';
+}

package/zkit-ui.podspec

@@ -1,6 +1,8 @@
 require 'json'
 
 package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+new_arch_enabled = ENV['RCT_NEW_ARCH_ENABLED'] == '1'
+new_arch_compiler_flags = '-DRCT_NEW_ARCH_ENABLED'
 
 Pod::Spec.new do |s|
   s.name         = 'zkit-ui'
@@ -12,8 +14,18 @@ Pod::Spec.new do |s|
   s.platforms    = { :ios => '15.1' }
   s.source       = { :git => 'https://github.com/Concur-max/zkit.git', :tag => s.version.to_s }
   s.requires_arc = true
+  s.swift_version = '5.4'
+  s.static_framework = true
+  s.compiler_flags = new_arch_compiler_flags if new_arch_enabled
 
-  s.source_files = 'ios/**/*.{h,m,mm}'
+  s.source_files = 'ios/**/*.{h,m,mm,swift}'
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+    'SWIFT_COMPILATION_MODE' => 'wholemodule',
+    'OTHER_SWIFT_FLAGS' => "$(inherited) #{new_arch_enabled ? new_arch_compiler_flags : ''}"
+  }
 
+  s.dependency 'ExpoModulesCore'
   s.dependency 'React-Core'
+  s.dependency 'SDWebImage'
 end