3.CDN方式集成到项目

约 1204 字大约 4 分钟

2024-12-20

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

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

1. 从 CDN 获取

CDN方式集成与静态引入方式集成到项目类似，只是引入的资源是从CDN服务器获取的，这样可以避免下载安装包，但不适合生产环境(CDN存在不稳定的情况)。

在 html 的 head 标签中引入 Mars3D 包相关 CDN 资源，有以下不同的CDN服务可以选择使用，任意选择一种即可。

1.1 淘宝npmjs.com镜像服务站

提供商：国内淘宝
官网：https://registry.npmmirror.com
说明：国内访问速度快且稳定，推荐使用。

<!--引入cesium基础lib-->
<script>
  // window.CESIUM_BASE_URL = "https://registry.npmmirror.com/mars3d-cesium/latest/files/Build/Cesium/" //非必须，如jsp、asp.net等非html框架报错时建议取消注释
</script>
<link href="https://registry.npmmirror.com/mars3d-cesium/latest/files/Build/Cesium/Widgets/widgets.css" rel="stylesheet" type="text/css" />
<script src="https://registry.npmmirror.com/mars3d-cesium/latest/files/Build/Cesium/Cesium.js" type="text/javascript"></script>
<script src="http://mars3d.cn/lib/turf/turf.min.js" type="text/javascript"></script>

<!--引入mars3d库lib-->
<link href="https://registry.npmmirror.com/mars3d/latest/files/mars3d.css" rel="stylesheet" type="text/css" />
<script src="https://registry.npmmirror.com/mars3d/latest/files/mars3d.js" type="text/javascript"></script>

<!--引入mars3d库插件lib（按需引入）-->
<script src="https://registry.npmmirror.com/mars3d-space/latest/files/mars3d-space.js" type="text/javascript"></script>

1.2 国外unpkg.com服务

提供商：国外 Michael Jackson 维护的开源项目，由Cloudflare提供服务器支持。
官网：https://unpkg.com
说明：国外稳定，国内偶尔被墙。

<!--引入cesium基础lib-->
<script>
  // window.CESIUM_BASE_URL = "https://unpkg.com/mars3d-cesium@latest/Build/Cesium/" //非必须，如jsp、asp.net等非html框架报错时建议取消注释
</script>
<link href="https://unpkg.com/mars3d-cesium@latest/Build/Cesium/Widgets/widgets.css" rel="stylesheet" type="text/css" />
<script src="https://unpkg.com/mars3d-cesium@latest/Build/Cesium/Cesium.js" type="text/javascript"></script>
<script src="https://unpkg.com/@turf/turf/turf.min.js" type="text/javascript"></script>

<!--引入mars3d库lib-->
<link href="https://unpkg.com/mars3d@latest/mars3d.css" rel="stylesheet" type="text/css" />
<script src="https://unpkg.com/mars3d@latest/mars3d.js" type="text/javascript"></script>

<!--引入mars3d库插件lib（按需引入）-->
<script src="https://unpkg.com/mars3d-space@latest/mars3d-space.js" type="text/javascript"></script>

1.3 国外jsDelivr服务

提供商：国外一个开源的免费公共CDN平台
官网：jsDelivr
说明：国外稳定，国内偶尔被墙。

<!--引入cesium基础lib-->
<script>
  // window.CESIUM_BASE_URL = "https://cdn.jsdelivr.net/npm/mars3d-cesium@latest/Build/Cesium/" //非必须，如jsp、asp.net等非html框架报错时建议取消注释
</script>
<link href="https://cdn.jsdelivr.net/npm/mars3d-cesium@latest/Build/Cesium/Widgets/widgets.css" rel="stylesheet" type="text/css" />
<script src="https://cdn.jsdelivr.net/npm/mars3d-cesium@latest/Build/Cesium/Cesium.js" type="text/javascript"></script>
<script src="https://unpkg.com/@turf/turf/turf.min.js" type="text/javascript"></script>

<!--引入mars3d库lib-->
<link href="https://cdn.jsdelivr.net/npm/mars3d@latest/mars3d.css" rel="stylesheet" type="text/css" />
<script src="https://cdn.jsdelivr.net/npm/mars3d@latest/mars3d.js" type="text/javascript"></script>

<!--引入mars3d库插件lib（按需引入）-->
<script src="https://cdn.jsdelivr.net/npm/mars3d-space@latest/mars3d-space.js" type="text/javascript"></script>

2. 增加DIV展示容器

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

<div id="mars3dContainer" class="mars3d-container"></div>

3. 创建地图对象

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

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

// Map的参数请看API文档：http://mars3d.cn/api/Map.html
const map = new mars3d.Map("mars3dContainer", {
  basemaps: [{ name: "天地图", type: "tdt", layer: "img_d", show: true }]
})

4. 完成集成

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

新窗口查看

5. 常见问题

5.1 eslint错误校验问题解决

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

.eslintrc.json

{
  "root": true,
  "globals": {
    "Cesium": "readonly", //增加Cesium全局变量
    "mars3d": "readonly"  //增加mars3d全局变量
  }
}

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

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

vue.config.js

module.exports = {
  // 已忽略其他无关配置
  configureWebpack: {
    externals: { 
      "mars3d": "mars3d", 
      "mars3d-cesium": "Cesium", 
      "@turf/turf": "turf", 
    } 
  }
}

vite.config.ts

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

export default defineConfig({
  // 已忽略其他无关配置
  plugins: [
    viteExternalsPlugin({
      externals: { 
        "mars3d": "mars3d", 
        "mars3d-cesium": "Cesium", 
        "@turf/turf": "turf", 
      }
    })
  ]
})