mapcn

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

mapcn

When to Use This Skill

适用场景

Use this skill when the user needs to install, integrate, customize, or troubleshoot mapcn in a React + shadcn/ui codebase.

Typical triggers:

```
integrate mapcn
```
```
add mapcn to shadcn project
```

mapcn MapControls/Markers/Routes/Clusters

```
controlled map viewport with mapcn
```
```
useMap hook mapcn
```
```
MapLibre with mapcn components
```

当用户需要在React + shadcn/ui代码库中安装、集成、自定义mapcn或排查相关问题时，可使用本技能。

典型触发场景：

```
integrate mapcn
```
（集成mapcn）
```
add mapcn to shadcn project
```
（在shadcn项目中添加mapcn）
```
mapcn MapControls/Markers/Routes/Clusters
```
（使用mapcn的MapControls/Markers/Routes/Clusters组件）
```
controlled map viewport with mapcn
```
（使用mapcn实现受控地图视口）
```
useMap hook mapcn
```
（使用mapcn的useMap钩子）
```
MapLibre with mapcn components
```
（结合mapcn组件使用MapLibre）

Library Overview

库概述

mapcn provides copy-paste style map components built on top of MapLibre GL JS and aligned with shadcn/ui workflows.

Assumptions:

Project uses React.
Tailwind CSS is already configured.
shadcn/ui is already configured.

Default behavior:

mapcn uses free CARTO tiles by default.
No API key is required for the default tile setup.

mapcn提供基于MapLibre GL JS构建的、可直接复制使用的地图组件，且与shadcn/ui的工作流保持一致。

前置假设：

项目已使用React
已配置Tailwind CSS
已配置shadcn/ui

默认行为：

mapcn默认使用免费的CARTO瓦片
默认瓦片设置无需API密钥

Installation

安装步骤

Canonical install command:

bash

npx shadcn@latest add @mapcn/map

Expected integration result:

UI map components are added to the project (typically under
```
components/ui
```
).
Import pattern usually follows:

import { Map } from "@/components/ui/map";

标准安装命令：

bash

npx shadcn@latest add @mapcn/map

预期集成结果：

UI地图组件将被添加到项目中（通常位于
```
components/ui
```
目录下）
导入方式通常如下：

import { Map } from "@/components/ui/map";

Quick Start

快速开始

Use a fixed-height container and render

Map

with

MapControls

tsx

import { Map, MapControls } from "@/components/ui/map";

export function BasicMap() {
  return (
    <div className="h-[500px] w-full overflow-hidden rounded-xl border">
      <Map
        initialViewState={{
          longitude: -58.3816,
          latitude: -34.6037,
          zoom: 11,
        }}
      >
        <MapControls
          showZoom
          showCompass
          showLocate
          showFullscreen
          position="top-right"
        />
      </Map>
    </div>
  );
}

Important:

The map container must have an explicit height, otherwise the map may render blank.

使用固定高度的容器，并结合

MapControls

渲染

Map

组件。

tsx

import { Map, MapControls } from "@/components/ui/map";

export function BasicMap() {
  return (
    <div className="h-[500px] w-full overflow-hidden rounded-xl border">
      <Map
        initialViewState={{
          longitude: -58.3816,
          latitude: -34.6037,
          zoom: 11,
        }}
      >
        <MapControls
          showZoom
          showCompass
          showLocate
          showFullscreen
          position="top-right"
        />
      </Map>
    </div>
  );
}

重要提示：

地图容器必须设置明确的高度，否则地图可能会显示为空白。

Core Components

核心组件

Map and Controlled Viewport

地图与受控视口

Use uncontrolled mode for simple cases, and controlled mode when state synchronization is needed.

tsx

const [viewport, setViewport] = useState({
  longitude: -58.3816,
  latitude: -34.6037,
  zoom: 11,
});

<Map viewport={viewport} onViewportChange={setViewport} />

简单场景下使用非受控模式，需要状态同步时使用受控模式。

tsx

const [viewport, setViewport] = useState({
  longitude: -58.3816,
  latitude: -34.6037,
  zoom: 11,
});

<Map viewport={viewport} onViewportChange={setViewport} />

Controls

控制组件

MapControls

supports common toggles and placement:

```
showZoom
```
```
showCompass
```
```
showLocate
```
```
showFullscreen
```
```
position
```

MapControls

支持常见的开关选项和位置设置：

```
showZoom
```
（显示缩放控件）
```
showCompass
```
（显示罗盘控件）
```
showLocate
```
（显示定位控件）
```
showFullscreen
```
（显示全屏控件）
```
position
```
（控件位置）

Markers and Marker UI Family

标记点及相关UI组件

Use marker composition for richer UI:

```
MapMarker
```
```
MarkerContent
```
```
MarkerPopup
```
```
MarkerTooltip
```
```
MarkerLabel
```

通过组件组合实现更丰富的标记点UI：

```
MapMarker
```
```
MarkerContent
```
```
MarkerPopup
```
```
MarkerTooltip
```
```
MarkerLabel
```

Standalone Popups

独立弹出层

Use

MapPopup

for popup UI not strictly attached to a marker component.

当弹出层不需要严格绑定到标记点组件时，可使用

MapPopup

。

Routes

路线组件

Use

MapRoute

to draw path-based overlays and route-like lines.

使用

MapRoute

绘制基于路径的覆盖层和类路线线条。

Clusters

聚合组件

Use

MapClusterLayer

with GeoJSON input for dense point datasets.

对于密集的点数据集，可结合GeoJSON输入使用

MapClusterLayer

。

Advanced Integration

高级集成

MapRef

MapRef

Use

MapRef

for imperative map actions such as

flyTo

, custom camera transitions, and direct map instance operations.

使用

MapRef

执行地图的命令式操作，如

flyTo

、自定义相机过渡效果，以及直接操作地图实例。

useMap

useMap

Use

useMap

to access map context safely and wire event listeners with lifecycle-aware cleanup.

使用

useMap

安全访问地图上下文，并结合生命周期感知的清理机制绑定事件监听器。

Custom Styles

自定义样式

Use

styles

prop (or the corresponding map style config option) with MapLibre-compatible style URLs/specs when default tiles are not enough.

当默认瓦片无法满足需求时，可使用

styles

属性（或对应的地图样式配置选项）传入兼容MapLibre的样式URL或规格。

Performance Guidelines

性能优化指南

DOM markers are fine for small to medium volumes (typically up to a few hundred points).
For large datasets, prefer GeoJSON layer-based rendering and clustering (
```
MapClusterLayer
```
).
Avoid excessive re-renders by stabilizing props and handlers.
Always clean up event listeners when using advanced map events.

DOM标记点适用于中小数据量（通常最多几百个点）
对于大型数据集，建议使用基于GeoJSON图层的渲染和聚合（
```
MapClusterLayer
```
）
通过稳定props和处理函数避免过度重渲染
使用高级地图事件时，务必清理事件监听器

Troubleshooting

问题排查

Blank Map

地图显示空白

Check:

Container height is explicitly set.
Style URL/spec is valid.
Tile requests are not blocked (network/CORS).

检查以下内容：

容器是否设置了明确的高度
样式URL/规格是否有效
瓦片请求是否被拦截（网络/CORS问题）

Hydration / App Framework Issues

水合/应用框架问题

Ensure map rendering is client-safe in SSR app setups.
Avoid direct map instance access before mount.

在SSR应用中，确保地图渲染仅在客户端安全执行
避免在组件挂载前直接访问地图实例

Missing Controls or Markers

控件或标记点缺失

Confirm components are nested under the correct map context.
Verify expected children hierarchy for marker and popup components.

确认组件是否嵌套在正确的地图上下文下
验证标记点和弹出层组件的子元素层级是否符合预期

Type/Coordinate Errors

类型/坐标错误

Validate coordinate shape/order and prop types.
Keep callback signatures aligned with component expectations.

验证坐标的格式/顺序以及属性类型
确保回调函数的签名与组件要求一致

Workflow for Agents

代理工作流

Detect user intent: install, basic map, markers, popups, routes, clusters, advanced events.
Implement the smallest working integration first.
Move to controlled viewport only when state sync is required.
Switch to cluster/layer patterns when point count grows.
Return concise code, then explain decisions and next steps.

识别用户意图：安装、基础地图、标记点、弹出层、路线、聚合、高级事件
先实现最小可用集成
仅当需要状态同步时才切换到受控视口
当点数量增加时，切换到聚合/图层模式
返回简洁代码，然后解释决策依据和后续步骤

Out of Scope

不适用场景

Non-React frameworks.
Unrequested wrapper migration/comparison work.
Hosted map vendor account setup beyond mapcn default/no-key baseline.

非React框架
未被请求的包装器迁移/对比工作
超出mapcn默认/无密钥基线的托管地图供应商账户设置

References

参考资料

Local references:

```
references/docs-pages.md
```
```
references/api-cheatsheet.md
```

Canonical docs:

```
https://www.mapcn.dev/docs
```
```
https://www.mapcn.dev/docs/installation
```

https://www.mapcn.dev/docs/api-reference

```
https://www.mapcn.dev/docs/basic-map
```
```
https://www.mapcn.dev/docs/controls
```
```
https://www.mapcn.dev/docs/markers
```
```
https://www.mapcn.dev/docs/popups
```
```
https://www.mapcn.dev/docs/routes
```
```
https://www.mapcn.dev/docs/clusters
```

https://www.mapcn.dev/docs/advanced-usage

本地参考：

```
references/docs-pages.md
```
```
references/api-cheatsheet.md
```

官方文档：

```
https://www.mapcn.dev/docs
```
```
https://www.mapcn.dev/docs/installation
```

https://www.mapcn.dev/docs/api-reference

```
https://www.mapcn.dev/docs/basic-map
```
```
https://www.mapcn.dev/docs/controls
```
```
https://www.mapcn.dev/docs/markers
```
```
https://www.mapcn.dev/docs/popups
```
```
https://www.mapcn.dev/docs/routes
```
```
https://www.mapcn.dev/docs/clusters
```

https://www.mapcn.dev/docs/advanced-usage