Map 地图组件

MapLibre 驱动的地图容器组件，支持标记、弹窗、提示、路线和控件。

Map 是根容器组件，它初始化 MapLibre GL 并为子组件提供上下文。自动处理浅色和深色模式之间的主题切换。

基本用法

最简单的地图只需要设置中心坐标和缩放级别：

MyMap.tsx
1234567891011
import { Map, MapControls } from class="tk-string">"@/components/ui/map";

export function MyMap() {
  return (
    <div className=class="tk-string">"h-[320px] overflow-hidden rounded-lg">
      <Map center={[-74.006, 40.7128]} zoom={11}>
        <MapControls />
      </Map>
    </div>
  );
}

空白模式

使用 blank 属性创建透明、无瓦片的画布。单独使用时不渲染任何内容，你需要添加自己的图层。

BlankMap.tsx
1234567891011121314
import { Map, MapGeoJSON } from class="tk-string">"@/components/ui/map";

const WORLD_GEOJSON =
  class="tk-string">"https:class="tk-commentclass="tk-string">">//cdn.jsdelivr.net/gh/nvkelso/natural-earth-vector@v5.1.2/geojson/ne_110m_admin_0_countries.geojson";

export function BlankMap() {
  return (
    <div className=class="tk-string">"h-[320px] overflow-hidden rounded-lg">
      <Map blank center={[0, 0]} zoom={1}>
        <MapGeoJSON data={WORLD_GEOJSON} />
      </Map>
    </div>
  );
}

自定义样式

使用 styles 属性指定自定义地图样式：

CustomStyleMap.tsx
12345678910111213141516
import { Map } from class="tk-string">"@/components/ui/map";

export function CustomStyleMap() {
  return (
    <div className=class="tk-string">"h-[320px] overflow-hidden rounded-lg">
      <Map
        center={[-74.006, 40.7128]}
        zoom={11}
        styles={{
          light: class="tk-string">"https:class="tk-commentclass="tk-string">">//maps.tilehosting.com/styles/positron/style.json?key=YOUR_KEY",
          dark: class="tk-string">"https:class="tk-commentclass="tk-string">">//maps.tilehosting.com/styles/dark-matter/style.json?key=YOUR_KEY",
        }}
      />
    </div>
  );
}

主题控制

默认情况下，Map 会自动从文档类名或系统偏好中检测主题。你也可以通过 theme 属性手动指定：

123
<Map center={[-74.006, 40.7128]} zoom={11} theme=class="tk-string">"dark">
  <MapControls />
</Map>

3D 地球视图

使用 projection 属性启用 3D 地球视图：

1234567
<Map
  center={[0, 20]}
  zoom={1}
  projection={{ type: class="tk-string">"globe" }}
>
  <MapControls showZoom showCompass />
</Map>

受控视口

使用 viewport 和 onViewportChange 实现受控模式：

ControlledMap.tsx
123456789101112131415161718
import { Map, type MapViewport } from class="tk-string">"@/components/ui/map";
import { useState } from class="tk-string">"react";

export function ControlledMap() {
  const [viewport, setViewport] = useState<MapViewport>({
    longitude: -74.006,
    latitude: 40.7128,
    zoom: 11,
  });

  return (
    <Map
      viewport={viewport}
      onViewportChange={setViewport}
      className=class="tk-string">"h-[320px]"
    />
  );
}

加载指示器

使用 loading 属性显示加载指示器：

1
<Map center={[-74.006, 40.7128]} zoom={11} loading />

属性

Map 组件继承了 MapLibre GL 的MapOptions（排除 container 和 style）。

属性	类型	默认值	描述
`children`	`ReactNode`	—	子组件（标记、弹窗、控件、路线）
`className`	`string`	—	地图容器的额外 CSS 类名
`theme`	`"light" \| "dark"`	自动检测	地图主题。未提供时从文档类名或系统偏好自动检测
`styles`	`{ light?: string \| StyleSpecification; dark?: string \| StyleSpecification }`	—	自定义地图样式，覆盖默认 CARTO 底图
`blank`	`boolean`	`false`	使用透明、无瓦片的底图。需要添加自己的图层
`projection`	`ProjectionSpecification`	—	地图投影类型。使用 `{ type: "globe" }` 启用 3D 地球
`viewport`	`Partial<MapViewport>`	—	受控视口状态。与 onViewportChange 配合实现受控模式
`onViewportChange`	`(viewport: MapViewport) => void`	—	视口变化时的回调函数
`loading`	`boolean`	`false`	在地图上显示加载指示器

下一步

控件

MapControls 组件