在阅读本节前,建议您已阅读:
- 获取 Mars3D SDK 类库 :了解 sdk 的不同下载及安装方式
- 开源仓库清单 :下载一些模版代码阅读或参考下
再尝试将 mars3d 集成到自己的项目中。
下面三种方式任选一种,注意不要重复操作
# 1. 在html直接引入所有资源方式集成 (cdn cesium + cdn mars3d)
具体引入方式请参考上一篇获取 Mars3D SDK 类库 操作即可。
当在传统技术栈时(html/java/php/net 等),可以在 html 的 head 标签中引入 Cesium 官方包和 Mars3D 包所有相关资源,此方法比较简单,mars3d 已经挂载在window 对象 (opens new window)下面,不会出现各类集成问题。
<!--引入cesium基础lib-->
<link href="./lib/Cesium/Widgets/widgets.css" rel="stylesheet" type="text/css" />
<script>
// window.CESIUM_BASE_URL = "./lib/Cesium/" //非必须,如jsp、asp.net等非html框架报错时建议取消注释
</script>
<script src="./lib/Cesium/Cesium.js" type="text/javascript" ></script>
<script src="./lib/turf/turf.min.js" type="text/javascript" ></script>
<!--引入mars3d库lib-->
<link href="./lib/mars3d/mars3d.css" rel="stylesheet" type="text/css" />
<script src="./lib/mars3d/mars3d.js" type="text/javascript" ></script>
2
3
4
5
6
7
8
9
10
11
引入 mars3d 后,在项目 js 代码中,可通过window.mars3d.*
来使用 mars3d 相关类及方法。
# 2. 在html直接引入Cesium资源和import mars3d方式集成 (cdn cesium + import mars3d)
如果在 Node 下的相关 vue/react/angular 等技术栈(下面介绍的方式3)时无法成功集成,运行项目不正常,也可以在 import 引入 mars3d 的方式下,兼容识别 head 静态引入的 Cesium 库。
主要修改项目地图呈现对应的首页index.html (opens new window)页面,在其 head 中引入 cesium 资源。
cesium 是通过在 html 的 head 中静态引入的
<!--引入cesium基础lib-->
<link href="./lib/Cesium/Widgets/widgets.css" rel="stylesheet" type="text/css" />
<script>
// window.CESIUM_BASE_URL = "./lib/Cesium/" //非必须,如jsp、asp.net等非html框架报错时建议取消注释
</script>
<script src="./lib/Cesium/Cesium.js" type="text/javascript" ></script>
<script src="./lib/turf/turf.min.js" type="text/javascript" ></script>
2
3
4
5
6
7
mars3d 还是通过 import 方式引入及使用的:
import "mars3d-cesium/Build/Cesium/Widgets/widgets.css" //依赖的cesium库本身css
import "mars3d/mars3d.css"; //v3.8.6及之前版本使用 import "mars3d/dist/mars3d.css";
import * as mars3d from "mars3d";
2
3
您可以参考vue2-template (opens new window) 项目的index.html (opens new window)文件,里面已有演示。
如果您下载了该项目源码进行运行,注意下载后修改.env (opens new window)文件中配置为VUE_APP_MARS3D_SOURCE=cdn
。
同时也建议在对应的技术栈配置中排除mars3d-cesium
的引用和打包
configureWebpack: {
externals: { 'mars3d-cesium': 'Cesium' }
},
2
3
# 3.通过 import 导入 mars3d 及所有依赖包的集成方式(import cesium + import mars3d)
使用 Node 环境下的现代 web 前端技术栈时,可以使用 npm 等来安装 mars3d 包并 import 导入后来使用。 具体引入方式请参考上一篇获取 Mars3D SDK 类库 操作即可。
因为 mars3d 所依赖的 Cesium 是一个多文件资源的 js 库,需要对其依赖的一些资源文件进行拷贝处理(这也是容易出问题的地方), 90% 的集成问题都是出现在这对 cesium 库的拷贝处理上,项目运行没有正确识别 Cesium 主目录造成各种问题。
下面请根据你项目的技术栈,选择对应的集成方式。
# 3.1 webpack 技术栈时 的项目配置修改
修改文件:webpack.config.js
参考项目:mars3d-webpack (opens new window)
关键代码及步骤:
- 安装依赖库(注意copy-webpack-plugin与webpack版本的依赖,可能需要按webpack对应版本的相关版本安装)
npm install copy-webpack-plugin --save-dev
- 修改 webpack.config.js 配置文件
const path = require("path");
const webpack = require("webpack");
const CopyWebpackPlugin = require("copy-webpack-plugin");
const cesiumSourcePath = "node_modules/mars3d-cesium/Build/Cesium/"; // cesium库安装目录
const cesiumRunPath = "./mars3d-cesium/"; // cesium运行时路径
module.exports = {
module: {
rules: [
{ test: /\.css$/, use: ["style-loader", "css-loader"], },
{ test: /\.js$/, use: { loader: 'babel-loader', options: { plugins: ['@babel/plugin-proposal-class-properties'] } } }
],
},
plugins: [
// CESIUM_BASE_URL是标识cesium资源所在的主目录,其内部资源加载、多线程等处理时需要用到
new webpack.DefinePlugin({
CESIUM_BASE_URL: JSON.stringify(cesiumRunPath),
}),
// Cesium相关资源目录需要拷贝到系统目录下面(部分CopyWebpackPlugin版本的语法可能没有patterns)
new CopyWebpackPlugin({
patterns: [
{ from: path.join(cesiumSourcePath, 'Workers'), to: path.join(cesiumRunPath, 'Workers') },
{ from: path.join(cesiumSourcePath, 'Assets'), to: path.join(cesiumRunPath, 'Assets') },
{ from: path.join(cesiumSourcePath, 'ThirdParty'), to: path.join(cesiumRunPath, 'ThirdParty') },
{ from: path.join(cesiumSourcePath, 'Widgets'), to: path.join(cesiumRunPath, 'Widgets') }
]
}),
],
};
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
- 常见问题:集成提示错误时,可看下"@vue/cli-service"的版本,需要是v5及以上版本,可以升级为:"~5.0.0",
# 3.2 vue-cli 技术栈时 的项目配置修改
修改文件:vue.config.js
参考项目:vue2-template (opens new window)
关键代码及步骤:
- 安装依赖库(注意copy-webpack-plugin与webpack版本的依赖,可能需要按webpack对应版本的相关版本安装)
npm install copy-webpack-plugin --save-dev
- 修改 vue.config.js 配置文件
const path = require('path')
const webpack = require('webpack')
const CopyWebpackPlugin = require('copy-webpack-plugin')
module.exports = {
configureWebpack: (config) => {
const cesiumSourcePath = 'node_modules/mars3d-cesium/Build/Cesium/' // cesium库安装目录
const cesiumRunPath = './mars3d-cesium/' // cesium运行时路径
const plugins = [
// 标识cesium资源所在的主目录,cesium内部资源加载、多线程等处理时需要用到
new webpack.DefinePlugin({
CESIUM_BASE_URL: JSON.stringify(path.join(config.output.publicPath, cesiumRunPath))
}),
// Cesium相关资源目录需要拷贝到系统目录下面(部分CopyWebpackPlugin版本的语法可能没有patterns)
new CopyWebpackPlugin({
patterns: [
{ from: path.join(cesiumSourcePath, 'Workers'), to: path.join(config.output.path, cesiumRunPath, 'Workers') },
{ from: path.join(cesiumSourcePath, 'Assets'), to: path.join(config.output.path, cesiumRunPath, 'Assets') },
{ from: path.join(cesiumSourcePath, 'ThirdParty'), to: path.join(config.output.path, cesiumRunPath, 'ThirdParty') },
{ from: path.join(cesiumSourcePath, 'Widgets'), to: path.join(config.output.path, cesiumRunPath, 'Widgets') }
]
})
]
return {
module: { unknownContextCritical: false }, // 配置加载的模块类型,cesium时必须配置
plugins: plugins
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# 3.3 vite 技术栈时 的项目配置修改
修改文件:vite.config.ts
参考项目:vue3-vite-template (opens new window)
关键代码及步骤:
- 安装依赖库
npm install vite-plugin-mars3d --save-dev
- 修改 vite.config.ts 配置文件
import { defineConfig } from 'vite';
import { mars3dPlugin } from 'vite-plugin-mars3d';
export default defineConfig({
plugins: [mars3dPlugin()]
});
2
3
4
5
6
# vite常见问题
- 使用原生cesium时,不要安装 mars3d-cesium(不能同时存在2个cesium 包),再在vite.config.ts配置改为
mars3dPlugin({ cesiumPackageName: "cesium" })
- 如果项目的 package.json 没有 type:"module" 或vite4及之前版本时,请使用 "vite-plugin-mars3d":"~3.1.3"
- 如果项目的 package.json 有 type:"module" 直接用最新版本即可。
- 如果无法排除解决问题,也可以在vite.config.ts配置改为静态引入
mars3dPlugin({ useStatic: true })
# 4. 新建DIV容器 + 创建地图
在需要呈现地图的html页面或相关vue/react等组件中,加上 div 容器,并注意设置 div 的 css 高宽样式。
<div id="mars3dContainer" class="mars3d-container"></div>
在对应技术栈的相关代码出,使用Map 地图类 (opens new window)类创建三维地图场景,加入下面代码:
var mapOptions = {
basemaps: [{ name: "天地图", type: "tdt", layer: "img_d", show: true }],
};
var map = new mars3d.Map("mars3dContainer", mapOptions); //支持的参数请看API文档:http://mars3d.cn/api/Map.html
2
3
4
详细可以对应技术栈的开源最简项目模板