README.md · ThingsKit/mars3d-vue-example

## 项目介绍

这是一个基于 Vue3.0 开发的 mars3d 功能示例项目。

> 如果您不熟悉Vue，对原生JS比较熟悉，可以阅读： 
 [功能示例原生版教程](http://mars3d.cn/dev/guide/start/example-old.html) 、
 [mars3d-es5-example代码](https://gitee.com/marsgis/mars3d-es5-example)

## 视频讲解
建议先看一遍视频讲解，再实际操作，您可以[新页面查看高清视频](https://www.bilibili.com/video/BV1PL41177SS/)

视频预览：
<iframe src="//player.bilibili.com/player.html?aid=464541155&bvid=BV1PL41177SS&cid=452039973&page=1" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true" style="width:100%;min-height:550px;"> </iframe>

## 下载运行项目

### 下载代码
- [github](https://github.com/marsgis/mars3d-vue-example)

```
git clone git@github.com:marsgis/mars3d-vue-example.git
```

- [gitee](https://gitee.com/marsgis/mars3d-vue-example)：国内码云，下载速度快些。

```
git clone git@gitee.com:marsgis/mars3d-vue-example.git
```

### 运行环境

- 推荐使用 vscode，安装参考[开发环境搭建教程](guide/start/env.html)
- 安装 vscode 插件，推荐安装 volar（并禁用 vetur）、ESlint 、 Prettier
- 配置 vscode 参数， setting.json相关配置
```json
{
  "eslint.format.enable": true,
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[html]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[vue]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}
```

- 下载最新lib
建议从[http://mars3d.cn/download](http://mars3d.cn/download)下载最新mars3d类库后覆盖至`public/lib/`目录下，更新mars3d为最新版本。

### 运行命令

#### 首次运行前安装依赖
```
npm install

//或使用代理
npm i --registry=http://registry.taobao.org
```

#### 启动开发环境
```
npm run serve
```

#### 编译构建
```
npm run build
```

### 运行效果  
 [在线体验](http://mars3d.cn/example)

![image](http://mars3d.cn/img/example.jpg)

## 如何反馈问题？
- 发现您发现项目中存在的问题或者需要优化的地方；
- 如果您有一些自己全新编写的示例，希望也开源与大家分享。

提交方式：
- 欢迎在github或gitee上[提交PR](https://www.baidu.com/s?wd=在GitHub上提交PR) 
- 如果对git不熟悉，也可以整理示例代码发送邮件到 wh@marsgis.cn 由我们来整理集成。

## 项目架构

### 技术选型

- [Vue3](https://v3.cn.vuejs.org/api/)：开发框架
- [Vue CLI](https://cli.vuejs.org/zh/guide/)：开发环境
- [TypeScript](https://www.tslang.cn/):开发语言 
- [ESlint](https://eslint.bootcss.com/)：代码检查工具
- [Ant Design Vue](https://next.antdv.com/components/overview-cn/)：UI控件库
- [IconPark](https://iconpark.oceanengine.com/official)：UI图标库

> 需要有一定的知识储备，包括 vue3.0 中的 composition Api 模式等

### 主要目录说明
```
mars3d-vue-example
└───src                 主要项目代码
│   └───components      vue组件代码【重要】
│   └───example         示例代码【重要】
│   └───misc            主要存放ts相关的模块定义
│   └───pages           页面入口
│   └───styles          样式文件
│   └───utils           工具方法
└───public              无需编译构建的静态资源【重要】
│   └───config          项目和功能的配置文件
│   └───img             图片资源
│   └───lib             示例依赖资源
│   └───temp            示例的公共基础代码
│───.eslintrc.js        eslint配置文件
│───babel.config.js     babel配置
│───package.json        项目配置信息
└───vue.config.js       vueCLI 配置文件
```
与示例相关的3个主要目录是：`src\example`、`public`、`src\components`(部分功能依赖)。

#### 示例主目录
 
- 位置 src/example
- 项目中的每一个示例对应了本目录下的一个 map.js 文件，如果包含 ui 面板，需要创建一个 index.vue
- 一些情况下可以将 example 视为 public 下的一个目录

#### 依赖资源

配置的依赖会在html中按配置顺序加载，注意配置时依赖之间的先后顺序。

1. libs 依赖，公共的通用依赖，统一放在`public/lib/`目录下，并由includeLibs.js统一配置。 libs中通常会是一些开源的 js 库，如果示例只依赖 mars3d 相关资源，可省略libs字段。

```json
{
  "name": "天地图地形",
  "main": "terrain/terrainTDT",
  "usePannel": true,
  "libs": ["mars3d", "mars3d-tdt"],
  "thumbnail": "b10_terrain_tdt.jpg"
}
```

> 通过 includeLibs.js 中的 isLocal 变量，手动控制使用本地资源，还是 CDN 资源

2. resources 依赖，一些个性化的资源,在开发过程中提取封装的文件的依赖资源，比如只是单个示例本身使用的一些js、css文件。
 
```json
{
  "name": "POI兴趣点搜索(Cesium原生)",
  "main": "control/cesium/geocoder",
  "resources": ["cesiumControl.css"],
  "thumbnail": "d10_geocoder.jpg"
}
```
同级目录下只需要配置文件名，不在同级目录的 需配置打包后文件位置的绝对路径如 `/example/graphic/line/typhoon/Typhoon.js`

## 添加新的示例

下面我们已`src\example\map\sample\`为示例说明。

### 1. 配置文件 example.json 中修改配置

在 `public/config/example.json` 中加上对应的配置项，这样就能在示例列表页面看到对应的示例卡片。

```json
{
  "name": "示例名称",
  "main": "map/sample", //示例的相对路径
  "usePannel": true, // 可选参数，表示是否存在ui面板，默认false
  "libs": [], // 通用依赖项，可选参数 默认 ["mars3d"]
  "resources": ["cesiumControl.css"], // 个性化依赖项, 可选参数，默认 []
  "thumbnail": "thumbnail.jpg" // 缩略图可选, 默认为 thumbnail.jpg
}
```
> 注：上述配置`main`为`src\example`下的相对路径

### 2. 新建示例对应目录

在`src\example`示例目录下新建对应示例的子目录，因为示例众多，建议多级目录来管理，当前我们新建了`src\example\map\sample\`目录。

### 3. 新建 map.js 地图业务文件

在目录下新建`map.js`（文件名固定不可修改）主入口文件 map.js 主要用于处理地图相关业务。
在文件中必须加上 initMap 方法来初始化地球和相关业务,比如：

最简结构如下
```js
var map
// 事件对象，用于抛出事件给vue
var eventTarget = new mars3d.BaseClass()

// 构造地图主方法【必须】
function initMap(options) {
  // 创建三维地球场景
  map = new mars3d.Map("mars3dContainer", options)
}
```

> 在 map.js 中 存在以下全局方法, 并且已经预先加载了 mar3d 相关依赖

```js
globalMsg(msg, type, ...args) // message
globalAlert(msg, title, ...args) // alert
globalNotify(msg, disc, ...args) // notify
showLoading(type) // 显示loading
hideLoading(type) // 关闭loading
```

完成后我们即可访问 [http://localhost:8080/example.html?id=map/sample](http://localhost:8080/example.html?id=map/sample)来查看示例的效果。

### 4. (按需可选)配置其他依赖资源
 
 按示例本身需要来配置libs和resources依赖。

### 5.  (按需可选)新建`index.vue`业务窗口面板

在目录下新增`index.vue`文件，该文件主要是用于 UI 面板相关的业务代码。
创建控件 Vue 面板，可以参考已有示例加上相关业务面板。

同时在example.json中的对应示例增加配置`usePannel:true`

最简模板如下:
```html
<template>
  <PannelBox class="infoView"> </PannelBox>
</template>
<script lang="ts" setup>
  import PannelBox from "@comp/OperationPannel/PannelBox.vue"
  const mapWork = window.mapWork
</script>
<style scoped lang="less"></style>
```

#### 5.1. `index.vue`面板操作`map.js`内地图相关对象时。

需要在 vue 中加上下面代码进行访问

index.vue 文件中：
```js
// mapWork是map.js内定义的所有对象,目前在示例框架中做好了封装传递过来的。
const mapWork = window.mapWork

// 滑动条修改事件
const onSliderChange = () => {
  mapWork.updateBrightness(formState.brightness)
}
```

map.js 文件中：
```js
// map.js中
function updateBrightness(val) {
  bloomEffect.brightness = val
}
```

#### 5.2. `map.js`地图业务中需要操作`index.vue`面板时。

map.js 文件中：
```js
// 抛出事件
var eventTarget = new mars3d.BaseClass()

//完成操作或取到相关数据后
eventTarget.fire("loadOk", { 需要传递到vue中使用的对象 })
```

index.vue 文件中：

```js
// 取到js中的数据
mapWork.eventTarget.on("loadOk", function (event: any) {})
```

#### 5.3. `map.js`和`index.vue`各自代码业务分离的原则

原则：

- 涉及地图业务的操作均写在 map.js 中
- 涉及 UI 层面、和地图无关的操作均写在 index.vue 中,vue 中不得使用 mars3d 和 ceium 开头的类

**如何区分？**

- 删除 index.vue 时不影响地图本身业务，map.js 需要正常运行 ！！！
- 删除 map.js 时，index.vue 需要正常展示 UI(除 mapWork 相关操作无响应外) ！！！

## 阅读示例源码和调试学习
 示例的目的是演示平台的每个功能点，可以按需求或兴趣去学习每一个示例，
- （1）学习中可以查询相关类的API文档
- （2）尝试修改源码中参数、方法等，来体验不同的呈现效果。

## 开发中常见问题

### 1. 局域网离线使用时注意事项
 平台所有代码层面来说支持离线运行和使用的，但需要注意的是离线时的地图服务的相关处理。
 
 如果局域网内有相关地形、卫星底图服务可以按内网服务类型和URL地址替换下`config.json`或`构造Map的代码中`的默认地形和底图。

如果局域网内没有相关服务，可以按下面处理：
- 修改config.json中`terrain`配置中，将已有的`"show": true`配置，改为`"show": false` 
- 修改config.json中`basemaps`数组配置中，将已有的`"show": true`的图层，将该值改为`"show": false` ，并将单张图片或离线地图加上`"show": true`，并修改相关URL地址。
- 您也可以参考教程[发布三维数据服务](/guide/data/server.html)进行部署离线地图服务，里面也有一些示例离线数据。

### 2. src\example\中增加的资源访问 404

因为新增静态资源涉及拷贝，需要重启服务 `npm run serve`

## Mars3D 是什么 
>  `Mars3D平台` 是[火星科技](http://marsgis.cn/)研发的一款基于 WebGL 技术实现的三维客户端开发平台，基于[Cesium](https://cesium.com/cesiumjs/)优化提升与B/S架构设计，支持多行业扩展的轻量级高效能GIS开发平台，能够免安装、无插件地在浏览器中高效运行，并可快速接入与使用多种GIS数据和三维模型，呈现三维空间的可视化，完成平台在不同行业的灵活应用。

> Mars3D平台可用于构建无插件、跨操作系统、 跨浏览器的三维 GIS 应用程序。平台使用 WebGL 来进行硬件加速图形化，跨平台、跨浏览器来实现真正的动态大数据三维可视化。通过 Mars3D产品可快速实现浏览器和移动端上美观、流畅的三维地图呈现与空间分析。

### 相关网站 
- Mars3D官网：[http://mars3d.cn](http://mars3d.cn)

- Mars3D开源项目列表：[https://github.com/marsgis/mars3d](https://github.com/marsgis/mars3d)

ThingsKit/mars3d-vue-example

简介

发行版

贡献者

近期动态

ThingsKit/mars3d-vue-example .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

ThingsKit/mars3d-vue-example