全栈从0到1 3D旅游地图标记和轨迹生成

功能演示

演示视频

体验地址

Vercel App

开发技术栈：

NextJs（前端框架）
React（前端框架）
TailwindCSS （CSS样式）
echart + echart gl （地图生成）
shadui（UI组件库）
Zustand
lucide-react （图标）

第三方：

Convex（数据存储+接口）
Vercel（项目托管）
高德开放平台（提供地图编码、逆编码等WEB API）

开发流程

下面给出关键步骤及部分代码。

1. Setup

1.1 初始化NextJS项目

系统要求：Nodejs 18.17+
打开终端，在控制台执行：

npx create-next-app@latest```全部选择默认选项即可。  
![image.png](https://cdn.jsdelivr.net/gh/Ygria/Pictures@main/20240425232407.png)  初始化完成后，进入项目并运行。  ```bash  
cd travel-tracel  
npm run dev

打开localhost:3000，看到如下页面，项目初始化成功。

1.2 安装npm依赖

安装一些主要的依赖。后续需要用到的依赖可以边开发边安装。

# 安装echarts依赖  
npm install echarts-for-react  
npm install echarts-gl  
npm install require # 图标组件  
npm install lucide-react

2 定义标记点

实现输入地点或地点关键字，查询经纬度，从而完成标记点的定义。
实现思路：

首先查询Convex数据库，提供10个最匹配的候选项
若没有找到对应候选项，用户可以点击搜索按钮，会调用高德API进行查询。
如果仍然没有查询到，可以点击“经纬度”按钮，进行经纬度的自行填写。
已经添加了的标记点，支持编辑和删除。
使用Zustand，进行地点增、删、改等状态管理。

2.1 定义useLocationPoints store

import {create} from "zustand";  import {nanoid} from "nanoid";  interface ILocationPoints {    locations: LocationPoint[],    addLocation: (loc: LocationPoint) => void,    editLocation: (loc: LocationPoint) => void,    
removeLocation: (id: string) => void  }  interface LocationPoint{    id: string,    name: string,    lng: string,    
lat: string  }    export const useLocationPoints = create<ILocationPoints>(set => ({    locations: [] as LocationPoint[],    addLocation: (loc: LocationPoint) => {    const _id  = nanoid()    loc["id"] = _id    set(state => ({    locations: [...state.locations, loc]    }));    },    editLocation: (loc: LocationPoint)=>{    set(state => ({    locations: state.locations.map(item=>{    if(item.id === loc.id){    return {    ...loc,    id: item.id,    }    }else {    return item    }    })    }));    },    
// 移除location    removeLocation:(id:string)=>{    set(state => ({    locations: state.locations.filter(item=>item.id !== id)    }));    
}  }));

对于location的增删改，均依赖于以上store实现。单页面定义React自带的useState当然也可以，但是为了便利于组件拆分，所以使用store，不用再跨组件管理状态的提交、更新、监听等，方便了很多。
考虑到location的名称、经纬度均有可能更改，所以使用nanoid生成唯一id进行location的索引。

2.2 引入Convex

使用convex作为平台后台。convex可以提供数据库存储、RESTful接口及接口调试的功能。

2.2.1 Convex 项目配置

访问Convex
创建app
在nextjs项目中，进行相应的配置。
参考Convex官方文档：
Next.js Quickstart | Convex Developer Hub

# 进入项目目录后，安装  
cd my-app && npm install convex  
npx convex dev

因为我已经在Convex控制台中创建过app了，所以选择已存在的project

2.2.2 Table Schema定义和数据初始化

在Convex目录下，新建·文件schema.ts

import { v } from "convex/values";  
import {defineSchema, defineTable} from "convex/server";  export default defineSchema({  locations: defineTable({        // 经纬度  name: v.string(),        //  经度  lng: v.number(),        // 纬度  lat:v.number(),  })        .index("by_name",["name"])        .searchIndex("search_by_name",{            searchField: "name",            filterFields: ["name"]        }),});

如上所示，定义了一个名称为“locations”的数据表，有name、lng、lat三个字段，并定义了查询的规则（by_name）
运行npx convex dev后，会发现Convex控制台中已经生成了该表。
我从网上找到了一些世界范围内的经纬度数据，是csv格式。通过python处理成出初始化数据。
小技巧：对于不同格式的csv，在第一行定义与字段相匹配的表头即可快速处理。

import json    import pandas as pd    data = []  csv_data = pd.read_csv('globalcities.csv',header=0,encoding="utf-8")    # {"name": "上海", "lng":  121.47,"lat":31.23}  with open("global.csv","w",encoding='utf-8') as file:    for index, row in csv_data.iterrows():    d = {    "name": row["城市名中文"] ,    "lng":row["经度"],    "lat":row["纬度"]    }    file.write(json.dumps(d,ensure_ascii=False) )    print(json)

执行导入：

npx convex import --table locations convex/init.jsonl```如下图所示，数据导入完成！  ![image.png](https://cdn.jsdelivr.net/gh/Ygria/Pictures@main/20240425220013.png)  #### 2.2.3 查询接口定义和使用  在convex文件夹下，新建文件location.ts，定义一个get查询接口  
```javascript  
import { v } from "convex/values";  import { query } from "./_generated/server"    export const get = query({    args:{    // orgId: v.string(),    // search: v.optional(v.string()),        // favorites: v.optional(v.string())        name: v.string()    },    handler: async (ctx,args) => {    let locations = [];    locations = await ctx.db.query("locations")    .withSearchIndex("search_by_name", (q) =>    q.search("name", args.name)).take(10);    return locations;    
}  })

运行npx convex dev进行接口的生成。
接口使用：（value为useState定义的动态值，绑定地点input输入框）

const queryResult =  useQuery(api.locations.get, {name: value});

在模版代码中遍历查询结果：

{    queryResult?.map(res => (    <Badge variant="outline" key = {res._id} onClick={event => handleClick(event, res)}>    {res.name } [<span className = "text-red-300">{res.lng}</span>,<span className = "text-green-800">{res.lat}</span>]    </Badge>    
))  }

实现效果如下图所示，输入内容后value更新，就会触发接口调用，出现候选地点供用户选择。

2.3 引入高德API

由于上一步的地点不一定全，也由于限定了仅显示前10条，故而又引入高德api进行查询。（有局限：无法查询国外地名）

2.3.1 高德开放平台

新建应用

创建key（web端使用的key）

使用该配置好的key就可以调用高德的接口了，每天有免费五千次的额度，对于一个小demo完全够用了。

2.3.2 调用高德接口

gaode.ts

// 调用接口    interface GaodeRes {    formatted_address: string,    
location: string  }    export const getGeoCode = async (address: string) : Promise<GaodeRes[]> => {    let result = await fetch(`https://restapi.amap.com/v3/geocode/geo?address=${address}&key={}`,{    headers: {    Accept: 'application/vnd.dpexpo.v1+json' //设置请求头    },    method: 'get',    })    let res = await result.json() //必须通过此方法才可返回数据    
return res.geocodes;  }

该接口设定为点击查询按钮时才触发（节约次数）。

const [gaodeQueryResult,setGaodeQueryResult] = useState([]);  const searchGeoCode = () =>{    let queryResult = getGeoCode(value);    queryResult.then(res=>{    if(res && res.length > 0){    let data  = res.map(item=>{    return {    "name": item.formatted_address,    "lng": item.location.split(",")[0],    "lat": item.location.split(",")[1],    }    })    setGaodeQueryResult(data)    }else{    setGaodeQueryResult([])    toast.error("未能查询到该地点！您可以通过经纬度进行查询。")    }    })    }

同样将结果在模版代码中遍历展示即可。

2.4 通过经纬度增加

如果查询不到，实现了点击“经纬度”展开，自行输入经纬度定义标记点的功能。值得一提的是使用了ShadUI的InputOTP组件，可以规定输入的位数和正则，我规定了只可以输入负号、小数点和数字。

2.5 标记点的删除和编辑

悬停状态才显示编辑和删除按钮。

<div className = "flex gap-x-2 m-2 relative group" ref={drag}    style={{    opacity: isDragging ? 0.5 : 1,    }}><MapPin />{name}    <button className = "opacity-0 group-hover:opacity-100" onClick={()=>onOpen(id,name,lng,lat)} ><Pencil size = "16"></Pencil> </button>    
<button className = "opacity-0 group-hover:opacity-100" onClick={onRemove} ><X size = "16"></X> </button>  </div>

定义useEditModal，控制编辑Modal的显示和方法。

import {create} from "zustand";  const defaultValues = {    name: "",    lng: "",    lat: "",    
id: ""  };    interface IEditModal {    isOpen: boolean;    initialValues: typeof defaultValues;    onOpen: (id:string,name:string,lng: string,lat: string) =>void;    
onClose: () => void;  }    export const useEditModal = create<IEditModal>((set) =>({    isOpen: false,    onOpen:(id:string,name,lng,lat)=>set({    isOpen:true,    initialValues: {id,name,lng,lat}    }),    onClose: ()=>set({    isOpen: false,    initialValues: defaultValues    }),    initialValues: defaultValues    }))

2.2 定义路线（react dnd）

用户可以拖拽地点到虚线框内，形成路线。路线图的增删改同样适用zustand实现，不加赘述。拖动点到路线框中形成路线，使用了react drag and drop库完成。

npm install react-dnd```
引入react dnd后，将使用到拖拽的部分使用如下provider包裹。  
```html  
<DndProvider backend={HTML5Backend}></DndProvider>

参考官方示例写法，拖部分：(location.tsx)

import { useDrag } from 'react-dnd'  
const [{ isDragging, }, drag, preview] = useDrag(    () => ({    type: ItemTypes.Location,    item: { name: name,id:id } ,    collect: (monitor) => ({    isDragging: !!monitor.isDragging(),    }),    }),    
[],  )

放部分：

import {Overlay, OverlayType} from "@/app/components/Overlay";  
import { useDrop} from 'react-dnd'  
const [{ isOver,canDrop }, drop] = useDrop(    () => ({    accept: ItemTypes.Location,    canDrop: (item:{name: string,id:string}) => {    if(!lineData || lineData.length == 0){    return true    }else{    return lineData[lineData.length - 1]?.id !== item.id    }    },    drop: (item:{name: string,id:string}) => {    dropLocation(id, item)    },    collect: (monitor) => ({    isOver: !!monitor.isOver(),    canDrop: !!monitor.canDrop(),    }),    }),    
[lineData],  )

在模版代码中，增加了Overlay并根据是否可以放的状态，给不同的颜色。

{isOver && !canDrop && <Overlay type={OverlayType.IllegalMoveHover} />}  {!isOver && canDrop && <Overlay type={OverlayType.PossibleMove} />}  {isOver && canDrop && <Overlay type={OverlayType.LegalMoveHover} />}

Overlay.js

export var OverlayType  ;(function (OverlayType) {    OverlayType['IllegalMoveHover'] = 'Illegal'    OverlayType['LegalMoveHover'] = 'Legal'    
OverlayType['PossibleMove'] = 'Possible'  })(OverlayType || (OverlayType = {}))  export const Overlay = ({ type }) => {    const color = getOverlayColor(type)    return (    <div    className="overlay"    role={type}    style={{    position: 'absolute',    top: 0,    left: 0,    height: '100%',    width: '100%',    zIndex: 1,    opacity: 0.5,    backgroundColor: color,    }}    />    
)  }  function getOverlayColor(type) {    switch (type) {    case OverlayType.IllegalMoveHover:    return 'red'    case OverlayType.LegalMoveHover:    return 'green'    case OverlayType.PossibleMove:    return '#66CC66'    
}  }

当所拖拽的地点与路线合集中最后一个地点一样时，不允许拖拽进入。

3 地图渲染（echartgl）

使用react-echart，并导入echart-gl，实现3D地图渲染。

<ReactEcharts    option={options}    style={{ width: "900px", height: "800px" }}    ></ReactEcharts>

  const [options,setOptions] = useState({    backgroundColor: "#000",    globe: {    baseTexture:"/earth1.jpg",    shading: "lambert",    atmosphere: {    
// 不需要大气光圈去掉即    show: false,    
offset: 4, // 大气层光圈宽度    },    viewControl: {    
distance: 200, // 默认视角距离地球表面距离    },    light: {    ambient: {    
intensity: 1, // 全局的环境光设置    },    main: {    
intensity: 1, // 场景主光源设置    },    },    },    })

使用useState，根据lineCollection、location数据，动态地增、减地图options。

useEffect(() => {    let series = initSeries;    series[0].data = normalData(lines);    series[1].data = activeData(lines);    locations.forEach((item) => {    series[2].data.push({    name: item.name,    value: [item.lng,item.lat]    });    });    setOptions({    ...options,    ...customTheme,    series: series    })    }, [locations,lineCollections,customTheme]);

3.1 地球换皮肤

更换贴图，即可实现地球换皮肤。
从网上搜罗一些地球贴图，放入public目录即可。

const themeTopics  = [{    globe: {    baseTexture: "/earth1.jpg",    },  },    {    globe: {    baseTexture: "/earth2.jpg",    },    },    {        globe: {    baseTexture: "/earth3.jpg",         },    },    {         globe: {    baseTexture: "/earth4.jpg",     },    
}  ]

部署

使用vercel作为部署托管。进入vercel并授权github项目，配置NextJS项目的构建命令。
由于我在github的项目源码没有放在根目录，所以还需要设置root-directory。

将所使用到的环境变量放在environment-variables中。

需要注意的是，Convex需要生成部署生产使用的URL和KEY，并配到环境变量中。

这样就完成啦～

源码地址

https://github.com/Ygria/travel-trace

小结

写的第一个相对完整的react小项目，麻雀虽小五脏俱全。使用合理的开源组件让全栈变得非常容易。
只使用到了react useState和useEffect两个hooks，已经感觉到了一定的理解门槛，与vue的将许多状态处理都放在内部封装好相比，react很多时候需要你自己来理解状态的依赖关系然后处理。react的tsx函数式写法的确很方便（比vue的defineComponents好多了……）。期待随着学习深入，了解到更多有趣的东西。

参考

echart assets
https://github.com/ecomfe/echarts-gl/tree/master/test/asset
全流程开发参考：
https://www.codewithantonio.com/courses/88ee3ccc-afd7-414b-a626-e59c93847f65/chapters/b2fb3143-9683-465d-ad49-04f92011a107
echarts+echarts-gl实现带有散点、路径的3d地球
https://download.csdn.net/download/weixin_45669156/86248540?ydreferer=aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NTY2OTE1Ni9hcnRpY2xlL2RldGFpbHMvMTI1OTMyNjAx