RoadMap-Fusion

RoadMap-Fusion 提供统一的 RoadMap API，支持 MapLibre、AMap、BDMap、MapVThree、天地图以及远端 3D RenderStreaming 场景，可运行在 2D、3D 和 Fusion 模式。

快速开始

1. 安装

npm install roadmap-fusion

2. 准备地图容器

<div id="map"></div>

html,
body,
#map {
  width: 100%;
  height: 100%;
  margin: 0;
}

3. 创建二维地图

下面示例使用高德底图。将 YOUR_AMAP_KEY 和 YOUR_AMAP_SECURITY_CODE 替换为自己的高德配置即可运行。

import RoadMap from "roadmap-fusion";

async function main() {
  const map = new RoadMap("map", {
    mapMode: "2D",
    initCam: {
      center: [118.8697, 32.01225],
      zoom: 12,
      pitch: 0,
      yaw: 0,
    },
    map2D: {
      mapSource: "AMap",
      mapConfig: [
        {
          type: "AMap",
          key: "YOUR_AMAP_KEY",
          securityJsCode: "YOUR_AMAP_SECURITY_CODE",
          mapStyle: "amap://styles/normal",
        },
      ],
    },
  });

  const result = await map.start();
  console.log(result.code, result.message);
}

main().catch(console.error);

如果使用自有 RMap 样式服务，只需替换二维底图配置：

map2D: {
  mapSource: "RMap",
  mapConfig: [
    {
      type: "RMap",
      style: "https://your-domain.example.com/styles/day.json",
    },
  ],
}

Worker 与发布目录

MapLibre Worker 默认以内联 Blob 形式随 SDK 一起加载。npm 用户无需手动配置 Worker、复制额外文件或修改构建工具配置。

发布包的核心结构如下：

node_modules/
└─ roadmap-fusion/
   └─ sdk-dist/
      ├─ metadigiee-fusion.es.js
      ├─ metadigiee-fusion.umd.js
      ├─ index.d.ts
      └─ assets/
         └─ maplibre-gl-worker-<hash>.js

sdk-dist/assets/ 中的哈希 Worker 是严格 CSP 环境的备用资源。若站点的 worker-src 不允许 blob:，请把该文件复制到站点可访问的静态目录，并在创建任何地图实例前指定其最终 URL：

import RoadMap from "roadmap-fusion";

RoadMap.setMapLibreWorkerUrl(
  "/roadmap-assets/maplibre-gl-worker-<hash>.js",
);

const map = new RoadMap("map", mapService);

此时 CSP 至少需要允许该 URL 对应的来源，例如同源部署时配置 worker-src 'self'。普通 npm/Vite/Webpack 项目不需要执行这一步。

包的根入口是浏览器 ESM；metadigiee-fusion.umd.js 是供 <script> 场景使用的浏览器产物，不是 Node.js CommonJS 入口。SSR 项目应只在客户端加载 SDK。

3D 与 Fusion 模式

3D 和 Fusion 模式需要可访问的 RenderStreaming 服务：

async function startFusionMap() {
  const map = new RoadMap("map", {
    mapMode: "Fusion",
    fusionZoom: 13,
    initCam: {
      center: [118.8697, 32.01225],
      zoom: 14,
      pitch: 60,
      yaw: 0,
    },
    map3D: {
      host: "YOUR_3D_HOST",
      port: 22222,
      scene: "UrbanRoad",
    },
    map2D: {
      mapSource: "RMap",
      mapConfig: [
        {
          type: "RMap",
          style: "https://your-domain.example.com/styles/day.json",
        },
      ],
    },
  });

  await map.start();
}

startFusionMap().catch(console.error);

本仓库开发

yarn install
yarn dev

构建可发布 SDK：

npm run build:sdk

该命令会生成 ES、UMD、TypeScript 声明和 Worker 资源，并同步当前静态 Demo 所需的 SDK 文件。静态 Demo 可通过以下命令预览：

yarn preview:static

主要源码入口：

• src/index.ts：npm/SDK 入口
• src/Map.ts：公开 RoadMap 类
• src/api/：公开 API 门面
• src/core_2d/：二维地图运行时
• src/core_3d/：三维桥接运行时
• src/sync/：共享相机、融合控制器和二维 Provider 适配器
• demo2-static/：产品交付静态示例