鸿蒙PC实战_OpenHarmony+ Cordova：JS Proxy 注入失败与 `window.gameNative` 为 undefined 排查指南

2501_92232234

1085人浏览 · 2025-11-21 16:17:55

2501_92232234 · 2025-11-21 16:17:55 发布

典型报错/现象：

Uncaught TypeError: Cannot read properties of undefined (reading 'toast')

window.gameNative 长时间为 undefined

偶现可用、偶现不可用（时序问题）

GamePlugin 实现，专门解决 JS Proxy 注入失败 类问题，帮助你系统定位 window.gameNative 无法使用的根因。

1. 调用链与注入时机总览

在项目中，window.gameNative.toast() 的可用性取决于三个环节：

ArkTS 插件 是否正确注册 JS Proxy。
注入时机 是否覆盖了 WebView 生命周期关键点。
Web 端调用 是否有降级与重试策略。

1.1 调用与注入的整体时序

时序相关特性：

如果 Web 比 Plugin 更早执行，就会出现一段时间 window.gameNative === undefined。
若只在某一个时机注册 Proxy（比如 initialize），一旦错过，就可能“永久不可用”。

2. ArkTS 插件层：确保 Proxy 真正被注册

2.1 检查 `GamePlugin` 的注入逻辑

在自定义插件中，我们通常会写类似逻辑（下述为示意）：

class JsGameNative {
  private ui: UIContext;
  constructor(ui: UIContext) { this.ui = ui; }
  toast(message: string) {
    this.ui.getPromptAction().showToast({ message: String(message) });
  }
}

export class GamePlugin extends CordovaPlugin {
  private registered: boolean = false;
  private jsObj: JsGameNative | null = null;

  private tryRegisterProxy(): void {
    if (this.registered) return;
    const ctx = this.cordovaWebView?.getUIContext();
    const controller = this.cordovaWebView?.getWebviewController();
    if (ctx && controller) {
      if (!this.jsObj) {
        this.jsObj = new JsGameNative(ctx);
      }
      controller.registerJavaScriptProxy(this.jsObj as ESObject, 'gameNative', [], ['toast']);
      this.registered = true;
    }
  }

  initialize(ci: CordovaInterface, cw: CordovaWebView): void {
    this.tryRegisterProxy();
  }

  onPageEnd(): void {
    this.tryRegisterProxy();
  }
}

2.2 插件层常见问题

cordovaWebView 或 WebviewController 为 null
- 说明初始化时机太早，可通过日志验证：

console.log('[GamePlugin] tryRegisterProxy ctx=', !!ctx, ' controller=', !!controller);

只在 initialize 中注册
- 部分设备/版本中，initialize 调用时 WebView 还未完全就绪，导致 Proxy 注册失败。
- 建议同时在 onPageEnd 等生命周期中再试一次。
registered 标记用法错误
- 若在失败路径也将 registered 设为 true，会导致后续不再重试。

建议：

每次调用 tryRegisterProxy 前后均输出日志，明确是否真正执行了 registerJavaScriptProxy。

只在成功注册后才将 registered 置为 true。

3. 多时机注入：MainPage + Plugin 双保险

除了在插件中注册 Proxy，你还可以在 MainPage 所在的页面层（如 Index.ets）利用生命周期做一次“兜底注册”。

3.1 Index.ets 层面的 Proxy 注册（思路）

思路是利用 MainPageCycle，在：

onControllerAttached：Web 控制器挂载时注册一次；
onSetCordovaWebAttribute（或等效回调）：Cordova WebView 属性就绪时再注册一次。

通过这类“双保险”，即便插件侧偶尔时机不对，也能在页面层兜底，从而降低 window.gameNative 为 undefined 的概率。

时序图示例：

4. Web 端：合理的降级与重试策略

即便原生注入逻辑完善，Web 端在调用时仍可能遇到 短暂的 undefined。合理的做法是：

提供统一封装函数，例如 showToast(msg)。
先尝试 window.gameNative.toast，失败时降级到 cordova.exec。
两者都不可用时，稍后重试。

4.1 推荐封装示意

function showToast(msg) {
  try {
    if (window.gameNative && typeof window.gameNative.toast === 'function') {
      window.gameNative.toast(msg);
    } else if (window.cordova && typeof window.cordova.exec === 'function') {
      window.cordova.exec(function(){}, function(){}, 'GamePlugin', 'toast', [{ message: msg }]);
    } else {
      setTimeout(() => showToast(msg), 200); // 等待注入
    }
  } catch (e) {
    console.error('[2048] toast error:', e);
  }
}

4.2 index.html 中等待注入（可选）

在 index.html 尾部，可以加一个简单的“注入探测脚本”，帮助你在调试阶段确认 Proxy 是否就绪：

<script>
  (function waitForNative() {
    if (window.gameNative) {
      console.log('[Init] gameNative ready');
    } else {
      console.log('[Init] gameNative not ready, retry...');
      setTimeout(waitForNative, 100);
    }
  })();
</script>