diff --git a/apps/desktop-shell/scripts/check-config.mjs b/apps/desktop-shell/scripts/check-config.mjs index a891b4fa..d60dbbd5 100644 --- a/apps/desktop-shell/scripts/check-config.mjs +++ b/apps/desktop-shell/scripts/check-config.mjs @@ -133,6 +133,7 @@ const requiredPermissions = [ const requiredBuildCommands = ['host_bridge_request']; const requiredMainSnippets = [ 'tauri_plugin_clipboard_manager::init()', + '"appearance.getColorScheme"', '"share.open"', '"share.setTarget"', '"navigation.openNativePage"', @@ -147,6 +148,7 @@ const requiredMainSnippets = [ 'BASE64_STANDARD.decode', 'set_title', 'set_badge_count', + 'window.theme()', ]; 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 979d9310..7d23aa43 100644 --- a/apps/desktop-shell/src-tauri/src/main.rs +++ b/apps/desktop-shell/src-tauri/src/main.rs @@ -5,6 +5,7 @@ use std::fs; use std::path::PathBuf; use std::sync::Mutex; use tauri::Manager; +use tauri::Theme; use tauri::Url; use tauri_plugin_clipboard_manager::ClipboardExt; use tauri_plugin_dialog::DialogExt; @@ -79,6 +80,7 @@ fn desktop_platform() -> &'static str { fn capabilities() -> Vec<&'static str> { vec![ "host.getRuntime", + "appearance.getColorScheme", "share.open", "share.setTarget", "navigation.openNativePage", @@ -116,6 +118,14 @@ fn failed(id: String, code: &'static str, message: impl Into) -> HostBri } } +fn color_scheme_from_theme(theme: Theme) -> &'static str { + match theme { + Theme::Light => "light", + Theme::Dark => "dark", + _ => "unknown", + } +} + fn validate_request(request: &HostBridgeRequest) -> Option { if request.bridge != HOST_BRIDGE_PROTOCOL || request.version != HOST_BRIDGE_VERSION { return Some(failed( @@ -520,6 +530,18 @@ async fn host_bridge_request( Err(error) => failed(request.id, "host_error", error.to_string()), } } + "appearance.getColorScheme" => match app.get_webview_window("main") { + Some(window) => match window.theme() { + Ok(theme) => ok( + request.id, + json!({ + "colorScheme": color_scheme_from_theme(theme) + }), + ), + Err(error) => failed(request.id, "host_error", error.to_string()), + }, + None => failed(request.id, "host_error", "main window not found"), + }, "navigation.openNativePage" => { let url = match required_string_payload(&request, "url") .ok() @@ -737,6 +759,10 @@ mod tests { assert_eq!(result["shell"], "tauri_desktop"); assert_eq!(result["bridgeVersion"], HOST_BRIDGE_VERSION); assert_eq!(result["capabilities"], json!(capabilities())); + assert!(result["capabilities"] + .as_array() + .unwrap() + .contains(&json!("appearance.getColorScheme"))); assert!(result["capabilities"] .as_array() .unwrap() @@ -801,6 +827,12 @@ mod tests { assert_eq!(error.message, "text is required"); } + #[test] + fn color_scheme_maps_window_theme() { + assert_eq!(color_scheme_from_theme(Theme::Light), "light"); + assert_eq!(color_scheme_from_theme(Theme::Dark), "dark"); + } + #[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 faa5ae81..79475fe8 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,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,share.open,share.setTarget,navigation.openNativePage,app.openExternalUrl,app.setTitle,app.setBadgeCount,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,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,share.open,share.setTarget,navigation.openNativePage,app.openExternalUrl,app.setTitle,app.setBadgeCount,clipboard.writeText,file.exportText,file.exportImage", "title": "Genarrative", "width": 1280, "height": 820, diff --git a/apps/mobile-shell/scripts/check-config.mjs b/apps/mobile-shell/scripts/check-config.mjs index 9bda30d5..0b147c3f 100644 --- a/apps/mobile-shell/scripts/check-config.mjs +++ b/apps/mobile-shell/scripts/check-config.mjs @@ -153,6 +153,7 @@ if (!appSource.includes('capabilities: resolveMobileHostCapabilities()')) { for (const capability of [ 'host.getRuntime', + 'appearance.getColorScheme', 'share.open', 'share.setTarget', 'navigation.openNativePage', @@ -175,3 +176,7 @@ if (!iosMobileCapabilitySet.has('app.setBadgeCount')) { if (mobileCapabilitySet.has('app.setBadgeCount')) { throw new Error('Android mobile shell base capabilities must not include app.setBadgeCount'); } + +if (!bridgeSource.includes('Appearance.getColorScheme()')) { + throw new Error('mobile shell HostBridge must read the native color scheme'); +} diff --git a/apps/mobile-shell/src/mobileHostBridge.test.ts b/apps/mobile-shell/src/mobileHostBridge.test.ts index 5b086c1d..28b6770d 100644 --- a/apps/mobile-shell/src/mobileHostBridge.test.ts +++ b/apps/mobile-shell/src/mobileHostBridge.test.ts @@ -1,7 +1,12 @@ import * as Haptics from 'expo-haptics'; import * as Linking from 'expo-linking'; import * as Sharing from 'expo-sharing'; -import { Platform, PushNotificationIOS, Share } from 'react-native'; +import { + Appearance, + Platform, + PushNotificationIOS, + Share, +} from 'react-native'; import { afterEach, describe, expect, test, vi } from 'vitest'; import { @@ -70,6 +75,9 @@ vi.mock('expo-sharing', () => ({ })); vi.mock('react-native', () => ({ + Appearance: { + getColorScheme: vi.fn(() => 'light'), + }, Platform: { OS: 'ios', }, @@ -130,6 +138,8 @@ function setPlatformOS(os: 'ios' | 'android') { } afterEach(() => { + vi.mocked(Appearance.getColorScheme).mockReset(); + vi.mocked(Appearance.getColorScheme).mockReturnValue('light'); vi.mocked(Haptics.impactAsync).mockReset(); vi.mocked(Linking.openURL).mockReset(); vi.mocked(PushNotificationIOS.setApplicationIconBadgeNumber).mockReset(); @@ -162,6 +172,7 @@ describe('handleMobileHostBridgeMessage', () => { (okResponse.result as { capabilities: string[] }).capabilities, ).toEqual( expect.arrayContaining([ + 'appearance.getColorScheme', 'host.events', 'navigation.canGoBack', 'app.setBadgeCount', @@ -184,6 +195,26 @@ describe('handleMobileHostBridgeMessage', () => { ).not.toContain('app.setBadgeCount'); }); + test('appearance.getColorScheme 返回系统配色模式', async () => { + vi.mocked(Appearance.getColorScheme).mockReturnValue('dark'); + + const response = await send(request('appearance.getColorScheme')); + + expect(expectOk(response).result).toEqual({ + colorScheme: 'dark', + }); + }); + + test('appearance.getColorScheme 归一化未知系统配色', async () => { + vi.mocked(Appearance.getColorScheme).mockReturnValue('unspecified'); + + const response = await send(request('appearance.getColorScheme')); + + expect(expectOk(response).result).toEqual({ + colorScheme: 'unknown', + }); + }); + test('navigation.openNativePage 把同源路径切到移动壳 WebView', async () => { const openWebViewUrl = vi.fn(); configureMobileHostBridgeNavigation({ diff --git a/apps/mobile-shell/src/mobileHostBridge.ts b/apps/mobile-shell/src/mobileHostBridge.ts index 8a614de8..7554db36 100644 --- a/apps/mobile-shell/src/mobileHostBridge.ts +++ b/apps/mobile-shell/src/mobileHostBridge.ts @@ -3,7 +3,12 @@ import { File, Paths } from 'expo-file-system'; import * as Haptics from 'expo-haptics'; import * as Linking from 'expo-linking'; import * as Sharing from 'expo-sharing'; -import { Platform, PushNotificationIOS, Share } from 'react-native'; +import { + Appearance, + Platform, + PushNotificationIOS, + Share, +} from 'react-native'; import { type ClipboardWriteTextPayload, @@ -21,6 +26,7 @@ import { type HostBridgeResponse, type NavigateNativePagePayload, normalizeHostBridgeBadgeCount, + normalizeHostBridgeColorScheme, normalizeHostBridgeExportFileName, normalizeHostBridgeExternalUrl, type OpenExternalUrlPayload, @@ -40,6 +46,7 @@ const EXPORT_IMAGE_MIME_TYPES = new Set([ export const MOBILE_HOST_CAPABILITIES: HostBridgeCapability[] = [ 'host.getRuntime', + 'appearance.getColorScheme', 'host.events', 'share.open', 'share.setTarget', @@ -309,6 +316,12 @@ function setBadgeCount(payload: unknown) { return true; } +function getColorScheme() { + return { + colorScheme: normalizeHostBridgeColorScheme(Appearance.getColorScheme()), + }; +} + function stringField(value: unknown, field: string) { if (!value || typeof value !== 'object') { return undefined; @@ -419,6 +432,8 @@ async function handleRequest(request: HostBridgeRequest) { bridgeVersion: HOST_BRIDGE_VERSION, capabilities: resolveMobileHostCapabilities(), }); + case 'appearance.getColorScheme': + return ok(request, getColorScheme()); case 'app.openExternalUrl': return ok(request, await openExternalUrl(request.payload)); case 'clipboard.writeText': diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index cee0dd78..0d75b38a 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -29,6 +29,7 @@ - 2026-06-18 原生壳统一验收门禁:根级 `npm run check:native-shells` 统一执行 H5 HostBridge 关键测试、Expo 壳 typecheck / test 和 Tauri 壳 typecheck / cargo test;根级 `npm run check` 会在 lint、主站测试、构建和内容检查后继续执行该门禁,避免 HostBridge 与两端壳验收散落成容易漏跑的单项命令。 - 2026-06-18 分享卡图片导出:新增 `file.exportImage` HostBridge capability,H5 分享卡下载在 native app 中优先把 canvas 生成的 base64 图片交给宿主导出;Expo 壳写缓存图片后交给系统分享 / 保存面板,Tauri 壳通过系统保存对话框写入图片字节。该能力只接受 `image/png` / `image/jpeg` / `image/webp`、单次 5 MiB 内图片数据,成功只返回文件名和字节数,不暴露本机绝对路径;宿主未声明时保留浏览器下载。 - 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 样式入口。 - 影响范围:`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 4e3eb4f7..402a2cf3 100644 --- a/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md +++ b/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md @@ -111,6 +111,7 @@ type HostBridgeEvent = { | method | 用途 | Expo 壳 | Tauri 壳 | | --- | --- | --- | --- | | `host.getRuntime` | 返回宿主、平台、版本和能力清单 | 支持 | 支持 | +| `appearance.getColorScheme` | 读取宿主当前配色模式 | 支持系统 Appearance 读取 | 支持窗口 theme 读取 | | `auth.requestLogin` | 打开宿主登录或账号绑定流程 | 支持 | 可先返回不支持 | | `payment.request` | 发起宿主支付 | 依平台策略接入 | 桌面二维码 / 外部浏览器 | | `share.setTarget` | 同步当前作品分享目标 | 支持 | 支持 | @@ -243,7 +244,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`、`host.events`、`share.open`、`share.setTarget`、`navigation.openNativePage`、`navigation.canGoBack`、`app.openExternalUrl`、`clipboard.writeText`、`file.exportText`、`file.exportImage`、`haptics.impact` 和 Android 返回键回退;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`、`share.open`、`share.setTarget`、`navigation.openNativePage`、`navigation.canGoBack`、`app.openExternalUrl`、`clipboard.writeText`、`file.exportText`、`file.exportImage`、`haptics.impact` 和 Android 返回键回退;其中 `appearance.getColorScheme` 只读系统配色偏好,不强改 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 @@ -254,7 +255,7 @@ GameBridge 禁止: - 实现 runtime、openExternalUrl、clipboard、share fallback、窗口标题同步。 - 验证 macOS / Windows / Linux 至少一条本地 smoke。 -当前状态:已新增 `apps/desktop-shell/`,Tauri dev 直接加载本地主站 Vite,release 打包根 `dist` 主站资产。Rust 侧只把 `host_bridge_request` command 授给主窗口,`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`、`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.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`、`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 020dfc9a..2e416ba7 100644 --- a/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md +++ b/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md @@ -40,6 +40,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 主题,也不覆盖用户或系统偏好。 - `requestHostLogin()`:微信小程序跳转原生登录页;浏览器返回 `false`,由 H5 登录弹窗承接。 - `requestHostPayment()`:微信小程序支付跳转原生支付页;其它渠道返回 `false`,继续走 H5 / Native 二维码。 - `setHostShareTarget()`:把当前公开作品分享目标同步给宿主。 diff --git a/packages/shared/src/contracts/hostBridge.test.ts b/packages/shared/src/contracts/hostBridge.test.ts index 89069f14..fdbfd78c 100644 --- a/packages/shared/src/contracts/hostBridge.test.ts +++ b/packages/shared/src/contracts/hostBridge.test.ts @@ -3,6 +3,7 @@ import { describe, expect, test } from 'vitest'; import { isHostBridgeCapability, normalizeHostBridgeBadgeCount, + normalizeHostBridgeColorScheme, normalizeHostBridgeExportFileName, normalizeHostBridgeExternalUrl, } from './hostBridge'; @@ -46,6 +47,7 @@ describe('HostBridge shared contract helpers', () => { }); test('识别 HostBridge 能力白名单', () => { + expect(isHostBridgeCapability('appearance.getColorScheme')).toBe(true); expect(isHostBridgeCapability('share.open')).toBe(true); expect(isHostBridgeCapability('app.setBadgeCount')).toBe(true); expect(isHostBridgeCapability('navigation.canGoBack')).toBe(true); @@ -62,4 +64,11 @@ describe('HostBridge shared contract helpers', () => { expect(normalizeHostBridgeBadgeCount(100000)).toBeNull(); expect(normalizeHostBridgeBadgeCount('1')).toBeNull(); }); + + test('归一化宿主配色模式', () => { + expect(normalizeHostBridgeColorScheme('light')).toBe('light'); + expect(normalizeHostBridgeColorScheme('dark')).toBe('dark'); + expect(normalizeHostBridgeColorScheme('unspecified')).toBe('unknown'); + expect(normalizeHostBridgeColorScheme(null)).toBe('unknown'); + }); }); diff --git a/packages/shared/src/contracts/hostBridge.ts b/packages/shared/src/contracts/hostBridge.ts index 780ef57c..b6df822f 100644 --- a/packages/shared/src/contracts/hostBridge.ts +++ b/packages/shared/src/contracts/hostBridge.ts @@ -15,6 +15,7 @@ export type NativeHostPlatform = export const HOST_BRIDGE_METHODS = [ 'host.getRuntime', + 'appearance.getColorScheme', 'auth.requestLogin', 'payment.request', 'share.setTarget', @@ -102,6 +103,20 @@ export type NavigationCanGoBackEventPayload = { canGoBack: boolean; }; +export type HostAppearanceColorScheme = 'light' | 'dark' | 'unknown'; + +export type AppearanceColorSchemeResult = { + colorScheme: HostAppearanceColorScheme; +}; + +export function normalizeHostBridgeColorScheme( + rawColorScheme: unknown, +): HostAppearanceColorScheme { + return rawColorScheme === 'light' || rawColorScheme === 'dark' + ? rawColorScheme + : 'unknown'; +} + export type NavigateNativePagePayload = { url: string; }; diff --git a/src/services/host-bridge/hostBridge.test.ts b/src/services/host-bridge/hostBridge.test.ts index fc5557a0..57bf5711 100644 --- a/src/services/host-bridge/hostBridge.test.ts +++ b/src/services/host-bridge/hostBridge.test.ts @@ -8,6 +8,7 @@ import { canUseNativeHostCapability, exportHostImageFile, exportHostTextFile, + getHostAppearanceColorScheme, getHostRuntime, getNativeAppHostRuntime, isWechatMiniProgramWebViewRuntime, @@ -421,15 +422,18 @@ describe('hostBridge', () => { version: 1, id: request.id, ok: true, - result: request.method === 'host.getRuntime' - ? { - shell: 'tauri_desktop', - platform: 'linux', - hostVersion: '0.1.0', - bridgeVersion: 1, - capabilities: ['host.getRuntime'], - } - : true, + result: + request.method === 'host.getRuntime' + ? { + shell: 'tauri_desktop', + platform: 'linux', + hostVersion: '0.1.0', + bridgeVersion: 1, + capabilities: ['host.getRuntime'], + } + : request.method === 'appearance.getColorScheme' + ? { colorScheme: 'dark' } + : true, }; }); window.history.replaceState( @@ -437,6 +441,7 @@ describe('hostBridge', () => { '', nativeAppPath([ 'host.getRuntime', + 'appearance.getColorScheme', 'navigation.openNativePage', 'auth.requestLogin', 'payment.request', @@ -456,6 +461,9 @@ describe('hostBridge', () => { }; await expect(navigateHostNativePage('/settings')).resolves.toBe(true); + await expect(getHostAppearanceColorScheme()).resolves.toEqual({ + colorScheme: 'dark', + }); await expect(requestHostLogin()).resolves.toBe(true); await expect( requestHostPayment({ @@ -495,6 +503,11 @@ describe('hostBridge', () => { }), ).resolves.toBe(true); + expect(invoke).toHaveBeenCalledWith('host_bridge_request', { + request: expect.objectContaining({ + method: 'appearance.getColorScheme', + }), + }); expect(invoke).toHaveBeenCalledWith('host_bridge_request', { request: expect.objectContaining({ method: 'navigation.openNativePage', @@ -599,6 +612,7 @@ describe('hostBridge', () => { }; await expect(navigateHostNativePage('/settings')).resolves.toBe(false); + await expect(getHostAppearanceColorScheme()).resolves.toBe(false); await expect(requestHostLogin()).resolves.toBe(false); await expect( requestHostPayment({ @@ -642,6 +656,7 @@ describe('hostBridge', () => { }); test('普通浏览器不处理宿主文件导出', async () => { + await expect(getHostAppearanceColorScheme()).resolves.toBe(false); await expect( exportHostTextFile({ fileName: '作品记录.txt', diff --git a/src/services/host-bridge/hostBridge.ts b/src/services/host-bridge/hostBridge.ts index a079774e..eda608dc 100644 --- a/src/services/host-bridge/hostBridge.ts +++ b/src/services/host-bridge/hostBridge.ts @@ -1,4 +1,5 @@ import type { + AppearanceColorSchemeResult, FileExportImagePayload, FileExportImageResult, FileExportTextPayload, @@ -14,6 +15,7 @@ import type { import { isHostBridgeCapability, normalizeHostBridgeBadgeCount, + normalizeHostBridgeColorScheme, normalizeHostBridgeExternalUrl, } from '../../../packages/shared/src/contracts/hostBridge'; import type { @@ -95,6 +97,8 @@ export type HostShareOpenRequest = ShareOpenPayload; export type HostExternalUrlRequest = OpenExternalUrlPayload; +export type HostAppearanceColorSchemeSnapshot = AppearanceColorSchemeResult; + const HOST_RUNTIME_REFRESH_TIMEOUT_MS = 3000; let cachedNativeHostRuntime: HostBridgeRuntimeResult | null = null; @@ -764,3 +768,21 @@ export async function setHostAppBadgeCount({ return false; } } + +export async function getHostAppearanceColorScheme() { + if (!canUseNativeHostCapability('appearance.getColorScheme')) { + return false; + } + + try { + const result = + await requestNativeAppHostBridge( + 'appearance.getColorScheme', + ); + return { + colorScheme: normalizeHostBridgeColorScheme(result?.colorScheme), + } satisfies HostAppearanceColorSchemeSnapshot; + } catch { + return false; + } +}