From 586e46fa630aa6caec14b9880482b424fcf5d44e Mon Sep 17 00:00:00 2001 From: kdletters Date: Thu, 18 Jun 2026 02:35:48 +0800 Subject: [PATCH] =?UTF-8?q?=E6=8E=A5=E5=85=A5=E5=8E=9F=E7=94=9F=E5=A3=B3?= =?UTF-8?q?=E7=BD=91=E7=BB=9C=E7=8A=B6=E6=80=81=E8=83=BD=E5=8A=9B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 network.status 与 network.statusChanged HostBridge 能力 Expo 壳通过 expo-network 查询并订阅真实网络状态 Tauri 壳通过主站可达性查询和 WebView online/offline 事件同步网络状态 更新壳能力检查、测试和架构文档 --- apps/desktop-shell/scripts/check-config.mjs | 4 + apps/desktop-shell/src-tauri/src/main.rs | 122 ++++++++++++++++++ apps/desktop-shell/src-tauri/tauri.conf.json | 4 +- apps/mobile-shell/App.tsx | 14 ++ apps/mobile-shell/package.json | 1 + apps/mobile-shell/scripts/check-config.mjs | 8 +- .../mobile-shell/src/mobileHostBridge.test.ts | 40 ++++++ apps/mobile-shell/src/mobileHostBridge.ts | 5 + .../src/mobileShellNetwork.test.ts | 84 ++++++++++++ apps/mobile-shell/src/mobileShellNetwork.ts | 40 ++++++ .../shared-memory/decision-log.md | 1 + ...ExpoReactNative与Tauri宿主壳方案-2026-06-17.md | 6 +- ...前端架构】宿主壳能力统一协议-2026-06-17.md | 1 + package-lock.json | 17 +++ package.json | 1 + .../shared/src/contracts/hostBridge.test.ts | 12 ++ packages/shared/src/contracts/hostBridge.ts | 45 +++++++ src/services/host-bridge/hostBridge.test.ts | 94 ++++++++++++++ src/services/host-bridge/hostBridge.ts | 57 ++++++++ 19 files changed, 551 insertions(+), 5 deletions(-) create mode 100644 apps/mobile-shell/src/mobileShellNetwork.test.ts create mode 100644 apps/mobile-shell/src/mobileShellNetwork.ts diff --git a/apps/desktop-shell/scripts/check-config.mjs b/apps/desktop-shell/scripts/check-config.mjs index 9cd69b40..f038edf6 100644 --- a/apps/desktop-shell/scripts/check-config.mjs +++ b/apps/desktop-shell/scripts/check-config.mjs @@ -135,6 +135,8 @@ const requiredMainSnippets = [ 'tauri_plugin_clipboard_manager::init()', '"appearance.getColorScheme"', '"app.lifecycle"', + '"network.status"', + '"network.statusChanged"', '"share.open"', '"share.setTarget"', '"navigation.openNativePage"', @@ -152,6 +154,8 @@ const requiredMainSnippets = [ 'window.theme()', 'WindowEvent::Focused', 'host_bridge_event_script', + 'resolve_desktop_network_status', + 'network.statusChanged', ]; for (const permission of requiredPermissions) { diff --git a/apps/desktop-shell/src-tauri/src/main.rs b/apps/desktop-shell/src-tauri/src/main.rs index 97f6b210..480a55cf 100644 --- a/apps/desktop-shell/src-tauri/src/main.rs +++ b/apps/desktop-shell/src-tauri/src/main.rs @@ -2,8 +2,10 @@ use base64::{engine::general_purpose::STANDARD as BASE64_STANDARD, Engine as _}; use serde::{Deserialize, Serialize}; use serde_json::{json, Value}; use std::fs; +use std::net::{TcpStream, ToSocketAddrs}; use std::path::PathBuf; use std::sync::Mutex; +use std::time::Duration; use tauri::Manager; use tauri::Theme; use tauri::Url; @@ -22,6 +24,7 @@ const EXPORT_IMAGE_MAX_BYTES: usize = 5 * 1024 * 1024; const EXPORT_FILE_NAME_FALLBACK: &str = "genarrative-export.txt"; const EXPORT_FILE_NAME_MAX_LENGTH: usize = 120; const BADGE_COUNT_MAX: i64 = 99999; +const DESKTOP_NETWORK_CHECK_TIMEOUT_MS: u64 = 1200; #[derive(Debug, Deserialize)] #[serde(rename_all = "camelCase")] @@ -90,6 +93,8 @@ fn capabilities() -> Vec<&'static str> { "app.openExternalUrl", "app.setTitle", "app.setBadgeCount", + "network.status", + "network.statusChanged", "clipboard.writeText", "file.exportText", "file.exportImage", @@ -441,6 +446,34 @@ fn emit_desktop_lifecycle_event( window.eval(script) } +fn desktop_network_status_payload(is_online: bool) -> Value { + json!({ + "isConnected": is_online, + "isInternetReachable": is_online, + "connectionType": if is_online { "unknown" } else { "none" }, + "nativeType": if is_online { "online" } else { "offline" }, + }) +} + +fn resolve_desktop_network_status() -> Value { + let timeout = Duration::from_millis(DESKTOP_NETWORK_CHECK_TIMEOUT_MS); + let is_reachable = ("app.genarrative.world", 443) + .to_socket_addrs() + .map(|addresses| { + addresses.into_iter().any(|address| { + TcpStream::connect_timeout(&address, timeout) + .map(|stream| { + drop(stream); + true + }) + .unwrap_or(false) + }) + }) + .unwrap_or(false); + + desktop_network_status_payload(is_reachable) +} + fn register_desktop_lifecycle_events(window: &WebviewWindow) { let lifecycle_window = window.clone(); window.on_window_event(move |event| { @@ -455,6 +488,56 @@ fn register_desktop_lifecycle_events(window: &WebviewWindow) { }); } +fn register_desktop_network_events(window: &WebviewWindow) -> tauri::Result<()> { + let online_script = host_bridge_event_script( + "network.statusChanged", + desktop_network_status_payload(true), + ) + .map_err(tauri::Error::Json)?; + let offline_script = host_bridge_event_script( + "network.statusChanged", + desktop_network_status_payload(false), + ) + .map_err(tauri::Error::Json)?; + let current_status_script = host_bridge_event_script( + "network.statusChanged", + json!({ + "isConnected": "__GENARRATIVE_DESKTOP_ONLINE__", + "isInternetReachable": "__GENARRATIVE_DESKTOP_ONLINE__", + "connectionType": "__GENARRATIVE_DESKTOP_CONNECTION_TYPE__", + "nativeType": "__GENARRATIVE_DESKTOP_NATIVE_TYPE__", + }), + ) + .map_err(tauri::Error::Json)? + .replace("\"__GENARRATIVE_DESKTOP_ONLINE__\"", "navigator.onLine") + .replace( + "\"__GENARRATIVE_DESKTOP_CONNECTION_TYPE__\"", + "(navigator.onLine ? 'unknown' : 'none')", + ) + .replace( + "\"__GENARRATIVE_DESKTOP_NATIVE_TYPE__\"", + "(navigator.onLine ? 'online' : 'offline')", + ); + + let script = format!( + "(() => {{ + if (window.__GENARRATIVE_DESKTOP_NETWORK_LISTENER_INSTALLED__) {{ + return true; + }} + window.__GENARRATIVE_DESKTOP_NETWORK_LISTENER_INSTALLED__ = true; + const emitOnline = () => {{ {} }}; + const emitOffline = () => {{ {} }}; + window.addEventListener('online', emitOnline); + window.addEventListener('offline', emitOffline); + {} + return true; + }})();", + online_script, offline_script, current_status_script + ); + + window.eval(script) +} + fn payload_string<'a>(value: &'a Value, field: &str) -> Option<&'a str> { value .get(field) @@ -730,6 +813,14 @@ async fn host_bridge_request( None => failed(request.id, "host_error", "main window not found"), } } + "network.status" => { + let network_status = + tauri::async_runtime::spawn_blocking(resolve_desktop_network_status).await; + match network_status { + Ok(status) => ok(request.id, status), + Err(error) => failed(request.id, "host_error", error.to_string()), + } + } "share.setTarget" => { let target = request .payload @@ -783,6 +874,7 @@ fn main() { tauri::WebviewWindowBuilder::from_config(app.handle(), &config)?.build()?; register_desktop_lifecycle_events(&window); let _ = emit_desktop_lifecycle_event(&window, "active", true, "created"); + let _ = register_desktop_network_events(&window); } Ok(()) }) @@ -822,6 +914,14 @@ mod tests { .as_array() .unwrap() .contains(&json!("app.lifecycle"))); + assert!(result["capabilities"] + .as_array() + .unwrap() + .contains(&json!("network.status"))); + assert!(result["capabilities"] + .as_array() + .unwrap() + .contains(&json!("network.statusChanged"))); assert!(result["capabilities"] .as_array() .unwrap() @@ -911,6 +1011,28 @@ mod tests { assert!(script.contains("\\\"focused\\\":true")); } + #[test] + fn desktop_network_status_payload_reports_reachability() { + assert_eq!( + desktop_network_status_payload(true), + json!({ + "isConnected": true, + "isInternetReachable": true, + "connectionType": "unknown", + "nativeType": "online", + }) + ); + assert_eq!( + desktop_network_status_payload(false), + json!({ + "isConnected": false, + "isInternetReachable": false, + "connectionType": "none", + "nativeType": "offline", + }) + ); + } + #[test] fn external_url_normalization_allows_only_safe_protocols() { assert_eq!( diff --git a/apps/desktop-shell/src-tauri/tauri.conf.json b/apps/desktop-shell/src-tauri/tauri.conf.json index 24da7588..466413aa 100644 --- a/apps/desktop-shell/src-tauri/tauri.conf.json +++ b/apps/desktop-shell/src-tauri/tauri.conf.json @@ -6,7 +6,7 @@ "build": { "beforeDevCommand": "npm --prefix ../.. run dev:web", "beforeBuildCommand": "npm --prefix ../.. run build:raw && npm run typecheck", - "devUrl": "http://127.0.0.1:3000/?clientRuntime=native_app&clientType=native_app&hostShell=tauri_desktop&hostPlatform=unknown&hostVersion=0.1.0&bridgeVersion=1&hostCapabilities=host.getRuntime,appearance.getColorScheme,app.lifecycle,share.open,share.setTarget,navigation.openNativePage,app.openExternalUrl,app.setTitle,app.setBadgeCount,clipboard.writeText,file.exportText,file.exportImage", + "devUrl": "http://127.0.0.1:3000/?clientRuntime=native_app&clientType=native_app&hostShell=tauri_desktop&hostPlatform=unknown&hostVersion=0.1.0&bridgeVersion=1&hostCapabilities=host.getRuntime,appearance.getColorScheme,app.lifecycle,share.open,share.setTarget,navigation.openNativePage,app.openExternalUrl,app.setTitle,app.setBadgeCount,network.status,network.statusChanged,clipboard.writeText,file.exportText,file.exportImage", "frontendDist": "../../../dist" }, "app": { @@ -14,7 +14,7 @@ { "create": false, "label": "main", - "url": "index.html?clientRuntime=native_app&clientType=native_app&hostShell=tauri_desktop&hostPlatform=unknown&hostVersion=0.1.0&bridgeVersion=1&hostCapabilities=host.getRuntime,appearance.getColorScheme,app.lifecycle,share.open,share.setTarget,navigation.openNativePage,app.openExternalUrl,app.setTitle,app.setBadgeCount,clipboard.writeText,file.exportText,file.exportImage", + "url": "index.html?clientRuntime=native_app&clientType=native_app&hostShell=tauri_desktop&hostPlatform=unknown&hostVersion=0.1.0&bridgeVersion=1&hostCapabilities=host.getRuntime,appearance.getColorScheme,app.lifecycle,share.open,share.setTarget,navigation.openNativePage,app.openExternalUrl,app.setTitle,app.setBadgeCount,network.status,network.statusChanged,clipboard.writeText,file.exportText,file.exportImage", "title": "Genarrative", "width": 1280, "height": 820, diff --git a/apps/mobile-shell/App.tsx b/apps/mobile-shell/App.tsx index 1ab9615c..21939332 100644 --- a/apps/mobile-shell/App.tsx +++ b/apps/mobile-shell/App.tsx @@ -23,6 +23,7 @@ import { resolveMobileShellExternalUrl, shouldOpenInMobileShellWebView, } from './src/mobileShellNavigation'; +import { subscribeMobileNetworkStatus } from './src/mobileShellNetwork'; import { buildMobileShellUrl } from './src/mobileShellUrl'; const defaultWebUrl = 'http://127.0.0.1:3000/'; @@ -127,6 +128,19 @@ export default function App() { return () => subscription.remove(); }, []); + useEffect(() => { + return subscribeMobileNetworkStatus((payload) => { + webViewRef.current?.injectJavaScript( + buildHostBridgeMessageScript({ + bridge: 'GenarrativeHostBridge', + version: 1, + event: 'network.statusChanged', + payload, + }), + ); + }); + }, []); + const handleMessage = (event: WebViewMessageEvent) => { void handleMobileHostBridgeMessage(event.nativeEvent.data, (response) => { webViewRef.current?.injectJavaScript( diff --git a/apps/mobile-shell/package.json b/apps/mobile-shell/package.json index 36b2f542..45a17d3b 100644 --- a/apps/mobile-shell/package.json +++ b/apps/mobile-shell/package.json @@ -18,6 +18,7 @@ "expo-file-system": "^56.0.8", "expo-haptics": "^56.0.3", "expo-linking": "^56.0.14", + "expo-network": "^56.0.5", "expo-sharing": "^56.0.18", "expo-status-bar": "^56.0.4", "react": "^19.0.0", diff --git a/apps/mobile-shell/scripts/check-config.mjs b/apps/mobile-shell/scripts/check-config.mjs index 3f50ac2a..26b426f0 100644 --- a/apps/mobile-shell/scripts/check-config.mjs +++ b/apps/mobile-shell/scripts/check-config.mjs @@ -119,6 +119,8 @@ for (const snippet of [ 'configureMobileHostBridgeNavigation', 'AppState.addEventListener', 'app.lifecycle', + 'network.statusChanged', + 'subscribeMobileNetworkStatus', 'navigation.canGoBack', 'buildHostBridgeMessageScript', ]) { @@ -127,7 +129,7 @@ for (const snippet of [ } } -for (const dependency of ['expo-file-system', 'expo-sharing']) { +for (const dependency of ['expo-file-system', 'expo-network', 'expo-sharing']) { if (!packageConfig.dependencies?.[dependency]) { throw new Error(`mobile shell package missing ${dependency}`); } @@ -136,6 +138,8 @@ for (const dependency of ['expo-file-system', 'expo-sharing']) { for (const snippet of [ 'file.exportText', 'file.exportImage', + 'network.status', + 'getMobileNetworkStatus', 'Sharing.shareAsync', 'normalizeHostBridgeExportFileName', 'base64Data', @@ -160,6 +164,8 @@ for (const capability of [ 'share.open', 'share.setTarget', 'app.lifecycle', + 'network.status', + 'network.statusChanged', 'navigation.openNativePage', 'navigation.canGoBack', 'app.openExternalUrl', diff --git a/apps/mobile-shell/src/mobileHostBridge.test.ts b/apps/mobile-shell/src/mobileHostBridge.test.ts index 6d13cb2f..d439137a 100644 --- a/apps/mobile-shell/src/mobileHostBridge.test.ts +++ b/apps/mobile-shell/src/mobileHostBridge.test.ts @@ -1,5 +1,6 @@ import * as Haptics from 'expo-haptics'; import * as Linking from 'expo-linking'; +import * as Network from 'expo-network'; import * as Sharing from 'expo-sharing'; import { Appearance, @@ -69,6 +70,20 @@ vi.mock('expo-linking', () => ({ openURL: vi.fn(), })); +vi.mock('expo-network', () => ({ + getNetworkStateAsync: vi.fn(async () => ({ + type: 'WIFI', + isConnected: true, + isInternetReachable: true, + })), + NetworkStateType: { + CELLULAR: 'CELLULAR', + ETHERNET: 'ETHERNET', + NONE: 'NONE', + WIFI: 'WIFI', + }, +})); + vi.mock('expo-sharing', () => ({ isAvailableAsync: vi.fn(async () => true), shareAsync: vi.fn(), @@ -142,6 +157,12 @@ afterEach(() => { vi.mocked(Appearance.getColorScheme).mockReturnValue('light'); vi.mocked(Haptics.impactAsync).mockReset(); vi.mocked(Linking.openURL).mockReset(); + vi.mocked(Network.getNetworkStateAsync).mockReset(); + vi.mocked(Network.getNetworkStateAsync).mockResolvedValue({ + type: Network.NetworkStateType.WIFI, + isConnected: true, + isInternetReachable: true, + }); vi.mocked(PushNotificationIOS.setApplicationIconBadgeNumber).mockReset(); setPlatformOS('ios'); vi.mocked(Sharing.isAvailableAsync).mockReset(); @@ -175,6 +196,8 @@ describe('handleMobileHostBridgeMessage', () => { 'appearance.getColorScheme', 'host.events', 'app.lifecycle', + 'network.status', + 'network.statusChanged', 'navigation.canGoBack', 'app.setBadgeCount', ]), @@ -288,6 +311,23 @@ describe('handleMobileHostBridgeMessage', () => { expect(Linking.openURL).not.toHaveBeenCalled(); }); + test('network.status 返回 Expo Network 真实状态', async () => { + vi.mocked(Network.getNetworkStateAsync).mockResolvedValue({ + type: Network.NetworkStateType.CELLULAR, + isConnected: true, + isInternetReachable: false, + }); + + const response = await send(request('network.status')); + + expect(expectOk(response).result).toEqual({ + isConnected: true, + isInternetReachable: false, + connectionType: 'cellular', + nativeType: 'CELLULAR', + }); + }); + test('haptics.impact 调起 Expo 触觉反馈', async () => { const response = await send( request('haptics.impact', { diff --git a/apps/mobile-shell/src/mobileHostBridge.ts b/apps/mobile-shell/src/mobileHostBridge.ts index 2c88cdea..b591040a 100644 --- a/apps/mobile-shell/src/mobileHostBridge.ts +++ b/apps/mobile-shell/src/mobileHostBridge.ts @@ -34,6 +34,7 @@ import { type ShareOpenPayload, } from '../../../packages/shared/src/contracts/hostBridge'; import { resolveMobileShellWebViewUrl } from './mobileShellNavigation'; +import { getMobileNetworkStatus } from './mobileShellNetwork'; const WEB_APP_ORIGIN = 'https://app.genarrative.world'; const EXPORT_TEXT_MAX_BYTES = 5 * 1024 * 1024; @@ -54,6 +55,8 @@ export const MOBILE_HOST_CAPABILITIES: HostBridgeCapability[] = [ 'navigation.openNativePage', 'navigation.canGoBack', 'app.openExternalUrl', + 'network.status', + 'network.statusChanged', 'clipboard.writeText', 'file.exportText', 'file.exportImage', @@ -437,6 +440,8 @@ async function handleRequest(request: HostBridgeRequest) { return ok(request, getColorScheme()); case 'app.openExternalUrl': return ok(request, await openExternalUrl(request.payload)); + case 'network.status': + return ok(request, await getMobileNetworkStatus()); case 'clipboard.writeText': return ok(request, await writeClipboard(request.payload)); case 'file.exportText': diff --git a/apps/mobile-shell/src/mobileShellNetwork.test.ts b/apps/mobile-shell/src/mobileShellNetwork.test.ts new file mode 100644 index 00000000..e8aab22e --- /dev/null +++ b/apps/mobile-shell/src/mobileShellNetwork.test.ts @@ -0,0 +1,84 @@ +import { describe, expect, test, vi } from 'vitest'; + +import { + getMobileNetworkStatus, + normalizeMobileNetworkStatus, + subscribeMobileNetworkStatus, +} from './mobileShellNetwork'; + +vi.mock('expo-network', () => ({ + addNetworkStateListener: vi.fn(), + getNetworkStateAsync: vi.fn(), + NetworkStateType: { + CELLULAR: 'CELLULAR', + ETHERNET: 'ETHERNET', + NONE: 'NONE', + WIFI: 'WIFI', + }, +})); + +describe('mobileShellNetwork', async () => { + const Network = await import('expo-network'); + + test('归一化 Expo Network 状态', () => { + expect( + normalizeMobileNetworkStatus({ + type: Network.NetworkStateType.WIFI, + isConnected: true, + isInternetReachable: true, + }), + ).toEqual({ + isConnected: true, + isInternetReachable: true, + connectionType: 'wifi', + nativeType: 'WIFI', + }); + + expect( + normalizeMobileNetworkStatus({ + type: Network.NetworkStateType.NONE, + }), + ).toEqual({ + isConnected: false, + isInternetReachable: null, + connectionType: 'none', + nativeType: 'NONE', + }); + }); + + test('查询和订阅真实 Expo Network API', async () => { + vi.mocked(Network.getNetworkStateAsync).mockResolvedValue({ + type: Network.NetworkStateType.CELLULAR, + isConnected: true, + isInternetReachable: false, + }); + const remove = vi.fn(); + vi.mocked(Network.addNetworkStateListener).mockReturnValue({ remove }); + const listener = vi.fn(); + + await expect(getMobileNetworkStatus()).resolves.toEqual({ + isConnected: true, + isInternetReachable: false, + connectionType: 'cellular', + nativeType: 'CELLULAR', + }); + + const unsubscribe = subscribeMobileNetworkStatus(listener); + const networkListener = vi.mocked(Network.addNetworkStateListener).mock + .calls[0]?.[0]; + networkListener?.({ + type: Network.NetworkStateType.ETHERNET, + isConnected: true, + isInternetReachable: true, + }); + unsubscribe(); + + expect(listener).toHaveBeenCalledWith({ + isConnected: true, + isInternetReachable: true, + connectionType: 'ethernet', + nativeType: 'ETHERNET', + }); + expect(remove).toHaveBeenCalledTimes(1); + }); +}); diff --git a/apps/mobile-shell/src/mobileShellNetwork.ts b/apps/mobile-shell/src/mobileShellNetwork.ts new file mode 100644 index 00000000..aedbe281 --- /dev/null +++ b/apps/mobile-shell/src/mobileShellNetwork.ts @@ -0,0 +1,40 @@ +import * as Network from 'expo-network'; + +import { + type NetworkStatusResult, + normalizeHostBridgeConnectionType, +} from '../../../packages/shared/src/contracts/hostBridge'; + +export function normalizeMobileNetworkStatus( + state: Network.NetworkState, +): NetworkStatusResult { + const nativeType = state.type; + const connectionType = normalizeHostBridgeConnectionType(nativeType); + + return { + isConnected: + typeof state.isConnected === 'boolean' + ? state.isConnected + : connectionType !== 'none' && connectionType !== 'unknown', + isInternetReachable: + typeof state.isInternetReachable === 'boolean' + ? state.isInternetReachable + : null, + connectionType, + ...(nativeType ? { nativeType } : {}), + }; +} + +export async function getMobileNetworkStatus() { + return normalizeMobileNetworkStatus(await Network.getNetworkStateAsync()); +} + +export function subscribeMobileNetworkStatus( + listener: (status: NetworkStatusResult) => void, +) { + const subscription = Network.addNetworkStateListener((state) => { + listener(normalizeMobileNetworkStatus(state)); + }); + + return () => subscription.remove(); +} diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 4af297cb..7bd21682 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -31,6 +31,7 @@ - 2026-06-18 应用角标能力：新增 `app.setBadgeCount` HostBridge capability，H5 只传 `0-99999` 整数并在宿主未声明时静默 fallback；Expo 壳只在 iOS 声明并通过 React Native `PushNotificationIOS` 设置应用图标角标，Android 不声明、不伪造成功；Tauri 壳通过主窗口 `set_badge_count` 设置任务栏角标，底层平台不支持时返回真实错误。 - 2026-06-18 宿主外观只读查询：新增 `appearance.getColorScheme` HostBridge capability，Expo 壳通过 React Native `Appearance.getColorScheme()` 读取系统配色，Tauri 壳通过主窗口 `theme()` 读取窗口主题；该能力只返回 `light` / `dark` / `unknown`，不设置 H5 主题、不覆盖系统主题，也不作为强制 UI 样式入口。 - 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。 - 影响范围：`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 a3cc24b7..50f5ea14 100644 --- a/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md +++ b/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md @@ -122,6 +122,8 @@ type HostBridgeEvent = { | `app.openExternalUrl` | 用系统浏览器打开外链 | 支持白名单协议 | 支持白名单协议 | | `app.setTitle` | 同步宿主窗口标题 | 不声明 | 支持 | | `app.setBadgeCount` | 设置应用 / 任务栏角标 | 仅 iOS 支持，Android 不声明 | 支持；平台底层不支持时返回错误 | +| `network.status` | 查询宿主网络状态 | 支持 Expo Network | 支持主站可达性短超时查询 | +| `network.statusChanged` | 通知 H5 网络状态变化 | 支持 Expo Network 事件 | 支持 WebView online / offline 事件 | | `clipboard.writeText` | 写剪贴板 | 支持 | 支持 | | `file.exportText` | 导出文本到用户选择的本地文件 | 支持系统分享 / 保存面板 | 支持系统保存对话框 | | `haptics.impact` | 轻量触感反馈 | 支持 | 不声明 | @@ -245,7 +247,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`、`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 游戏循环、音频和轮询做真实暂停 / 恢复判断；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`、`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 承接。 ### Phase 3：Tauri 桌面壳 MVP @@ -256,7 +258,7 @@ GameBridge 禁止： - 实现 runtime、openExternalUrl、clipboard、share fallback、窗口标题同步。 - 验证 macOS / Windows / Linux 至少一条本地 smoke。 -当前状态：已新增 `apps/desktop-shell/`，Tauri dev 直接加载本地主站 Vite，release 打包根 `dist` 主站资产。Rust 侧只把 `host_bridge_request` command 授给主窗口，`appearance.getColorScheme` 由 Rust 内部读取主窗口 `theme()` 并返回 `light` / `dark` / `unknown`，不设置或覆盖系统主题；`app.lifecycle` 由主窗口 focus / blur 事件注入 `active` / `inactive` 统一状态，不开放 Tauri event 插件给前端；`app.openExternalUrl` 由 Rust 内部通过 opener 插件执行且只允许 `http:`、`https:`、`mailto:`、`tel:` 外链协议，ICP备案号和资产调试原图等 H5 外链入口在 `native_app` 中优先通过该能力离开主窗口并交给系统浏览器；`navigation.openNativePage` 只接受 `https://app.genarrative.world` 同源 H5 route 并在主窗口内受控跳转，`clipboard.writeText` 由 Rust 内部通过 clipboard-manager 插件写入系统剪贴板并由 H5 复制服务优先调用，`app.setTitle` 通过 Tauri 主窗口 API 同步窗口标题并拒绝空标题 / 控制字符，`app.setBadgeCount` 通过主窗口 `set_badge_count` 设置任务栏角标，数量只接受 `0-99999` 整数且 `0` 表示清除；H5 主站会按当前平台阶段先更新 `document.title`，再通过 `app.setTitle` 把同一标题同步给 Tauri 窗口，Expo 移动壳不声明该能力时静默忽略；不把 opener、clipboard 或 dialog 插件命令直接暴露给前端。当前真实能力为 `host.getRuntime`、`appearance.getColorScheme`、`app.lifecycle`、`share.setTarget`、`share.open`、`navigation.openNativePage`、`app.openExternalUrl`、`app.setTitle`、`app.setBadgeCount`、`clipboard.writeText`、`file.exportText` 和 `file.exportImage`；H5 会在主 App 启动时通过真实 `host.getRuntime` 回读并缓存这些能力，即使入口 URL 缺少 `hostCapabilities`，也只按宿主真实回包开启能力入口；其中 `share.open` 会把直接传入的分享 payload 或 `share.setTarget` 缓存的作品目标整理成非空分享文本并写入系统剪贴板，返回 `copied_to_clipboard`，发布分享弹窗在桌面壳中也通过该能力提供“系统分享”动作；`file.exportText` 通过系统保存对话框让用户选择本地路径，清洗文件名、限制单次文本导出不超过 5 MiB，写入成功后只返回文件名和字节数，不把本机绝对路径暴露给 H5，用户取消返回 `cancelled`；`file.exportImage` 同样通过系统保存对话框写入 H5 生成的图片字节，只接受 `image/png` / `image/jpeg` / `image/webp` base64 数据，单次不超过 5 MiB，分享卡下载会优先走该能力，用户取消返回 `cancelled`。原生系统分享面板、登录和支付未接入真实插件 / 渠道前不声明支持，不返回 mock 成功。 +当前状态：已新增 `apps/desktop-shell/`，Tauri dev 直接加载本地主站 Vite，release 打包根 `dist` 主站资产。Rust 侧只把 `host_bridge_request` command 授给主窗口，`appearance.getColorScheme` 由 Rust 内部读取主窗口 `theme()` 并返回 `light` / `dark` / `unknown`，不设置或覆盖系统主题；`app.lifecycle` 由主窗口 focus / blur 事件注入 `active` / `inactive` 统一状态，不开放 Tauri event 插件给前端；`network.status` 由 Rust 对 `app.genarrative.world:443` 做短超时 TCP 可达性查询，`network.statusChanged` 由主 WebView 的 `online` / `offline` 事件注入，不开放任意网络探测给 H5；`app.openExternalUrl` 由 Rust 内部通过 opener 插件执行且只允许 `http:`、`https:`、`mailto:`、`tel:` 外链协议，ICP备案号和资产调试原图等 H5 外链入口在 `native_app` 中优先通过该能力离开主窗口并交给系统浏览器；`navigation.openNativePage` 只接受 `https://app.genarrative.world` 同源 H5 route 并在主窗口内受控跳转，`clipboard.writeText` 由 Rust 内部通过 clipboard-manager 插件写入系统剪贴板并由 H5 复制服务优先调用，`app.setTitle` 通过 Tauri 主窗口 API 同步窗口标题并拒绝空标题 / 控制字符，`app.setBadgeCount` 通过主窗口 `set_badge_count` 设置任务栏角标，数量只接受 `0-99999` 整数且 `0` 表示清除；H5 主站会按当前平台阶段先更新 `document.title`，再通过 `app.setTitle` 把同一标题同步给 Tauri 窗口，Expo 移动壳不声明该能力时静默忽略；不把 opener、clipboard 或 dialog 插件命令直接暴露给前端。当前真实能力为 `host.getRuntime`、`appearance.getColorScheme`、`app.lifecycle`、`network.status`、`network.statusChanged`、`share.setTarget`、`share.open`、`navigation.openNativePage`、`app.openExternalUrl`、`app.setTitle`、`app.setBadgeCount`、`clipboard.writeText`、`file.exportText` 和 `file.exportImage`；H5 会在主 App 启动时通过真实 `host.getRuntime` 回读并缓存这些能力，即使入口 URL 缺少 `hostCapabilities`，也只按宿主真实回包开启能力入口；其中 `share.open` 会把直接传入的分享 payload 或 `share.setTarget` 缓存的作品目标整理成非空分享文本并写入系统剪贴板，返回 `copied_to_clipboard`，发布分享弹窗在桌面壳中也通过该能力提供“系统分享”动作；`file.exportText` 通过系统保存对话框让用户选择本地路径，清洗文件名、限制单次文本导出不超过 5 MiB，写入成功后只返回文件名和字节数，不把本机绝对路径暴露给 H5，用户取消返回 `cancelled`；`file.exportImage` 同样通过系统保存对话框写入 H5 生成的图片字节，只接受 `image/png` / `image/jpeg` / `image/webp` base64 数据，单次不超过 5 MiB，分享卡下载会优先走该能力，用户取消返回 `cancelled`。原生系统分享面板、登录和支付未接入真实插件 / 渠道前不声明支持，不返回 mock 成功。 ### Phase 4：宿主能力扩展 diff --git a/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md b/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md index fc6029a3..b0b46ea7 100644 --- a/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md +++ b/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md @@ -42,6 +42,7 @@ AI H5 sandbox - `getHostRuntime()`：识别 `browser`、`wechat_mini_program`、`native_app`，并解析 `hostCapabilities` 能力声明；进入 `native_app` 后会通过真实 `host.getRuntime` 回读宿主 runtime 并缓存能力清单，未知能力会被丢弃。H5 业务只根据已声明或已回读的能力展示入口、发起宿主请求或走 fallback。 - `getHostAppearanceColorScheme()`：原生 App 宿主的受控外观查询入口。H5 可通过 `appearance.getColorScheme` 读取宿主当前 `light` / `dark` / `unknown` 配色模式；Expo 移动壳通过 React Native `Appearance.getColorScheme()` 读取系统偏好，Tauri 桌面壳通过主窗口 `theme()` 读取窗口主题。该能力只读，不改变 H5 主题，也不覆盖用户或系统偏好。 - `subscribeHostAppLifecycle()`：原生 App 宿主的受控生命周期事件入口。Expo 移动壳通过 React Native `AppState` 派发 `app.lifecycle`，Tauri 桌面壳通过主窗口 focus / blur 事件派发同名事件；H5 只依赖统一的 `active` / `inactive` / `background` 状态和 `focused` 布尔值，原生细分状态只放在 `nativeState` 用于排障，不作为业务分支依据。 +- `getHostNetworkStatus()` / `subscribeHostNetworkStatusChange()`：原生 App 宿主的受控网络状态入口。Expo 移动壳通过 `expo-network` 查询并订阅真实系统网络状态；Tauri 桌面壳通过短超时连接 `app.genarrative.world:443` 查询主站可达性，并在主 WebView 内监听 `online` / `offline` 注入变化事件。H5 只依赖统一的 `isConnected`、`isInternetReachable` 和连接类型，不直接读取平台私有网络 API。 - `requestHostLogin()`：微信小程序跳转原生登录页；浏览器返回 `false`，由 H5 登录弹窗承接。 - `requestHostPayment()`：微信小程序支付跳转原生支付页；其它渠道返回 `false`，继续走 H5 / Native 二维码。 - `setHostShareTarget()`：把当前公开作品分享目标同步给宿主。 diff --git a/package-lock.json b/package-lock.json index 7adcdf76..629b9a11 100644 --- a/package-lock.json +++ b/package-lock.json @@ -20,6 +20,7 @@ "expo-file-system": "^56.0.8", "expo-haptics": "^56.0.3", "expo-linking": "^56.0.14", + "expo-network": "^56.0.5", "expo-sharing": "^56.0.18", "expo-status-bar": "^56.0.4", "lucide-react": "^0.546.0", @@ -6444,6 +6445,16 @@ "react-native": "*" } }, + "node_modules/expo-network": { + "version": "56.0.5", + "resolved": "https://registry.npmjs.org/expo-network/-/expo-network-56.0.5.tgz", + "integrity": "sha512-zmuyO95jayDY9jyUfOAlNp9XXJrJaAOkBXXLy0TS/nh2kppj7CHirRPkQ/tf0rsxhIL3AEd9nsRTiPtNsGT9Lw==", + "license": "MIT", + "peerDependencies": { + "expo": "*", + "react": "*" + } + }, "node_modules/expo-server": { "version": "56.0.5", "resolved": "https://registry.npmjs.org/expo-server/-/expo-server-56.0.5.tgz", @@ -17320,6 +17331,12 @@ "integrity": "sha512-fHZcFpYO/o62GYa6fJyAQJZcAShzhoN0iMMDzbr7vD3ewET6e1vAlTonbEakN9F0VHEgBFJ4NREy87uwVcpCuA==", "requires": {} }, + "expo-network": { + "version": "56.0.5", + "resolved": "https://registry.npmjs.org/expo-network/-/expo-network-56.0.5.tgz", + "integrity": "sha512-zmuyO95jayDY9jyUfOAlNp9XXJrJaAOkBXXLy0TS/nh2kppj7CHirRPkQ/tf0rsxhIL3AEd9nsRTiPtNsGT9Lw==", + "requires": {} + }, "expo-server": { "version": "56.0.5", "resolved": "https://registry.npmjs.org/expo-server/-/expo-server-56.0.5.tgz", diff --git a/package.json b/package.json index a688674c..b5b3d066 100644 --- a/package.json +++ b/package.json @@ -90,6 +90,7 @@ "expo-file-system": "^56.0.8", "expo-haptics": "^56.0.3", "expo-linking": "^56.0.14", + "expo-network": "^56.0.5", "expo-sharing": "^56.0.18", "expo-status-bar": "^56.0.4", "lucide-react": "^0.546.0", diff --git a/packages/shared/src/contracts/hostBridge.test.ts b/packages/shared/src/contracts/hostBridge.test.ts index 893d6263..f7f12ba6 100644 --- a/packages/shared/src/contracts/hostBridge.test.ts +++ b/packages/shared/src/contracts/hostBridge.test.ts @@ -4,6 +4,7 @@ import { isHostBridgeCapability, normalizeHostBridgeBadgeCount, normalizeHostBridgeColorScheme, + normalizeHostBridgeConnectionType, normalizeHostBridgeExportFileName, normalizeHostBridgeExternalUrl, normalizeHostBridgeLifecycleState, @@ -51,6 +52,8 @@ describe('HostBridge shared contract helpers', () => { expect(isHostBridgeCapability('appearance.getColorScheme')).toBe(true); expect(isHostBridgeCapability('share.open')).toBe(true); expect(isHostBridgeCapability('app.lifecycle')).toBe(true); + expect(isHostBridgeCapability('network.status')).toBe(true); + expect(isHostBridgeCapability('network.statusChanged')).toBe(true); expect(isHostBridgeCapability('app.setBadgeCount')).toBe(true); expect(isHostBridgeCapability('navigation.canGoBack')).toBe(true); expect(isHostBridgeCapability('unknown.capability')).toBe(false); @@ -80,4 +83,13 @@ describe('HostBridge shared contract helpers', () => { expect(normalizeHostBridgeLifecycleState('extension')).toBe('inactive'); expect(normalizeHostBridgeLifecycleState(null)).toBe('inactive'); }); + + test('归一化宿主网络连接类型', () => { + expect(normalizeHostBridgeConnectionType('WIFI')).toBe('wifi'); + expect(normalizeHostBridgeConnectionType('CELLULAR')).toBe('cellular'); + expect(normalizeHostBridgeConnectionType('ETHERNET')).toBe('ethernet'); + expect(normalizeHostBridgeConnectionType('NONE')).toBe('none'); + expect(normalizeHostBridgeConnectionType('satellite')).toBe('unknown'); + expect(normalizeHostBridgeConnectionType(null)).toBe('unknown'); + }); }); diff --git a/packages/shared/src/contracts/hostBridge.ts b/packages/shared/src/contracts/hostBridge.ts index c87f6135..60a072a7 100644 --- a/packages/shared/src/contracts/hostBridge.ts +++ b/packages/shared/src/contracts/hostBridge.ts @@ -24,6 +24,7 @@ export const HOST_BRIDGE_METHODS = [ 'app.openExternalUrl', 'app.setTitle', 'app.setBadgeCount', + 'network.status', 'clipboard.writeText', 'file.exportText', 'file.exportImage', @@ -36,6 +37,7 @@ export const HOST_BRIDGE_CAPABILITIES = [ ...HOST_BRIDGE_METHODS, 'host.events', 'app.lifecycle', + 'network.statusChanged', 'navigation.canGoBack', ] as const; @@ -120,6 +122,49 @@ export function normalizeHostBridgeLifecycleState( : 'inactive'; } +export type HostNetworkConnectionType = + | 'none' + | 'unknown' + | 'cellular' + | 'wifi' + | 'ethernet' + | 'bluetooth' + | 'vpn' + | 'other'; + +export type NetworkStatusResult = { + isConnected: boolean; + isInternetReachable: boolean | null; + connectionType: HostNetworkConnectionType; + nativeType?: string; +}; + +export function normalizeHostBridgeConnectionType( + rawConnectionType: unknown, +): HostNetworkConnectionType { + if (typeof rawConnectionType !== 'string') { + return 'unknown'; + } + + const normalizedType = rawConnectionType.toLowerCase(); + if ( + normalizedType === 'none' || + normalizedType === 'cellular' || + normalizedType === 'wifi' || + normalizedType === 'ethernet' || + normalizedType === 'bluetooth' || + normalizedType === 'vpn' + ) { + return normalizedType; + } + + if (normalizedType === 'other') { + return 'other'; + } + + return 'unknown'; +} + export type HostAppearanceColorScheme = 'light' | 'dark' | 'unknown'; export type AppearanceColorSchemeResult = { diff --git a/src/services/host-bridge/hostBridge.test.ts b/src/services/host-bridge/hostBridge.test.ts index 03ee90b7..e71b6609 100644 --- a/src/services/host-bridge/hostBridge.test.ts +++ b/src/services/host-bridge/hostBridge.test.ts @@ -9,6 +9,7 @@ import { exportHostImageFile, exportHostTextFile, getHostAppearanceColorScheme, + getHostNetworkStatus, getHostRuntime, getNativeAppHostRuntime, isWechatMiniProgramWebViewRuntime, @@ -30,6 +31,7 @@ import { setHostAppTitle, setHostShareTarget, subscribeHostAppLifecycle, + subscribeHostNetworkStatusChange, subscribeHostRuntimeChange, writeHostClipboardText, } from './hostBridge'; @@ -217,6 +219,78 @@ describe('hostBridge', () => { expect(listener).not.toHaveBeenCalled(); }); + test('查询并订阅原生 App 网络状态', async () => { + const invoke = vi.fn( + async (_command: string, args?: Record) => { + const request = (args as { request: { id: string; method: string } }) + .request; + return { + bridge: 'GenarrativeHostBridge', + version: 1, + id: request.id, + ok: true, + result: { + isConnected: true, + isInternetReachable: false, + connectionType: 'WIFI', + nativeType: 'WIFI', + }, + }; + }, + ); + const listener = vi.fn(); + window.history.replaceState( + null, + '', + nativeAppPath(['network.status', 'network.statusChanged']), + ); + window.ReactNativeWebView = { + postMessage: vi.fn(), + }; + window.__TAURI__ = { + core: { + invoke: asTauriInvoke(invoke), + }, + }; + + await expect(getHostNetworkStatus()).resolves.toEqual({ + isConnected: true, + isInternetReachable: false, + connectionType: 'wifi', + nativeType: 'WIFI', + }); + + const unsubscribe = subscribeHostNetworkStatusChange(listener); + window.dispatchEvent( + new MessageEvent('message', { + data: JSON.stringify({ + bridge: 'GenarrativeHostBridge', + version: 1, + event: 'network.statusChanged', + payload: { + isConnected: false, + isInternetReachable: false, + connectionType: 'NONE', + nativeType: 'NONE', + }, + }), + }), + ); + unsubscribe(); + + expect(listener).toHaveBeenCalledWith({ + isConnected: false, + isInternetReachable: false, + connectionType: 'none', + nativeType: 'NONE', + }); + expect(invoke).toHaveBeenCalledWith('host_bridge_request', { + request: expect.objectContaining({ + method: 'network.status', + }), + }); + }); + test('从真实宿主 runtime 回读能力并通知订阅者', async () => { const listener = vi.fn(); const unsubscribe = subscribeHostRuntimeChange(listener); @@ -510,6 +584,13 @@ describe('hostBridge', () => { } : request.method === 'appearance.getColorScheme' ? { colorScheme: 'dark' } + : request.method === 'network.status' + ? { + isConnected: true, + isInternetReachable: true, + connectionType: 'ethernet', + nativeType: 'online', + } : true, }; }); @@ -527,6 +608,7 @@ describe('hostBridge', () => { 'app.openExternalUrl', 'app.setTitle', 'app.setBadgeCount', + 'network.status', 'share.open', 'file.exportImage', ]), @@ -565,6 +647,12 @@ describe('hostBridge', () => { true, ); await expect(setHostAppBadgeCount({ count: 7 })).resolves.toBe(true); + await expect(getHostNetworkStatus()).resolves.toEqual({ + isConnected: true, + isInternetReachable: true, + connectionType: 'ethernet', + nativeType: 'online', + }); await expect( openHostShare({ title: '暖灯猫街', @@ -645,6 +733,11 @@ describe('hostBridge', () => { }, }), }); + expect(invoke).toHaveBeenCalledWith('host_bridge_request', { + request: expect.objectContaining({ + method: 'network.status', + }), + }); expect(invoke).toHaveBeenCalledWith('host_bridge_request', { request: expect.objectContaining({ method: 'share.open', @@ -716,6 +809,7 @@ describe('hostBridge', () => { await expect(setHostAppBadgeCount({ count: 1 })).resolves.toBe(false); await expect(setHostAppBadgeCount({ count: -1 })).resolves.toBe(false); await expect(setHostAppBadgeCount({ count: 1.5 })).resolves.toBe(false); + await expect(getHostNetworkStatus()).resolves.toBe(false); await expect( openHostShare({ title: '暖灯猫街', diff --git a/src/services/host-bridge/hostBridge.ts b/src/services/host-bridge/hostBridge.ts index 0102e9df..2e57920f 100644 --- a/src/services/host-bridge/hostBridge.ts +++ b/src/services/host-bridge/hostBridge.ts @@ -9,6 +9,7 @@ import type { HostBridgeCapability, HostBridgeMethod, HostBridgeRuntimeResult, + NetworkStatusResult, OpenExternalUrlPayload, SetBadgeCountPayload, ShareOpenPayload, @@ -17,6 +18,7 @@ import { isHostBridgeCapability, normalizeHostBridgeBadgeCount, normalizeHostBridgeColorScheme, + normalizeHostBridgeConnectionType, normalizeHostBridgeExternalUrl, normalizeHostBridgeLifecycleState, } from '../../../packages/shared/src/contracts/hostBridge'; @@ -104,6 +106,8 @@ export type HostAppearanceColorSchemeSnapshot = AppearanceColorSchemeResult; export type HostAppLifecycleSnapshot = AppLifecycleEventPayload; +export type HostNetworkStatusSnapshot = NetworkStatusResult; + const HOST_RUNTIME_REFRESH_TIMEOUT_MS = 3000; let cachedNativeHostRuntime: HostBridgeRuntimeResult | null = null; @@ -815,3 +819,56 @@ export function subscribeHostAppLifecycle( }, ); } + +function normalizeHostNetworkStatus( + payload: NetworkStatusResult | null | undefined, +): HostNetworkStatusSnapshot { + const connectionType = normalizeHostBridgeConnectionType( + payload?.connectionType ?? payload?.nativeType, + ); + const isConnected = + typeof payload?.isConnected === 'boolean' + ? payload.isConnected + : connectionType !== 'none' && connectionType !== 'unknown'; + + return { + isConnected, + isInternetReachable: + typeof payload?.isInternetReachable === 'boolean' + ? payload.isInternetReachable + : null, + connectionType, + ...(typeof payload?.nativeType === 'string' + ? { nativeType: payload.nativeType } + : {}), + }; +} + +export async function getHostNetworkStatus() { + if (!canUseNativeHostCapability('network.status')) { + return false; + } + + try { + return normalizeHostNetworkStatus( + await requestNativeAppHostBridge('network.status'), + ); + } catch { + return false; + } +} + +export function subscribeHostNetworkStatusChange( + listener: (payload: HostNetworkStatusSnapshot) => void, +) { + if (!canUseNativeHostCapability('network.statusChanged')) { + return () => undefined; + } + + return subscribeNativeAppHostBridgeEvent( + 'network.statusChanged', + (payload) => { + listener(normalizeHostNetworkStatus(payload)); + }, + ); +}