Android 配置

Android 使用 Google Maps SDK. 将您的 API 密钥作为 manifest 元数据添加到 android/app/src/main/AndroidManifest.xml 内部 <application>:

<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${GOOGLE_MAPS_API_KEY}" />

在 android { defaultConfig { ... } } 中的 android/app/build.gradle，将占位符映射到环境变量或本地密钥：

android {
    defaultConfig {
        manifestPlaceholders = [
            GOOGLE_MAPS_API_KEY: System.getenv("GOOGLE_MAPS_API_KEY") ?: "REPLACE_WITH_YOUR_GOOGLE_MAPS_API_KEY"
        ]
    }
}

导出 GOOGLE_MAPS_API_KEY ，否则 Gradle 会注入回退字符串，导致 Maps SDK 在运行时失败。

启用 Android 版 Maps SDK 在 Google Cloud Console 中获取该密钥。并将相同的密钥传递给 NativeMap.create({ apiKey }) 以保持与 Web 构建的一致性。

WebView 背后的地图

在 create期间，插件会附加一个 MapView 到 Capacitor WebView 下，调用 bringToFront() 在 WebView 上，并设置 webView.setBackgroundColor(Color.TRANSPARENT) 以便您的 HTML UI 可以在地图上方渲染。

对于嵌入式地图，请向传递一个容器元素给 NativeMap.create({ element })。插件会测量该元素，并在调整大小或滚动时保持原生地图框架同步。

对于 后台模式，传入 toBack: true 并设置 config.x, config.y, config.width，以及 config.height (若省略则使用 viewport 默认值)。调用 updateLayout 当窗口大小或方向发生变化时，以确保 MapView 与 WebView 保持对齐。