1.npm包安装方式集成到项目

1368字约5分钟

2024-12-20

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

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

1. 从 npm 安装获取SDK

使用 Node 环境下的现代 web 前端技术栈时，可以使用 npm 或 pnpm 或 yarn 等方式来安装 mars2d 包

npm

//安装mars2d主库，其中leaflet为依赖库
npm install mars2d leaflet  --save

//安装mars2d插件（按需安装）
npm install mars2d-esri --save

pnpm

//安装mars2d主库，其中leaflet为依赖库
pnpm add mars2d leaflet

//安装mars2d插件（按需安装）
pnpm add mars2d-esri --save

yarn

//安装mars2d主库，其中leaflet为依赖库
yarn add mars2d leaflet

//安装mars2d插件（按需安装）
yarn add mars2d-esri --save

3. 增加DIV展示容器

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

如下：

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

4. 在相关组件中import导入SDK

安装后在相关使用组件文件中import导入SDK,并可增加如下代码，即可创建一个地图对象，并显示到页面中。

// 引入css
import "leaflet/dist/leaflet.css"
import "mars2d/mars2d.css"

import * as mars2d from "mars2d"
import "mars2d-esri" // 导入mars2d插件，导入即可，自动注册（按需使用，需要先npm install mars2d-esri）
// import "mars2d-echarts"; // 其他插件类型，自行修改名称

const L = mars2d.L

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

参考项目：https://gitee.com/marsgis/mars2d-vue-template
修改文件：vite.config.ts

5. 完成集成

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

新窗口查看

7. 常见问题

7.1. 集成失败报错无法解决时

如果尝试修改相关配置无法成功集成时，也可以排除leaflet库，使用在html直接引入Leaflet资源，这样可以不用操作上一步的配置，配置方式更为简单些。

可以在 import 引入 mars2d 的方式下，兼容识别 head 静态引入的 Leaflet 库。

index.html增加静态引入leaflet

主要修改项目地图呈现对应的首页index.html页面，在其 head 中引入 leaflet 资源，可以参考静态引入方式Mars2D中下载leaflet资源到本地的步骤。

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

修改配置，排除`leaflet`的引用和打包

在对应的技术栈配置中按技术栈的配置规则，排除leaflet的引用和打包。

vue.config.js

module.exports = {
  // 已忽略其他无关配置
  configureWebpack: {
    externals: { "leaflet": "L" } // 排除使用 leaflet
  }
}

vite.config.ts

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

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

7.2 临时更新SDK为最新版本

如果mars2d官方临时修改SDK，但未发布最新npm正式包时，则可以通过在官网下载最新SDK,按以下方式更新mars2d最新开发版本。

方式 1：临时覆盖本地node_modules

该方式可用于临时更新本地node_modules中的mars2d包，但需要每次npm i 后覆盖一次。

将离线包的mars2d.js和mars2d.css文件覆盖到 \node_modules\mars2d\目录下同名文件。下载链接： http://mars2d.cn/lib/mars2d/mars2d.css http://mars2d.cn/lib/mars2d/mars2d.js http://mars2d.cn/lib/mars2d/mars2d.d.ts

覆盖后执行npm run clean-cache清理缓存（确保F12打印的编译日期是最新的），可在package.json中scripts节点下加上下面命令：

"clean-cache": "rimraf node_modules/.cache/ && rimraf node_modules/.vite",

方式 2：修改package.json的指向项目本地目录

此方式适合授权版本SDK或想永久固化版本时使用，操作步骤：

在项目根目录创建/packages/目录
覆盖官网下载最新版：将mars2d-sdk.zip离线包放到packages目录，并解压到当前目录下，解压后packages的目录结构为：

mars2d-vue-project
- packages
  - mars2d
    - img
      - …
    - mars2d.css
    - mars2d.d.ts
    - mars2d.js
    - package.json#必须有，如果没有请下载包中拷贝：http://mars2d.cn/download/mars2d.zip

修改链接：修改package.json中mars2d包配置为： "mars2d": "file:packages/mars2d",
【重要】删除node_modules重新npm install安装依赖

7.3. vue2老技术栈中编译慢问题

如果vue2等技术栈时引入本地版本build编译很慢时，可以按下面配置修改babel.config.js

module.exports = {
  // 已忽略其他配置
  ignore: [
    "packages/mars2d/mars2d.js", // 改成自己的本地地址
  ],
};