M2(容器+能力骨架+启动接线): CapabilityProvider/Registrar/AppModule + BridgeGameContainer 完整化 + Splash 接编排

T-M2-13 能力插件框架骨架：CapabilityProvider/CapabilityContext 接口、CapabilityRegistrar(批量注册+生命周期转发)、组装根 AppModule.buildCapabilities()(唯一知道全部能力处)、EchoSampleProvider 样板 T-M2-10 BridgeGameContainer 完整化：经 Registrar 注册能力(替换内联 handler)、首次进度 100% 推 appservice/setPostUrl、加载 params.entryUrl(回退 test_echo)、前后台 EventBus 联动、aboutToDisappear 全量清理；getContext→getHostContext 去弃用 SplashPage：进入即跑 StartupOrchestrator，完成 replace 进大厅、showmessage 阻断弹公告、进度条内置测试大厅 rawfile/gamehall_builtin.zip（gamehall/index.html+data/test.json+version.xml，正斜杠标准 zip），作 M2 端到端 + V2(file:// XHR) 离线验证页；真实大厅由远程 zip 在生产下发 devecocli build 通过。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-25 18:36:59 +08:00
parent d2da223c8d
commit 2b0bd1f392
8 changed files with 254 additions and 39 deletions
@@ -0,0 +1,40 @@
+/**
+ * 能力插件契约（框架 §6.1）。**桥核心对能力零感知**：能力以插件形式在容器初始化时
+ * 把自己的入站 handler 注册进桥，并持有 bridge 以便异步推送出站 handler。
+ *
+ * 新增/裁剪一个原生能力 = 新增/删除一个 CapabilityProvider + 在组装根 buildCapabilities() 增删一行，
+ * 零侵入桥核心（杜绝桥层 import 任何具体能力）。
+ */
+import { common } from '@kit.AbilityKit';
+import { BridgeController } from 'feature_bridge';
+import { ConfigManager } from 'domain_resource';
+import { KvStore, LocalUploadServer } from 'platform';
+import { Logger } from 'common';
+
+/** 能力运行上下文（注入给每个 Provider）。 */
+export interface CapabilityContext {
+  /** UIAbility 上下文（拉起系统能力/弹窗/权限）。 */
+  uiAbilityContext: common.UIAbilityContext;
+  /** 配置（取 agent/market/other 等暴露给 H5 的值）。 */
+  config: ConfigManager;
+  /** 键值存储。 */
+  kv: KvStore;
+  /** 本机上传端点（截图分享用，M3）。 */
+  uploadServer: LocalUploadServer;
+  /** 通用日志。 */
+  log: Logger;
+}
+
+/** 能力插件接口。 */
+export interface CapabilityProvider {
+  /** 能力名（如 'location'/'share'），用于日志与诊断。 */
+  readonly name: string;
+  /** 把本能力的入站 handler 注册到桥；持有 bridge 以便异步推送。 */
+  register(bridge: BridgeController, ctx: CapabilityContext): void;
+  /** 应用切前台（可选，联动 §A.1）。 */
+  onForeground?(): void;
+  /** 应用切后台（可选）。 */
+  onBackground?(): void;
+  /** 容器销毁清理（可选，解绑监听/释放资源）。 */
+  onDestroy?(): void;
+}
@@ -0,0 +1,50 @@
+/**
+ * 能力注册器（框架 §6.2）。把一组 Provider 批量注册到桥，并统一转发生命周期。
+ *
+ * 容器持有一个 Registrar：onControllerAttached 时 register()，前后台时 onForeground/onBackground()，
+ * aboutToDisappear 时 onDestroy()。桥核心始终不感知任何具体能力。
+ */
+import { BridgeController } from 'feature_bridge';
+import { Logger } from 'common';
+import { CapabilityContext, CapabilityProvider } from './CapabilityProvider';
+
+export class CapabilityRegistrar {
+  private static readonly log: Logger = Logger.tag('CapabilityRegistrar');
+  private readonly providers: CapabilityProvider[];
+
+  constructor(providers: CapabilityProvider[]) {
+    this.providers = providers;
+  }
+
+  /** 注册全部 Provider 的入站 handler。 */
+  registerAll(bridge: BridgeController, ctx: CapabilityContext): void {
+    for (const p of this.providers) {
+      p.register(bridge, ctx);
+      CapabilityRegistrar.log.i(`registered capability: ${p.name}`);
+    }
+  }
+
+  forEachForeground(): void {
+    for (const p of this.providers) {
+      if (p.onForeground !== undefined) {
+        p.onForeground();
+      }
+    }
+  }
+
+  forEachBackground(): void {
+    for (const p of this.providers) {
+      if (p.onBackground !== undefined) {
+        p.onBackground();
+      }
+    }
+  }
+
+  destroyAll(): void {
+    for (const p of this.providers) {
+      if (p.onDestroy !== undefined) {
+        p.onDestroy();
+      }
+    }
+  }
+}
@@ -0,0 +1,23 @@
+/**
+ * 示例能力（M2 脚手架）。验证 CapabilityProvider 插件模式可注册并被桥分发，
+ * 对接最小回显 H5（test_echo.html 用 getTime/nativeEcho）。
+ *
+ * ⚠ M3 用真实 Provider（DeviceProvider 等）替换：buildCapabilities() 删除本行即可，
+ * 桥核心与容器零改动。
+ */
+import { BridgeController } from 'feature_bridge';
+import { CapabilityContext, CapabilityProvider } from '../core/CapabilityProvider';
+
+export class EchoSampleProvider implements CapabilityProvider {
+  readonly name: string = 'echo(sample)';
+
+  register(bridge: BridgeController, ctx: CapabilityContext): void {
+    bridge.registerHandler('getTime', (_data: string, cb: (resp: string) => void) => {
+      cb(Date.now().toString());
+    });
+    bridge.registerHandler('nativeEcho', (data: string, cb: (resp: string) => void) => {
+      cb(data);
+    });
+    ctx.log.i('echo sample registered (getTime/nativeEcho)');
+  }
+}