2.静态引入方式集成到项目

973字约3分钟

2024-12-20

Mars2D 提供了多种获取SDK类库和集成的方式，你可以根据项目的实际情况和技术栈选择以下任选其中一种方式安装。

1. npm包安装方式：适合vue、react等Node等开发框架项目，推荐使用。
1. 静态引入方式 : 适合原生项目、npm安装存在问题时、离线内网环境、所有技术栈都可以使用。
1. CDN方式集成到项目 : 适合临时演示及快速开始使用，不适合生产环境(CDN存在不稳定的情况)。

1. 下载SDK静态包

下载2个静态资源包，其中leaflet为依赖库。

mars2d 主库

下载最新版

leaflet库

下载最新版

2. 拷贝SDK到项目中

原生JS项目中

当在传统技术栈时(html/java/php/net 等)，可以在 html 的 head 标签中引入 Leaflet 官方包和 Mars2D 包所有相关资源，此方法比较简单，mars2d 已经挂载在window 对象下面，不会出现各类集成问题。

第一步在项目根目录创建lib目录，将下载的mars2d-sdk.zip和leaflet.zip解压到lib目录下，解压整理后目录结构为：

index.html
lib
- mars2d
  - img
    - …
  - mars2d.css
  - mars2d.js
- leaflet
  - leaflet.css
  - leaflet.js

Vue等前端框架项目中

如果您是Vue、React等前端框架项目中，也可以使用静态引入方式，特别是在无法成功安装和集成，运行项目不正常时，可以采用此方式集成。

第一步在对应框架的静态文件目录创建lib，比如vue3项目的public目录下，目录结构为：

public
- lib
  - mars2d
    - img
      - …
    - mars2d.css
    - mars2d.js
  - leaflet
    - leaflet.css
    - leaflet.js
src
- …
index.html

3. 修改html页面head增加静态资源引入

修改页面head部分，增加引入leaflet、mars2d等静态资源，如下：

<!--引入leaflet基础lib-->
<link href="./lib/leaflet/leaflet.css" rel="stylesheet" type="text/css" />
<script src="./lib/leaflet/leaflet.js" type="text/javascript"></script>

<!--引入mars2d库lib-->
<link href="./lib/mars2d/mars2d.css" rel="stylesheet" type="text/css" />
<script src="./lib/mars2d/mars2d.js" type="text/javascript"></script>

<!--引入mars2d库插件lib（按需引入）-->
<script src="./lib/mars2d/plugins/esri/mars2d-esri.js" type="text/javascript"></script>

4. 增加DIV展示容器

在需要呈现Mars2D地图的html页面中，加上 div 容器，并注意设置 div 的 css 高宽样式（可以直接用内置样式mars2d-container），如下：

<div id="mars2dContainer" class="mars2d-container"></div>

5. 创建地图对象

在页面js代码中，，可通过window.mars2d.* 来使用 mars2d 相关类及方法。可以增加如下代码，即可创建一个地图对象，并显示到页面中。

const mars2d = window.mars2d // 静态资源引入时，对象都是挂载在window中
const L = window.mars2d.L

// Map的参数请看API文档：http://mars2d.cn/api/Map.html
const map = new mars2d.Map("mars2dContainer", {
  basemaps: [{ name: "高德地图", type: "gaode", layer: "vec", show: true }]
})

6. 完成集成

这样你的Mars2D二维地图就集成完成了，您可以预览相关页面，查看地图效果。

新窗口查看

7. 常见问题

7.1 eslint错误校验问题解决

如果是ts、eslint相关技术栈项目中，window.*取值会存在eslint校验报错时，可以在.eslintrc.json的globals中增加如下配置：

.eslintrc.json

{
  "root": true,
  "globals": {
    "L": "readonly", //增加Leaflet全局变量
    "mars2d": "readonly"  //增加mars2d全局变量
  }
}

7.2 如果想代码中import导入mars2d,打包时实际使用CDN

如果想代码中npm安装mars2d包和import导入使用,打包实际使用CDN时。需要参考你使用项目的技术栈情况，按相关资料及技术栈API修改配置，排除mars2d、leaflet的引用和打包，比如：

vue.config.js

module.exports = {
  // 已忽略其他无关配置
  configureWebpack: {
    externals: {
      "mars2d": "mars2d",
      "leaflet": "L",
    }
  }
}

vite.config.ts

import { defineConfig } from "vite"
import { viteExternalsPlugin } from "vite-plugin-externals"

export default defineConfig({
  // 已忽略其他无关配置
  plugins: [
    viteExternalsPlugin({
      externals: {
        "mars2d": "mars2d",
        "leaflet": "L",
      }
    })
  ]
})