3D 地图最佳实践

本指南详细介绍了 3D 地图 Web 组件以及在与应用集成时需要考虑的事项。

性能考虑因素

为确保互动和视觉元素流畅且响应迅速，请考虑以下方法。

加载地图

3D 地图的初始加载和渲染设置结合了浏览器配置技术和界面最佳实践，可提供最佳用户体验。

API 加载：使用 3D 地图异步动态加载，以便在初始页面加载时加载 Maps JavaScript API。
库：根据需要以程序化方式加载库，例如 google.maps.importLibrary("maps3d")。或者，如果您在 HTML 网页中直接使用直接脚本加载的 <gmp-map-3d> 等 Web 组件，库会在适当的时间自动加载
管理基础地图功能：使用自定义 mapId 过滤基础地图 POI（混合模式），并控制其密度，尤其是在应用有自己的一组自定义元素（例如标记或折线）时。这样可以避免视觉杂乱和潜在的重叠。或者，您也可以停用底图矢量图块功能，例如 POI、道路折线、道路名称、街道名称（卫星模式）。
事件：监听 gmp-steadystate 或 gmp-error 事件，以构建后续逻辑，例如加载标记、为相机设置动画效果。

地图加载顺序 — 背景画布 > 缩小的图块 > 地形网格 > 地表网格（例如：建筑物）> 地标和道路标签，并行加载的自定义元素（标记、3D 模型等）

用户互动：在更改地图内容之前，请等待 gmp-steadystate 事件。如果用户在初始 gmp-steadystate 事件之前开始与地图互动（平移、缩放），则该事件仅在用户停止互动后触发。避免在用户平移或缩放地图时显示或更新叠加层内容（例如标记或多边形），避免通过监听 gmp-centerchange、gmp-headingchange、gmp-rangechange、gmp-rollchange、gmp-tiltchange 来显示或更新叠加层内容（例如标记或多边形）。
使用 requestAnimationFrame() (rAF) 进行持续更新，并严格将密集型计算与绘制调用分开。
- 使用 rAF：将更新与浏览器的显示速率同步，以实现流畅的 60FPS 动画并降低功耗。
- 避免执行密集型绘制工作：在最终更新期间，不要执行繁重的非绘制任务。
- 分离逻辑：在 rAF 循环中，在最少的 Web 组件更新调用之前执行所有密集型逻辑。
初始场景设置：<gmp-map-3d> 倾斜等相机设置会影响加载速度。场景的缩放或倾斜程度越大，显示的详细多边形就越多，需要加载的资源也就越多。详细程度还取决于位置（例如：建筑物众多的城市与只有自然特征的乡村）。
- 最好是缩小程度较低（高海拔）且倾斜度较低或不倾斜的视图。
- 向地图添加边界（示例），以便用户始终专注于特定区域，并且图块可以完全加载。
预加载器视觉效果：虽然 <gmp-map-3d> 加载速度非常快，但对于使用低端设备（低 GPU）或带宽（慢速 4G）的用户，可能需要一些时间才能以全分辨率显示。在这种情况下，您可以创建一个包含图片、动画或文字的预加载器，并在后台加载 3D 场景。请参阅下文中的关键事件：

// create the map in the background and wait for gmp-steadystate event
async function initMap() {
    await google.maps.importLibrary("maps3d");
    const map = document.querySelector('gmp-map-3d');
    const div = document.querySelector('div'); // preloader "
    map.addEventListener('gmp-steadystate', ({isSteady}) => {
        if (isSteady) {
            div.style.display = 'none';
        }
    });
}
initMap();

2D 地图：
- 您可以向这些用户提供替代的 2D 地图 (SATELLITE)，同时仍包含您的地理位置数据（例如标记）。

或者，也可以显示处于卫星模式的补充性 2D 静态地图，以便用户在加载时直观地了解给定地点。

视觉元素性能和管理

3D 地图提供了多种方式来显示标记、折线、多边形和 3D 模型等视觉元素，即使是大量视觉元素，也能以最佳性能和最短渲染时间进行显示。

标记

最佳自定义选项：
- PinElement：如需进行基本的标记更改（颜色、缩放比例、边框、文字字形），请使用 <gmp-pin> 元素或 PinElement 类。这是性能最高的自定义方法。
- 谨慎使用 HTMLImageElement 或 SVGElement 标记：用于进行更多自定义，例如添加透明度或将图片（例如图标）注入 SVGElement（需要 base64 编码）。它们会在加载时栅格化，并产生性能开销。HTMLImageElement 和 SVGElement 必须封装在 <template> 元素中，然后才能分配给 Marker3DElement 的默认 slot。
- 目前不支持添加纯 HTML 或 CSS。
管理冲突行为：利用标记的 collisionBehavior 属性。对于必须始终可见的关键标记，请相应地设置行为。对于不太重要的标记，允许用户将其隐藏，以保持更简洁、更清晰的地图体验，尤其是在高缩放级别下。
仅限关键 POI：仅对必须透过建筑物或地形看到的标记使用 drawsWhenOccluded（或以编程方式设置该属性），例如救援目标、埋设的公用事业线路或用户的头像。
测试遮挡：由于地图是 3D 的，因此标记可能会被建筑物或地形遮挡。测试不同的拍摄角度和标记海拔高度，以确保关键 POI 保持可见，或实现相关逻辑，以便在被遮挡时调整可见性和海拔高度。
利用海拔高度：在 3D 地图中，标记应使用具有海拔高度值的位置。对于与地形或建筑物关联的标记，请使用 altitudeMode: 'RELATIVE_TO_GROUND'、'RELATIVE_TO_MESH' 或类似设置，以确保在地图倾斜或旋转时标记能够正确锚定。

多边形和折线

多边形加载示例 — 示例场景：加载 1, 000 个多边形需要 100-150 毫秒（现代笔记本电脑：macOS M3 Pro、Chrome）

简化几何图形：在渲染之前，对路径数据应用简化算法。这样可以减少顶点数量，同时保留大致形状，从而大幅提高渲染速度，尤其是在处理复杂的边界或路线时。
按缩放级别进行精简：对于非常大的数据集，请考虑仅在用户放大到相应区域时加载更高细节的几何图形。在较低的缩放级别下，只需使用高度简化的折线或多边形版本。
为拉伸多边形预先计算：如果您的多边形是拉伸的 (extruded: true)，则路径数据会定义一个 3D 体积（网格）。处理复杂的高顶点多边形需要大量计算资源。确保多边形的源数据尽可能简单。
测试折线和多边形性能：添加大量或复杂的折线/多边形（尤其是挤出为 3D 时）时，请确保它们不会导致帧速率下降。如有必要，请限制顶点数量或使用简化算法。
更新形状时，应在单个操作中修改整个路径数组，而不是循环修改各个元素。单个赋值操作（例如，polyline.path = newPathArray;）比多次迭代更新效率高得多。
尽可能避免使用拉伸多段线：虽然多段线可以使用海拔高度值放置在 3D 空间中，但拉伸多段线（例如，为其提供描边宽度和较大的海拔高度范围）可能会消耗大量图形资源。尽可能使用地面上的 2D 折线 (RELATIVE_TO_GROUND) 或最小描边宽度，以提高性能。
仅对关键的路线元素使用 drawsOccludedSegments。对于背景或情境形状，允许它们被地图的 3D 几何图形自然遮挡。显示非关键隐藏几何体增加了不必要的渲染复杂性。

3D 模型

在 <gmp-map-3d> 中，3D 模型 .glb 渲染和互动性（例如 gmp-click 事件）非常快。

通过压缩尽可能减小文件大小：为确保快速加载（尤其是在移动网络上），请将复杂的 .glb 模型文件保持在 5MB 以下（最好更小）。实现此目的的主要方法是对 .glb 文件中的网格数据应用 Draco 压缩，这样可以显著减小文件大小（通常可减小 50% 以上），同时将视觉质量损失降至最低。
将模型原点居中：确保 3D 建模软件导出的模型以其原点（0, 0, 0 点）为中心位于模型底部。这样可以简化地图上的定位和旋转，确保模型正确锚定到纬度/经度坐标。
管理 CORS：如果您的模型文件托管在与 Web 应用不同的网域或 CDN 上，您必须配置托管服务器以包含必要的跨源资源共享 (CORS) 标头（例如，Access-Control-Allow-Origin: *）。否则，地图无法加载模型。