zkit-ui 2.0.5 → 2.0.7

package/ios/{GaleriaView.swift → NativeImagePreviewView.swift}

@@ -1,10 +1,10 @@
 import ExpoModulesCore
 import UIKit
 
-class GaleriaView: ExpoView {
+class NativeImagePreviewView: ExpoView {
   private var childImageView: UIImageView?
   private weak var registeredAnchorImageView: UIImageView?
-  private var registeredGalleryId: String?
+  private var registeredPreviewGroupId: String?
   private var registeredIndex: Int?
 
   deinit {
@@ -57,11 +57,10 @@ class GaleriaView: ExpoView {
   #endif
 
   #if RCT_NEW_ARCH_ENABLED
-    // https://github.com/nandorojo/galeria/issues/19
-    // Cleanup gesture recognizers from the image view to work with fabric view recycling
+    // Cleanup gesture recognizers from the image view to work with Fabric view recycling.
     override func unmountChildComponentView(_ childComponentView: UIView, index: Int) {
       unregisterCurrentAnchor()
-      childImageView?.removeGaleriaViewerInteraction()
+      childImageView?.removeNativeImagePreviewViewerInteraction()
       childImageView = nil
       super.unmountChildComponentView(childComponentView, index: index)
     }
@@ -71,7 +70,7 @@ class GaleriaView: ExpoView {
   var urls: [String]?
   var items: [[String: Any]]?
   var initialIndex: Int?
-  var galleryId: String?
+  var previewGroupId: String?
   var closeIconName: String?
   var rightNavItemIconName: String?
   let onPressRightNavItemIcon = EventDispatcher()
@@ -99,7 +98,7 @@ class GaleriaView: ExpoView {
   ) {
     let configuration = buildViewerConfiguration()
 
-    let imageItems: [GaleriaMediaItem] = items.compactMap { item in
+    let imageItems: [NativeImagePreviewMediaItem] = items.compactMap { item in
         guard let type = item["type"] as? String else { return nil }
 
         if type == "video", let urlStr = item["url"] as? String, let url = URL(string: urlStr) {
@@ -107,25 +106,25 @@ class GaleriaView: ExpoView {
             if let posterStr = item["poster"] as? String {
                 posterUrl = URL(string: posterStr)
             }
-            return GaleriaMediaItem.video(url: url, poster: posterUrl)
+            return NativeImagePreviewMediaItem.video(url: url, poster: posterUrl)
         } else if type == "image", let urlStr = item["url"] as? String {
              if urlStr.hasPrefix("http://") || urlStr.hasPrefix("https://") || urlStr.hasPrefix("file://") {
                 if let url = URL(string: urlStr) {
-                    return GaleriaMediaItem.imageURL(url, placeholder: nil)
+                    return NativeImagePreviewMediaItem.imageURL(url, placeholder: nil)
                 }
              } else {
-                return GaleriaMediaItem.imageURL(URL(fileURLWithPath: urlStr), placeholder: nil)
+                return NativeImagePreviewMediaItem.imageURL(URL(fileURLWithPath: urlStr), placeholder: nil)
              }
         }
         return nil
     }
 
-    let datasource = GaleriaArrayDataSource(items: imageItems)
-    childImage.setupGaleriaViewer(
+    let datasource = NativeImagePreviewArrayDataSource(items: imageItems)
+    childImage.setupNativeImagePreviewViewer(
       dataSource: datasource,
       initialIndex: initialIndex,
       configuration: configuration,
-      galleryId: galleryId)
+      previewGroupId: previewGroupId)
   }
 
 
@@ -143,11 +142,11 @@ class GaleriaView: ExpoView {
       return URL(fileURLWithPath: string)
     }
 
-    childImage.setupGaleriaViewer(
+    childImage.setupNativeImagePreviewViewer(
       urls: urlObjects,
       initialIndex: initialIndex,
       configuration: configuration,
-      galleryId: galleryId)
+      previewGroupId: previewGroupId)
   }
 
   private func setupViewerWithSingleImage(_ childImage: UIImageView) {
@@ -157,11 +156,11 @@ class GaleriaView: ExpoView {
     }
     let configuration = buildViewerConfiguration()
 
-    childImage.setupGaleriaViewer(images: [img], configuration: configuration, galleryId: galleryId)
+    childImage.setupNativeImagePreviewViewer(images: [img], configuration: configuration, previewGroupId: previewGroupId)
   }
 
-  private func buildViewerConfiguration() -> GaleriaViewerConfiguration {
-    var configuration = GaleriaViewerConfiguration(theme: theme.toViewerTheme())
+  private func buildViewerConfiguration() -> NativeImagePreviewViewerConfiguration {
+    var configuration = NativeImagePreviewViewerConfiguration(theme: theme.toViewerTheme())
     let iconColor = theme.iconColor()
 
     if let closeIconName = closeIconName,
@@ -191,7 +190,7 @@ class GaleriaView: ExpoView {
   private func registerCurrentAnchorIfNeeded() {
     guard
       window != nil,
-      let galleryId,
+      let previewGroupId,
       let initialIndex,
       let childImage = getChildImageView()
     else {
@@ -202,30 +201,30 @@ class GaleriaView: ExpoView {
     if
       let registeredAnchorImageView,
       (registeredAnchorImageView !== childImage
-        || registeredGalleryId != galleryId
+        || registeredPreviewGroupId != previewGroupId
         || registeredIndex != initialIndex)
     {
       unregisterCurrentAnchor()
     }
 
-    GaleriaSourceViewRegistry.shared.register(
+    NativeImagePreviewSourceViewRegistry.shared.register(
       childImage,
-      galleryId: galleryId,
+      previewGroupId: previewGroupId,
       index: initialIndex)
     registeredAnchorImageView = childImage
-    registeredGalleryId = galleryId
+    registeredPreviewGroupId = previewGroupId
     registeredIndex = initialIndex
   }
 
   private func unregisterCurrentAnchor() {
     if let registeredAnchorImageView = registeredAnchorImageView {
-      GaleriaSourceViewRegistry.shared.unregister(
+      NativeImagePreviewSourceViewRegistry.shared.unregister(
         registeredAnchorImageView,
-        galleryId: registeredGalleryId,
+        previewGroupId: registeredPreviewGroupId,
         index: registeredIndex)
     }
     registeredAnchorImageView = nil
-    registeredGalleryId = nil
+    registeredPreviewGroupId = nil
     registeredIndex = nil
   }
 }
@@ -234,7 +233,7 @@ enum Theme: String, Enumerable {
   case dark
   case light
 
-  func toViewerTheme() -> GaleriaViewerTheme {
+  func toViewerTheme() -> NativeImagePreviewViewerTheme {
     switch self {
     case .dark:
       return .dark

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zkit-ui",
-  "version": "2.0.5",
+  "version": "2.0.7",
   "private": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -170,7 +170,10 @@
     "./assets/*": "./dist/assets/*",
     "./package.json": "./package.json"
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "*.css",
+    "**/*.css"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Concur-max/zkit.git",
@@ -181,7 +184,8 @@
     "url": "https://github.com/Concur-max/zkit/issues"
   },
   "files": [
-    "android",
+    "android/build.gradle",
+    "android/src",
     "dist",
     "expo-module.config.json",
     "src",
@@ -193,6 +197,14 @@
   "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",
@@ -219,6 +231,7 @@
   },
   "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",
@@ -235,13 +248,6 @@
     "react-native-svg": "^15.12.1",
     "react-native-worklets": "0.5.1",
     "sonner-native": "^0.22.2",
-    "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"
+    "typescript": "~5.9.3"
   }
-}
+}

package/src/services/ImagePreviewService/README.md

@@ -77,7 +77,7 @@ import { NativeImagePreview } from 'zkit-ui/native-image-preview';
 两者不要混用成同一个本地封装：
 
 - `ImagePreview`：普通全屏预览，支持声明式 `open/value` 和命令式 `imagePreview.open()`。
-- `NativeImagePreview`：原生共享转场预览，需要包住真实缩略图节点，iOS / Android 走原生 viewer。
+- `NativeImagePreview`：共享转场预览，需要包住真实缩略图节点，iOS / Android 走原生 viewer，Web 走 H5 viewer。
 
 ## 手动确认点
 

package/src/types.d.ts

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

package/src/ui/Button/README.md

@@ -186,5 +186,5 @@ export function Demo() {
 
 - `disabled` 会禁用交互并进入禁用视觉；`loading` 只禁用交互，不强制置灰
 - 显式传入 `hitSlop` 时以调用侧为准；否则小尺寸和 `link` 会自动补足触控热区
-- `accessibilityRole` 固定为 `button`
+- Native 端 `accessibilityRole` 固定为 `button`；Web 端根节点不设置 `button` role，避免 RN Web 将 Button 渲染为真实 `<button>` 后产生嵌套按钮问题
 - `iconOnly` 必须提供可读的 `accessibilityLabel`，除非 children 是可作为标签的文本

package/src/ui/Button/index.tsx

@@ -108,7 +108,7 @@ export type ButtonColors = {
 
 type NativePressableProps = Omit<
   React.ComponentPropsWithoutRef<typeof Pressable>,
-  'accessibilityRole' | 'accessibilityState' | 'children' | 'disabled' | 'style'
+  'accessibilityRole' | 'accessibilityState' | 'children' | 'disabled' | 'role' | 'style'
 >;
 
 export type ButtonRef = React.ComponentRef<typeof Pressable>;
@@ -839,6 +839,20 @@ function resolveWebCursorStyle(disabled: boolean): ViewStyle | undefined {
   return { cursor: disabled ? 'not-allowed' : 'pointer' } as ViewStyle;
 }
 
+function resolveRootAccessibilityRole() {
+  return Platform.OS === 'web' ? undefined : 'button';
+}
+
+function resolveRootPressableProps<T extends object>(props: T): T {
+  if (Platform.OS !== 'web') return props;
+
+  const { accessibilityRole: _accessibilityRole, role: _role, ...rest } = props as T & {
+    accessibilityRole?: unknown;
+    role?: unknown;
+  };
+  return rest as T;
+}
+
 function requiresAnimatedPressEffect(effect: ButtonPressEffect | undefined) {
   return (
     effect === 'scale' ||
@@ -1161,6 +1175,8 @@ function ButtonStaticImpl(
     },
     [interactionDisabled, onPress]
   );
+  const rootAccessibilityRole = resolveRootAccessibilityRole();
+  const rootPressableProps = resolveRootPressableProps(pressableProps);
   const pressOpacityEnabled = !interactionDisabled && (pressEffect === 'auto' || pressEffect === 'opacity');
   const rootStyle = React.useCallback(
     ({ pressed }: PressableStateCallbackType) => [
@@ -1186,10 +1202,10 @@ function ButtonStaticImpl(
 
   return (
     <Pressable
-      {...pressableProps}
+      {...rootPressableProps}
       ref={ref}
       accessibilityLabel={resolvedAccessibilityLabel}
-      accessibilityRole="button"
+      accessibilityRole={rootAccessibilityRole}
       accessibilityState={{
         ...accessibilityState,
         busy: Boolean(loading || accessibilityState?.busy),
@@ -1398,13 +1414,15 @@ function ButtonPressAnimatedImpl(
     },
     [interactionDisabled, onPressOut, pressSv, resolvedPressEffect]
   );
+  const rootAccessibilityRole = resolveRootAccessibilityRole();
+  const rootPressableProps = resolveRootPressableProps(pressableProps);
 
   return (
     <AnimatedPressable
-      {...pressableProps}
+      {...rootPressableProps}
       ref={ref}
       accessibilityLabel={resolvedAccessibilityLabel}
-      accessibilityRole="button"
+      accessibilityRole={rootAccessibilityRole}
       accessibilityState={{
         ...accessibilityState,
         busy: Boolean(loading || accessibilityState?.busy),
@@ -1736,13 +1754,15 @@ function ButtonAnimatedImpl(
     },
     [interactionDisabled, onPressOut, pressSv, resolvedPressEffect]
   );
+  const rootAccessibilityRole = resolveRootAccessibilityRole();
+  const rootPressableProps = resolveRootPressableProps(pressableProps);
 
   return (
     <AnimatedPressable
-      {...pressableProps}
+      {...rootPressableProps}
       ref={ref}
       accessibilityLabel={resolvedAccessibilityLabel}
-      accessibilityRole="button"
+      accessibilityRole={rootAccessibilityRole}
       accessibilityState={{
         ...accessibilityState,
         busy: Boolean(loading || accessibilityState?.busy),

package/src/ui/NativeImagePreview/NativeImagePreview.tsx

@@ -25,7 +25,7 @@ type NativePreviewViewProps = {
   children: React.ReactElement;
   index: number;
   style?: StyleProp<ViewStyle>;
-  galleryId: string;
+  previewGroupId: string;
   items: readonly NativeImagePreviewNativeItem[];
   theme: 'dark' | 'light';
   edgeToEdge: boolean;
@@ -39,7 +39,7 @@ const NativePreviewView = requireNativeView<NativePreviewViewProps>(
 
 const ANDROID_EDGE_TO_EDGE = Platform.OS === 'android' ? isEdgeToEdge() : false;
 
-function createGalleryId() {
+function createPreviewGroupId() {
   return `zkit-native-image-preview-${Date.now().toString(36)}-${Math.random()
     .toString(36)
     .slice(2, 10)}`;
@@ -55,9 +55,9 @@ const NativeImagePreviewRoot = React.memo(function NativeImagePreview({
   onChange,
 }: NativeImagePreviewProps) {
   const systemColorScheme = useColorScheme();
-  const galleryIdRef = React.useRef<string | null>(null);
-  if (galleryIdRef.current == null) {
-    galleryIdRef.current = createGalleryId();
+  const previewGroupIdRef = React.useRef<string | null>(null);
+  if (previewGroupIdRef.current == null) {
+    previewGroupIdRef.current = createPreviewGroupId();
   }
 
   const resolvedItems = React.useMemo(
@@ -71,7 +71,7 @@ const NativeImagePreviewRoot = React.memo(function NativeImagePreview({
   const resolvedColorScheme = resolveNativeImagePreviewColorScheme(colorScheme, systemColorScheme);
   const contextValue = React.useMemo(
     () => ({
-      galleryId: galleryIdRef.current!,
+      previewGroupId: previewGroupIdRef.current!,
       items: resolvedItems,
       nativeItems,
       colorScheme: resolvedColorScheme,
@@ -129,7 +129,7 @@ const NativeImagePreviewItem = React.memo(function NativeImagePreviewItem({
     <NativePreviewView
       closeIconName={context.nativeProps?.iosCloseIconName}
       edgeToEdge={resolvedEdgeToEdge}
-      galleryId={context.galleryId}
+      previewGroupId={context.previewGroupId}
       index={clampPreviewIndex(index, context.nativeItems.length)}
       items={context.nativeItems}
       onIndexChange={handleIndexChange}

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

@@ -1,35 +1,199 @@
+/// <reference lib="dom" />
+
+import './web/styles.css';
+
 import * as React from 'react';
-import { View } from 'react-native';
+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';
 
-let didWarnUnsupportedWeb = false;
+type SourceElement = HTMLElement | null;
 
-function warnUnsupportedWeb() {
-  if (!__DEV__ || didWarnUnsupportedWeb) return;
+type NativeImagePreviewWebContextValue = {
+  disabled: boolean;
+  items: readonly NativeImagePreviewResolvedItem[];
+  open: (
+    index: number,
+    onItemChange?: (value: number, meta: NativeImagePreviewChangeMeta) => void
+  ) => void;
+  sourceElementsRef: { current: SourceElement[] };
+};
 
-  didWarnUnsupportedWeb = true;
-  console.warn(
-    '[zkit-ui][NativeImagePreview] Native shared-transition preview is only available in iOS and Android native builds.'
-  );
+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) {
-  React.useEffect(warnUnsupportedWeb, []);
+  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;
+    };
+  }, []);
 
-  return <>{children}</>;
+  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) {
-  return <View style={style}>{children}</View>;
+  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, {

package/src/ui/NativeImagePreview/README.md

@@ -1,6 +1,6 @@
 # NativeImagePreview
 
-`NativeImagePreview` 是强调原生共享转场体验的图片预览组件。它和普通 `ImagePreview` 服务分工不同：`ImagePreview` 适合命令式打开图片；`NativeImagePreview` 适合从真实缩略图自然过渡到全屏 viewer，并在 iOS / Android 上走原生手势、缩放、滑动和拖拽关闭路径。
+`NativeImagePreview` 是强调真实缩略图锚点与共享转场体验的图片预览组件。它和普通 `ImagePreview` 服务分工不同：`ImagePreview` 适合命令式打开图片；`NativeImagePreview` 适合从真实缩略图自然过渡到全屏 viewer，并在 iOS / Android 上走原生手势、缩放、滑动和拖拽关闭路径，在 Web 上走 H5 共享转场 viewer。
 
 ## 适用场景
 
@@ -95,14 +95,14 @@ import { imagePreview } from 'zkit-ui/image-preview';
 imagePreview.open({ images, index: 0 });
 ```
 
-`ImagePreview` 是普通全屏预览服务，适合没有稳定缩略图锚点的命令式场景。`NativeImagePreview` 是声明式共享转场组件，必须就地包住真实图片节点。两者不要混成同一个封装，否则很容易把原生共享转场退化成普通弹层。
+`ImagePreview` 是普通全屏预览服务，适合没有稳定缩略图锚点的命令式场景。`NativeImagePreview` 是声明式共享转场组件，必须就地包住真实图片节点。两者不要混成同一个封装，否则很容易把共享转场退化成普通弹层。
 
 ## 平台行为
 
 - iOS / Android：使用原生 viewer 和真实图片锚点，主打共享转场、缩放、滑动和拖拽关闭。
+- Web：使用 H5 viewer 和真实 DOM 图片锚点，支持共享转场、缩放、滑动、视频播放和拖拽关闭。
 - 首次接入或变更原生依赖后需要重新构建 native app；仅刷新 JS bundle 不会注册新的原生 ViewManager。
 - 原生模块未注册时不会降级到 `ImagePreview`。这是 native 接入或构建错误，需要重新安装依赖并重建 native app。
-- Web：仅保留子节点渲染，不提供预览能力，也不会模拟普通 `ImagePreview`。
 
 ## 手动确认点
 

package/src/ui/NativeImagePreview/context.tsx

@@ -8,7 +8,7 @@ import type {
 } from './types';
 
 export type NativeImagePreviewContextValue = {
-  galleryId: string;
+  previewGroupId: string;
   items: readonly NativeImagePreviewResolvedItem[];
   nativeItems: readonly NativeImagePreviewNativeItem[];
   colorScheme: NativeImagePreviewResolvedColorScheme;

package/src/ui/NativeImagePreview/types.ts

@@ -15,6 +15,7 @@ export type NativeImagePreviewSource = ImageSourcePropType | string;
 
 export type NativeImagePreviewItemDescriptor = {
   id?: string;
+  alt?: string;
   type?: NativeImagePreviewMediaType;
   url?: string;
   source?: NativeImagePreviewSource;
@@ -34,6 +35,7 @@ export type NativeImagePreviewResolvedItem = {
   poster?: string;
   width?: number;
   height?: number;
+  alt?: string;
   raw: NativeImagePreviewItem;
 };
 
@@ -46,7 +48,7 @@ export type NativeImagePreviewNativeItem = {
   height?: number;
 };
 
-export type NativeImagePreviewChangeReason = 'swipe';
+export type NativeImagePreviewChangeReason = 'api' | 'swipe';
 
 export type NativeImagePreviewChangeEventPayload = {
   currentIndex: number;

package/src/ui/NativeImagePreview/utils.ts

@@ -56,6 +56,7 @@ function normalizePreviewItem(
       poster,
       width: item.width,
       height: item.height,
+      alt: item.alt,
       raw: item,
     };
   }