From 14f838c414498bf7a65b904915cd07cf00aa8bb4 Mon Sep 17 00:00:00 2001 From: kdletters Date: Thu, 18 Jun 2026 03:04:21 +0800 Subject: [PATCH] =?UTF-8?q?=E6=8E=A5=E5=85=A5=E7=A7=BB=E5=8A=A8=E5=A3=B3?= =?UTF-8?q?=E5=9B=BE=E7=89=87=E5=AF=BC=E5=85=A5=E8=83=BD=E5=8A=9B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Expo 壳通过系统相册选择器实现 file.importImage 限制导入图片 MIME 与大小并避免暴露设备本地 URI H5 facade 将用户取消导入归为无选择回退 更新移动壳依赖、配置校验、测试和架构文档 --- apps/mobile-shell/app.json | 10 ++ apps/mobile-shell/package.json | 1 + apps/mobile-shell/scripts/check-config.mjs | 31 +++- .../mobile-shell/src/mobileHostBridge.test.ts | 138 ++++++++++++++++++ apps/mobile-shell/src/mobileHostBridge.ts | 98 ++++++++++++- .../shared-memory/decision-log.md | 1 + ...ExpoReactNative与Tauri宿主壳方案-2026-06-17.md | 4 +- ...前端架构】宿主壳能力统一协议-2026-06-17.md | 2 +- package-lock.json | 36 +++++ package.json | 1 + src/services/host-bridge/hostBridge.test.ts | 30 ++++ src/services/host-bridge/hostBridge.ts | 3 +- 12 files changed, 348 insertions(+), 7 deletions(-) diff --git a/apps/mobile-shell/app.json b/apps/mobile-shell/app.json index 13b0f21e..03cbf2a7 100644 --- a/apps/mobile-shell/app.json +++ b/apps/mobile-shell/app.json @@ -10,6 +10,16 @@ "assetBundlePatterns": [ "**/*" ], + "plugins": [ + [ + "expo-image-picker", + { + "photosPermission": "允许 Genarrative 读取你选择的图片，用于导入创作素材和参考图。", + "cameraPermission": false, + "microphonePermission": false + } + ] + ], "ios": { "supportsTablet": true, "associatedDomains": [ diff --git a/apps/mobile-shell/package.json b/apps/mobile-shell/package.json index 45a17d3b..af9e8d43 100644 --- a/apps/mobile-shell/package.json +++ b/apps/mobile-shell/package.json @@ -17,6 +17,7 @@ "expo-clipboard": "^56.0.4", "expo-file-system": "^56.0.8", "expo-haptics": "^56.0.3", + "expo-image-picker": "^56.0.18", "expo-linking": "^56.0.14", "expo-network": "^56.0.5", "expo-sharing": "^56.0.18", diff --git a/apps/mobile-shell/scripts/check-config.mjs b/apps/mobile-shell/scripts/check-config.mjs index 26b426f0..9923232b 100644 --- a/apps/mobile-shell/scripts/check-config.mjs +++ b/apps/mobile-shell/scripts/check-config.mjs @@ -129,18 +129,46 @@ for (const snippet of [ } } -for (const dependency of ['expo-file-system', 'expo-network', 'expo-sharing']) { +for (const dependency of [ + 'expo-file-system', + 'expo-image-picker', + 'expo-network', + 'expo-sharing', +]) { if (!packageConfig.dependencies?.[dependency]) { throw new Error(`mobile shell package missing ${dependency}`); } } +const imagePickerPlugin = appConfig.plugins?.find((plugin) => + Array.isArray(plugin) ? plugin[0] === 'expo-image-picker' : plugin === 'expo-image-picker', +); +if (!imagePickerPlugin) { + throw new Error('mobile shell image picker plugin is missing'); +} + +if (Array.isArray(imagePickerPlugin)) { + const pluginOptions = imagePickerPlugin[1] ?? {}; + if (typeof pluginOptions.photosPermission !== 'string') { + throw new Error('mobile shell image picker photo permission text is missing'); + } + if ( + pluginOptions.cameraPermission !== false || + pluginOptions.microphonePermission !== false + ) { + throw new Error('mobile shell image picker must not request camera or microphone'); + } +} + for (const snippet of [ 'file.exportText', 'file.exportImage', + 'file.importImage', 'network.status', 'getMobileNetworkStatus', 'Sharing.shareAsync', + 'ImagePicker.launchImageLibraryAsync', + 'ImagePicker.requestMediaLibraryPermissionsAsync', 'normalizeHostBridgeExportFileName', 'base64Data', ]) { @@ -172,6 +200,7 @@ for (const capability of [ 'clipboard.writeText', 'file.exportText', 'file.exportImage', + 'file.importImage', 'haptics.impact', ]) { if (!mobileCapabilitySet.has(capability)) { diff --git a/apps/mobile-shell/src/mobileHostBridge.test.ts b/apps/mobile-shell/src/mobileHostBridge.test.ts index d439137a..e8e12267 100644 --- a/apps/mobile-shell/src/mobileHostBridge.test.ts +++ b/apps/mobile-shell/src/mobileHostBridge.test.ts @@ -1,4 +1,5 @@ import * as Haptics from 'expo-haptics'; +import * as ImagePicker from 'expo-image-picker'; import * as Linking from 'expo-linking'; import * as Network from 'expo-network'; import * as Sharing from 'expo-sharing'; @@ -66,6 +67,15 @@ vi.mock('expo-haptics', () => ({ impactAsync: vi.fn(), })); +vi.mock('expo-image-picker', () => ({ + PermissionStatus: { + DENIED: 'denied', + GRANTED: 'granted', + }, + launchImageLibraryAsync: vi.fn(), + requestMediaLibraryPermissionsAsync: vi.fn(), +})); + vi.mock('expo-linking', () => ({ openURL: vi.fn(), })); @@ -156,6 +166,18 @@ afterEach(() => { vi.mocked(Appearance.getColorScheme).mockReset(); vi.mocked(Appearance.getColorScheme).mockReturnValue('light'); vi.mocked(Haptics.impactAsync).mockReset(); + vi.mocked(ImagePicker.launchImageLibraryAsync).mockReset(); + vi.mocked(ImagePicker.launchImageLibraryAsync).mockResolvedValue({ + canceled: true, + assets: null, + }); + vi.mocked(ImagePicker.requestMediaLibraryPermissionsAsync).mockReset(); + vi.mocked(ImagePicker.requestMediaLibraryPermissionsAsync).mockResolvedValue({ + status: ImagePicker.PermissionStatus.GRANTED, + granted: true, + canAskAgain: true, + expires: 'never', + }); vi.mocked(Linking.openURL).mockReset(); vi.mocked(Network.getNetworkStateAsync).mockReset(); vi.mocked(Network.getNetworkStateAsync).mockResolvedValue({ @@ -189,6 +211,9 @@ describe('handleMobileHostBridgeMessage', () => { expect( (okResponse.result as { capabilities: string[] }).capabilities, ).toContain('file.exportText'); + expect( + (okResponse.result as { capabilities: string[] }).capabilities, + ).toContain('file.importImage'); expect( (okResponse.result as { capabilities: string[] }).capabilities, ).toEqual( @@ -550,4 +575,117 @@ describe('handleMobileHostBridgeMessage', () => { expect(writtenFiles).toEqual([]); expect(Sharing.shareAsync).not.toHaveBeenCalled(); }); + + test('file.importImage 调起系统相册并返回受控图片数据', async () => { + vi.mocked(ImagePicker.launchImageLibraryAsync).mockResolvedValue({ + canceled: false, + assets: [ + { + uri: 'file:///private/mobile/参考图.png', + width: 120, + height: 80, + type: 'image', + fileName: ' ../参考:图?.png ', + fileSize: 5, + base64: 'aW1hZ2U=', + mimeType: 'image/png', + }, + ], + }); + + const response = await send(request('file.importImage')); + + expect(expectOk(response).result).toEqual({ + action: 'selected', + fileName: '参考-图-.png', + base64Data: 'aW1hZ2U=', + mimeType: 'image/png', + bytes: 5, + }); + expect(ImagePicker.requestMediaLibraryPermissionsAsync).toHaveBeenCalled(); + expect(ImagePicker.launchImageLibraryAsync).toHaveBeenCalledWith({ + allowsEditing: false, + allowsMultipleSelection: false, + base64: true, + exif: false, + mediaTypes: ['images'], + quality: 1, + }); + }); + + test('file.importImage 取消选择时返回 cancelled', async () => { + vi.mocked(ImagePicker.launchImageLibraryAsync).mockResolvedValue({ + canceled: true, + assets: null, + }); + + const response = await send(request('file.importImage')); + + const failedResponse = expectFailed(response); + expect(failedResponse.error.code).toBe('cancelled'); + }); + + test('file.importImage 拒绝权限、非法 MIME 和超限图片', async () => { + vi.mocked(ImagePicker.requestMediaLibraryPermissionsAsync).mockResolvedValue( + { + status: ImagePicker.PermissionStatus.DENIED, + granted: false, + canAskAgain: false, + expires: 'never', + }, + ); + + const denied = await send(request('file.importImage')); + + expect(expectFailed(denied).error.code).toBe('host_error'); + expect(ImagePicker.launchImageLibraryAsync).not.toHaveBeenCalled(); + + vi.mocked(ImagePicker.requestMediaLibraryPermissionsAsync).mockResolvedValue( + { + status: ImagePicker.PermissionStatus.GRANTED, + granted: true, + canAskAgain: true, + expires: 'never', + }, + ); + vi.mocked(ImagePicker.launchImageLibraryAsync).mockResolvedValue({ + canceled: false, + assets: [ + { + uri: 'file:///private/mobile/参考图.gif', + width: 120, + height: 80, + type: 'image', + fileName: '参考图.gif', + fileSize: 5, + base64: 'aW1hZ2U=', + mimeType: 'image/gif', + }, + ], + }); + + const unsupportedMime = await send(request('file.importImage')); + + expect(expectFailed(unsupportedMime).error.code).toBe('invalid_request'); + + vi.mocked(ImagePicker.launchImageLibraryAsync).mockResolvedValue({ + canceled: false, + assets: [ + { + uri: 'file:///private/mobile/参考图.png', + width: 120, + height: 80, + type: 'image', + fileName: '参考图.png', + fileSize: 10 * 1024 * 1024 + 1, + base64: 'aW1hZ2U=', + mimeType: 'image/png', + }, + ], + }); + + const oversized = await send(request('file.importImage')); + + expect(expectFailed(oversized).error.code).toBe('invalid_request'); + }); }); diff --git a/apps/mobile-shell/src/mobileHostBridge.ts b/apps/mobile-shell/src/mobileHostBridge.ts index b591040a..be5c95f3 100644 --- a/apps/mobile-shell/src/mobileHostBridge.ts +++ b/apps/mobile-shell/src/mobileHostBridge.ts @@ -1,6 +1,7 @@ import * as Clipboard from 'expo-clipboard'; import { File, Paths } from 'expo-file-system'; import * as Haptics from 'expo-haptics'; +import * as ImagePicker from 'expo-image-picker'; import * as Linking from 'expo-linking'; import * as Sharing from 'expo-sharing'; import { @@ -16,11 +17,13 @@ import { type FileExportImageResult, type FileExportTextPayload, type FileExportTextResult, + type FileImportImageResult, type HapticsImpactPayload, HOST_BRIDGE_PROTOCOL, HOST_BRIDGE_VERSION, type HostBridgeCapability, type HostBridgeError, + type HostBridgeImageMimeType, type HostBridgeMethod, type HostBridgeRequest, type HostBridgeResponse, @@ -39,7 +42,8 @@ import { getMobileNetworkStatus } from './mobileShellNetwork'; const WEB_APP_ORIGIN = 'https://app.genarrative.world'; const EXPORT_TEXT_MAX_BYTES = 5 * 1024 * 1024; const EXPORT_IMAGE_MAX_BYTES = 5 * 1024 * 1024; -const EXPORT_IMAGE_MIME_TYPES = new Set([ +const IMPORT_IMAGE_MAX_BYTES = 10 * 1024 * 1024; +const HOST_BRIDGE_IMAGE_MIME_TYPES = new Set([ 'image/png', 'image/jpeg', 'image/webp', @@ -60,6 +64,7 @@ export const MOBILE_HOST_CAPABILITIES: HostBridgeCapability[] = [ 'clipboard.writeText', 'file.exportText', 'file.exportImage', + 'file.importImage', 'haptics.impact', ]; @@ -251,7 +256,10 @@ async function exportTextFile(payload: unknown): Promise { async function exportImageFile(payload: unknown): Promise { const exportPayload = payload as FileExportImagePayload | undefined; const mimeType = exportPayload?.mimeType; - if (typeof mimeType !== 'string' || !EXPORT_IMAGE_MIME_TYPES.has(mimeType)) { + if ( + typeof mimeType !== 'string' || + !HOST_BRIDGE_IMAGE_MIME_TYPES.has(mimeType as HostBridgeImageMimeType) + ) { throw invalidRequest('mimeType must be an allowed image type'); } @@ -288,6 +296,90 @@ async function exportImageFile(payload: unknown): Promise }; } +function normalizeImportedImageMimeType( + value: unknown, +): HostBridgeImageMimeType | null { + if (typeof value !== 'string') { + return null; + } + + const mimeType = value.toLowerCase(); + return HOST_BRIDGE_IMAGE_MIME_TYPES.has(mimeType as HostBridgeImageMimeType) + ? (mimeType as HostBridgeImageMimeType) + : null; +} + +function fallbackImportedImageFileName(mimeType: HostBridgeImageMimeType) { + if (mimeType === 'image/jpeg') { + return 'genarrative-import.jpg'; + } + if (mimeType === 'image/webp') { + return 'genarrative-import.webp'; + } + return 'genarrative-import.png'; +} + +async function importImageFile(): Promise { + const permission = await ImagePicker.requestMediaLibraryPermissionsAsync(); + if (permission.status !== ImagePicker.PermissionStatus.GRANTED) { + throw { + code: 'host_error', + message: 'photo library permission denied', + } satisfies HostBridgeError; + } + + const result = await ImagePicker.launchImageLibraryAsync({ + allowsEditing: false, + allowsMultipleSelection: false, + base64: true, + exif: false, + mediaTypes: ['images'], + quality: 1, + }); + if (result.canceled) { + throw { + code: 'cancelled', + message: 'file import cancelled', + } satisfies HostBridgeError; + } + + const asset = result.assets[0]; + if (!asset || asset.type !== 'image') { + throw invalidRequest('image asset is required'); + } + + const mimeType = normalizeImportedImageMimeType(asset.mimeType); + if (!mimeType) { + throw invalidRequest('mimeType must be an allowed image type'); + } + + const base64Data = normalizedBase64Data(asset.base64); + if (!base64Data) { + throw invalidRequest('base64Data is required'); + } + + const bytes = base64DecodedByteLength(base64Data); + if (bytes <= 0 || bytes > IMPORT_IMAGE_MAX_BYTES) { + throw invalidRequest('image exceeds file import size limit'); + } + if ( + typeof asset.fileSize === 'number' && + asset.fileSize > IMPORT_IMAGE_MAX_BYTES + ) { + throw invalidRequest('image exceeds file import size limit'); + } + + return { + action: 'selected', + fileName: normalizeHostBridgeExportFileName( + asset.fileName || fallbackImportedImageFileName(mimeType), + ), + base64Data, + mimeType, + bytes, + }; +} + async function runHaptics(payload: unknown) { const style = (payload as HapticsImpactPayload | undefined)?.style; const impactStyle = @@ -448,6 +540,8 @@ async function handleRequest(request: HostBridgeRequest) { return ok(request, await exportTextFile(request.payload)); case 'file.exportImage': return ok(request, await exportImageFile(request.payload)); + case 'file.importImage': + return ok(request, await importImageFile()); case 'haptics.impact': return ok(request, await runHaptics(request.payload)); case 'app.setBadgeCount': diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index f5b49d3a..ff47bd94 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -33,6 +33,7 @@ - 2026-06-18 原生壳生命周期事件：新增 `app.lifecycle` HostBridge capability，Expo 壳通过 React Native `AppState` 派发 `active` / `inactive` / `background`，Tauri 壳通过主窗口 focus / blur 派发 `active` / `inactive`；H5 只通过 `subscribeHostAppLifecycle()` 订阅统一状态，后续游戏循环、音频和轮询暂停 / 恢复不得直接依赖 Expo / Tauri 平台细节。 - 2026-06-18 原生壳网络状态：新增 `network.status` 与 `network.statusChanged` HostBridge capability，Expo 壳通过 `expo-network` 查询和订阅真实系统网络状态，Tauri 壳通过短超时连接 `app.genarrative.world:443` 查询主站可达性，并通过 WebView `online` / `offline` 注入变化事件；H5 统一使用 `getHostNetworkStatus()` / `subscribeHostNetworkStatusChange()`，不得直接读取 Expo / Tauri 私有网络 API。 - 2026-06-18 桌面图片导入：新增 `file.importImage` 与 `file.imageDropped` HostBridge capability，Tauri 壳通过系统文件选择框和主窗口拖拽事件读取用户选择 / 拖入的真实图片，只允许 `image/png`、`image/jpeg`、`image/webp` 且单次不超过 10 MiB；H5 统一使用 `importHostImageFile()` / `subscribeHostImageDrop()`，宿主只回传文件名、MIME、base64 内容、字节数和可选坐标，不暴露本地绝对路径，也不开放通用文件系统。 +- 2026-06-18 移动图片导入：Expo 壳开始声明并实现 `file.importImage`，通过 `expo-image-picker` 请求相册权限并打开系统相册选择器，只允许 `image/png`、`image/jpeg`、`image/webp` 且单次不超过 10 MiB；成功只回传清洗后的文件名、MIME、base64 内容和字节数，不暴露设备本地 URI，不请求相机或麦克风权限，用户取消返回 `cancelled` 并由 H5 facade 归为 `false`。 - 影响范围：`src/services/host-bridge/`、未来 `apps/mobile-shell/`、未来 `apps/desktop-shell/`、移动端支付 / 分享 / 深链 / 推送、桌面端系统能力、AI H5 sandbox 的 GameBridge 边界。 - 验证方式：普通浏览器、小程序、Expo 壳、Tauri 壳都能返回正确 `getHostRuntime()`；未支持能力能回退 H5；固定玩法在各宿主中读取同一作品数据和运行态 snapshot；AI sandbox 无法直接调用 HostBridge；Tauri release 不允许任意远端页面调用桌面命令。 - 关联文档：`docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md`、`docs/【前端架构】宿主壳能力统一协议-2026-06-17.md`。 diff --git a/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md b/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md index ab533a50..629507af 100644 --- a/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md +++ b/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md @@ -126,7 +126,7 @@ type HostBridgeEvent = { | `network.statusChanged` | 通知 H5 网络状态变化 | 支持 Expo Network 事件 | 支持 WebView online / offline 事件 | | `clipboard.writeText` | 写剪贴板 | 支持 | 支持 | | `file.exportText` | 导出文本到用户选择的本地文件 | 支持系统分享 / 保存面板 | 支持系统保存对话框 | -| `file.importImage` | 导入用户选择的图片文件 | 不声明 | 支持系统选择图片 | +| `file.importImage` | 导入用户选择的图片文件 | 支持系统相册选择图片 | 支持系统选择图片 | | `file.imageDropped` | 通知 H5 桌面拖入图片 | 不声明 | 支持主窗口拖拽图片事件 | | `haptics.impact` | 轻量触感反馈 | 支持 | 不声明 | @@ -249,7 +249,7 @@ GameBridge 禁止： - iOS / Android 深链打开作品详情、创作页和邀请码。 - 登录和支付先 fallback 到 H5；只把能力边界跑通。 -当前状态：已新增 `apps/mobile-shell/`，通过 Expo development build 运行，`react-native-webview` 加载 H5 URL 并附加 `native_app` 宿主 query。移动壳使用真实品牌图标资产，已接入 `genarrative://` scheme、iOS associated domain 和 Android app link filter，启动和运行时 deep link 只会映射到同源 H5 路径并继续附加 HostBridge 上下文，外域和危险协议回退到默认主站入口。首轮真实能力包括 `host.getRuntime`、`appearance.getColorScheme`、`host.events`、`app.lifecycle`、`network.status`、`network.statusChanged`、`share.open`、`share.setTarget`、`navigation.openNativePage`、`navigation.canGoBack`、`app.openExternalUrl`、`clipboard.writeText`、`file.exportText`、`file.exportImage`、`haptics.impact` 和 Android 返回键回退；其中 `appearance.getColorScheme` 只读系统配色偏好，不强改 H5 或系统主题；`app.lifecycle` 通过 React Native `AppState` 注入 `active` / `inactive` / `background` 统一状态，供 H5 游戏循环、音频和轮询做真实暂停 / 恢复判断；`network.status` / `network.statusChanged` 通过 `expo-network` 查询并订阅真实系统网络状态，供 H5 游戏运行态和生成页识别离线 / 弱网回退；iOS 额外声明 `app.setBadgeCount`，通过 React Native `PushNotificationIOS` 设置应用图标角标，Android 不声明该能力。H5 会解析并过滤 `hostCapabilities`，也会在主 App 启动时通过真实 `host.getRuntime` 回读并缓存能力，只对声明或回读到的能力展示入口或调用宿主能力；其中 `share.setTarget` / `share.open` 会解析统一分享目标里的 `title`、`message`、`url`、`work`、`path` 或 `targetPath` 并调用 React Native 系统分享面板；发布分享弹窗只有在宿主声明 `share.open` 时才提供“系统分享”动作，失败时保留复制链接回退路径；`navigation.openNativePage` 在 Expo 壳内只接受同源 H5 route 并切换 WebView URL，不伪造尚未存在的登录、支付或其它原生页面，`navigation.canGoBack` 由 WebView 导航状态变化实时注入 H5，WebView 自身拦截到外域导航时只会把 `http:`、`https:`、`mailto:`、`tel:` 交给系统，危险协议直接阻断；`app.openExternalUrl` 也只允许同一协议白名单，ICP备案号和资产调试原图等 H5 外链入口在 `native_app` 中优先通过该能力离开 WebView 并交给系统浏览器；`clipboard.writeText` 由 H5 复制服务优先调用并写入系统剪贴板；`file.exportText` 通过 Expo 文件系统写入缓存文本文件，再交给系统分享 / 保存面板，文件名必须清洗，单次文本不超过 5 MiB，成功只返回文件名和字节数；`file.exportImage` 通过 Expo 文件系统写入缓存图片，再交给系统分享 / 保存面板，H5 只传允许 MIME 的 base64 图片数据，单次不超过 5 MiB，分享卡下载会优先走该能力；`haptics.impact` 通过 Expo Haptics 承接运行时轻触反馈，H5 在宿主不支持时回退到浏览器 vibration。登录和支付尚未接入渠道 SDK / 原生页面时明确返回 unsupported，让 H5 fallback 承接。 +当前状态：已新增 `apps/mobile-shell/`，通过 Expo development build 运行，`react-native-webview` 加载 H5 URL 并附加 `native_app` 宿主 query。移动壳使用真实品牌图标资产，已接入 `genarrative://` scheme、iOS associated domain 和 Android app link filter，启动和运行时 deep link 只会映射到同源 H5 路径并继续附加 HostBridge 上下文，外域和危险协议回退到默认主站入口。首轮真实能力包括 `host.getRuntime`、`appearance.getColorScheme`、`host.events`、`app.lifecycle`、`network.status`、`network.statusChanged`、`share.open`、`share.setTarget`、`navigation.openNativePage`、`navigation.canGoBack`、`app.openExternalUrl`、`clipboard.writeText`、`file.exportText`、`file.exportImage`、`file.importImage`、`haptics.impact` 和 Android 返回键回退；其中 `appearance.getColorScheme` 只读系统配色偏好，不强改 H5 或系统主题；`app.lifecycle` 通过 React Native `AppState` 注入 `active` / `inactive` / `background` 统一状态，供 H5 游戏循环、音频和轮询做真实暂停 / 恢复判断；`network.status` / `network.statusChanged` 通过 `expo-network` 查询并订阅真实系统网络状态，供 H5 游戏运行态和生成页识别离线 / 弱网回退；iOS 额外声明 `app.setBadgeCount`，通过 React Native `PushNotificationIOS` 设置应用图标角标，Android 不声明该能力。H5 会解析并过滤 `hostCapabilities`，也会在主 App 启动时通过真实 `host.getRuntime` 回读并缓存能力，只对声明或回读到的能力展示入口或调用宿主能力；其中 `share.setTarget` / `share.open` 会解析统一分享目标里的 `title`、`message`、`url`、`work`、`path` 或 `targetPath` 并调用 React Native 系统分享面板；发布分享弹窗只有在宿主声明 `share.open` 时才提供“系统分享”动作，失败时保留复制链接回退路径；`navigation.openNativePage` 在 Expo 壳内只接受同源 H5 route 并切换 WebView URL，不伪造尚未存在的登录、支付或其它原生页面，`navigation.canGoBack` 由 WebView 导航状态变化实时注入 H5，WebView 自身拦截到外域导航时只会把 `http:`、`https:`、`mailto:`、`tel:` 交给系统，危险协议直接阻断；`app.openExternalUrl` 也只允许同一协议白名单，ICP备案号和资产调试原图等 H5 外链入口在 `native_app` 中优先通过该能力离开 WebView 并交给系统浏览器；`clipboard.writeText` 由 H5 复制服务优先调用并写入系统剪贴板；`file.exportText` 通过 Expo 文件系统写入缓存文本文件，再交给系统分享 / 保存面板，文件名必须清洗，单次文本不超过 5 MiB，成功只返回文件名和字节数；`file.exportImage` 通过 Expo 文件系统写入缓存图片，再交给系统分享 / 保存面板，H5 只传允许 MIME 的 base64 图片数据，单次不超过 5 MiB，分享卡下载会优先走该能力；`file.importImage` 通过 Expo ImagePicker 请求相册权限并打开系统相册选择器，只接受 `image/png` / `image/jpeg` / `image/webp`、单次不超过 10 MiB，成功只返回清洗后的文件名、MIME、base64 内容和字节数，不把设备本地 URI 暴露给 H5，用户取消返回 `cancelled` 并由 H5 视作无选择；`haptics.impact` 通过 Expo Haptics 承接运行时轻触反馈，H5 在宿主不支持时回退到浏览器 vibration。登录和支付尚未接入渠道 SDK / 原生页面时明确返回 unsupported，让 H5 fallback 承接。 ### Phase 3：Tauri 桌面壳 MVP diff --git a/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md b/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md index 70cdab4f..4c3f746b 100644 --- a/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md +++ b/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md @@ -56,7 +56,7 @@ AI H5 sandbox - `navigateHostNativePage()`：受控跳转宿主页，供订阅授权、支付、登录等 adapter 复用。Expo 移动壳首版只接受同源 H5 route 并切换 WebView URL；Tauri 桌面壳同样只接受 `https://app.genarrative.world` 同源 H5 route 并在主窗口内跳转。真正原生页面、登录和支付能力必须等对应 SDK / 页面接入后再声明支持。 - `exportHostTextFile()`：原生 App 宿主的受控文本导出入口。Expo 移动壳通过 `file.exportText` 写入缓存文本文件并交给系统分享 / 保存面板；Tauri 桌面壳通过 `file.exportText` 打开系统保存对话框并写入用户选择的文件。文件名必须清洗，单次文本不超过 5 MiB，成功只返回文件名和字节数，不把本机绝对路径暴露给 H5；系统分享不可用或用户取消时返回明确错误，由 H5 fallback 承接。 - `exportHostImageFile()`：原生 App 宿主的受控图片导出入口。H5 只传自己生成的图片 `base64Data`、清洗后的文件名和允许的 `image/png` / `image/jpeg` / `image/webp` MIME；Expo 移动壳写入缓存图片后交给系统分享 / 保存面板，Tauri 桌面壳打开系统保存对话框并写入图片字节。单次图片不超过 5 MiB，成功只返回文件名和字节数，不回传本机绝对路径。当前分享卡下载在 native app 中优先走 `file.exportImage`，宿主未声明时保留浏览器下载路径。 -- `importHostImageFile()` / `subscribeHostImageDrop()`：桌面 App 宿主的受控图片导入入口。Tauri 壳通过系统文件选择框或主窗口拖拽事件读取用户选择 / 拖入的图片，只接受 `image/png`、`image/jpeg`、`image/webp`，单次不超过 10 MiB，成功只返回文件名、MIME、base64 内容、字节数和可选拖入坐标，不把本机绝对路径暴露给 H5，也不开放通用文件系统能力；Expo 移动壳未接入真实图片选择器前不声明该能力。 +- `importHostImageFile()` / `subscribeHostImageDrop()`：原生 App 宿主的受控图片导入入口。Expo 移动壳通过 Expo ImagePicker 请求相册权限并打开系统相册选择器，Tauri 壳通过系统文件选择框或主窗口拖拽事件读取用户选择 / 拖入的图片；两端都只接受 `image/png`、`image/jpeg`、`image/webp`，单次不超过 10 MiB，成功只返回文件名、MIME、base64 内容、字节数和可选拖入坐标，不暴露设备本地 URI 或本机绝对路径，也不开放通用文件系统能力。 ## 迁移顺序 diff --git a/package-lock.json b/package-lock.json index 629b9a11..52d5b90a 100644 --- a/package-lock.json +++ b/package-lock.json @@ -19,6 +19,7 @@ "expo-clipboard": "^56.0.4", "expo-file-system": "^56.0.8", "expo-haptics": "^56.0.3", + "expo-image-picker": "^56.0.18", "expo-linking": "^56.0.14", "expo-network": "^56.0.5", "expo-sharing": "^56.0.18", @@ -6388,6 +6389,27 @@ "expo": "*" } }, + "node_modules/expo-image-loader": { + "version": "56.0.3", + "resolved": "https://registry.npmjs.org/expo-image-loader/-/expo-image-loader-56.0.3.tgz", + "integrity": "sha512-JgUo4fUeU1ZC+z8iBFj8v7yoGQnZrLbOVPyNE+DWVrld55F2F6R1ck+rmdm/8TNWLz1LhNQfD7c3XYP1ZikxXA==", + "license": "MIT", + "peerDependencies": { + "expo": "*" + } + }, + "node_modules/expo-image-picker": { + "version": "56.0.18", + "resolved": "https://registry.npmjs.org/expo-image-picker/-/expo-image-picker-56.0.18.tgz", + "integrity": "sha512-sCjQ8M27bhGUv2vUavIE+uWdYo79b2D7Q5h9B66BSDZ+Rd8YyLVSf7vYGfIzQ7nMVoENZ6c4xo/JiDkEeQ9iTg==", + "license": "MIT", + "dependencies": { + "expo-image-loader": "~56.0.3" + }, + "peerDependencies": { + "expo": "*" + } + }, "node_modules/expo-keep-awake": { "version": "56.0.3", "resolved": "https://registry.npmjs.org/expo-keep-awake/-/expo-keep-awake-56.0.3.tgz", @@ -17292,6 +17314,20 @@ "integrity": "sha512-ycoahZJnR9tWAVh/0mJYxbETtHRYaWjiWS8cHlP6aDGU6Q6Y8rZ5NKsuBwWw6HR2Pe30mfVFgbF2HrBR6gtYmw==", "requires": {} }, + "expo-image-loader": { + "version": "56.0.3", + "resolved": "https://registry.npmjs.org/expo-image-loader/-/expo-image-loader-56.0.3.tgz", + "integrity": "sha512-JgUo4fUeU1ZC+z8iBFj8v7yoGQnZrLbOVPyNE+DWVrld55F2F6R1ck+rmdm/8TNWLz1LhNQfD7c3XYP1ZikxXA==", + "requires": {} + }, + "expo-image-picker": { + "version": "56.0.18", + "resolved": "https://registry.npmjs.org/expo-image-picker/-/expo-image-picker-56.0.18.tgz", + "integrity": "sha512-sCjQ8M27bhGUv2vUavIE+uWdYo79b2D7Q5h9B66BSDZ+Rd8YyLVSf7vYGfIzQ7nMVoENZ6c4xo/JiDkEeQ9iTg==", + "requires": { + "expo-image-loader": "~56.0.3" + } + }, "expo-keep-awake": { "version": "56.0.3", "resolved": "https://registry.npmjs.org/expo-keep-awake/-/expo-keep-awake-56.0.3.tgz", diff --git a/package.json b/package.json index b5b3d066..f629d2c5 100644 --- a/package.json +++ b/package.json @@ -89,6 +89,7 @@ "expo-clipboard": "^56.0.4", "expo-file-system": "^56.0.8", "expo-haptics": "^56.0.3", + "expo-image-picker": "^56.0.18", "expo-linking": "^56.0.14", "expo-network": "^56.0.5", "expo-sharing": "^56.0.18", diff --git a/src/services/host-bridge/hostBridge.test.ts b/src/services/host-bridge/hostBridge.test.ts index 286fe559..e35283d2 100644 --- a/src/services/host-bridge/hostBridge.test.ts +++ b/src/services/host-bridge/hostBridge.test.ts @@ -1089,4 +1089,34 @@ describe('hostBridge', () => { }), }); }); + + test('原生 App 宿主取消导入图片时回退为 false', async () => { + const invoke = vi.fn( + async (_command: string, args?: Record) => { + const request = (args as { request: { id: string } }).request; + return { + bridge: 'GenarrativeHostBridge', + version: 1, + id: request.id, + ok: false, + error: { + code: 'cancelled', + message: 'file import cancelled', + }, + }; + }, + ); + window.history.replaceState( + null, + '', + nativeAppPath(['file.importImage']), + ); + window.__TAURI__ = { + core: { + invoke: asTauriInvoke(invoke), + }, + }; + + await expect(importHostImageFile()).resolves.toBe(false); + }); }); diff --git a/src/services/host-bridge/hostBridge.ts b/src/services/host-bridge/hostBridge.ts index 3ddb94e0..6e1d9c29 100644 --- a/src/services/host-bridge/hostBridge.ts +++ b/src/services/host-bridge/hostBridge.ts @@ -125,7 +125,8 @@ function isUnsupportedHostBridgeError(error: unknown) { return ( error instanceof Error && (error.name === 'unsupported_method' || - error.name === 'unsupported_capability') + error.name === 'unsupported_capability' || + error.name === 'cancelled') ); }