框架集成与 TypeScript

501字约2分钟

2026-10-20

本页目标

已经会用 new mars2d.Map 之后，在 Vue / React 等框架中如何正确集成，以及 TypeScript 项目的类型支持。

通用的 NPM / 静态 / CDN 集成方式，请先阅读1-NPM方式集成、2-静态方式集成、3-CDN方式集成。本页聚焦“在框架组件里怎么用”。

1. 通用原则

地图容器 DIV 必须有明确高度（height: 100% 或固定像素）。
一个容器只创建一个地图实例，组件卸载时销毁（map.destroy()）。
不要把地图实例放进响应式深层监听，避免频繁重渲染。
不要用 mars2d 作为自己的变量名。

2. Vue3

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

<script setup>
import { onMounted, onUnmounted } from "vue"
import * as mars2d from "mars2d"

let map = null

onMounted(() => {
  map = new mars2d.Map("mars2dContainer", {
    zoom: 13,
    center: { lng: 117.240601, lat: 31.827107 }
  })
})

onUnmounted(() => {
  if (map) {
    map.destroy()
    map = null
  }
})
</script>

<style scoped>
.mars2d-container { width: 100%; height: 100%; }
</style>

3. React

import { useEffect, useRef } from "react"
import * as mars2d from "mars2d"

export default function MapView() {
  const mapRef = useRef(null)

  useEffect(() => {
    const map = new mars2d.Map("mars2dContainer", {
      zoom: 13,
      center: { lng: 117.240601, lat: 31.827107 }
    })
    mapRef.current = map

    return () => {
      map.destroy()
      mapRef.current = null
    }
  }, [])

  return <div id="mars2dContainer" style={{ width: "100%", height: "100%" }} />
}

4. TypeScript

Mars2D 包内自带类型声明文件 mars2d.d.ts，NPM 方式安装后可直接获得类型提示：

import * as mars2d from "mars2d"

const map: mars2d.Map = new mars2d.Map("mars2dContainer", {
  zoom: 13,
  center: { lng: 117.240601, lat: 31.827107 }
})

const layer = new mars2d.layer.GraphicLayer()
map.addLayer(layer)

静态/CDN 集成时，把 mars2d.d.ts 放到项目里并在 tsconfig.json 的 types 或 include 中声明即可获得提示。
自定义扩展类时，可继承 mars2d.graphic.* / mars2d.layer.* 并参考官方示例。

注意事项

注意

在 Vue / React 中，务必在卸载钩子里调用 map.destroy()，否则切换页面后地图容器与事件监听会残留，导致内存持续上涨。