mcpField
M
mapcn

mapcn

github.com/ferminrp开发3999 次安装13 周前更新
代码仓库

关于 mapcn

mapcn 是面向 React 与 shadcn/ui 项目的地图组件技能，帮助编码 Agent 安装、集成、定制和排查 mapcn。它基于 MapLibre GL JS，默认使用无需 API 密钥的 CARTO 瓦片。

主要功能

  1. 01集成 MapLibre 地图组件
  2. 02配置缩放、罗盘和定位控件
  3. 03组合标记、弹出框与提示
  4. 04绘制路线并聚合 GeoJSON 点
  5. 05通过 MapRef 与 useMap 操作地图

适用场景

  1. 01在 React 与 shadcn/ui 项目加入地图
  2. 02添加标记、弹出框或路线
  3. 03在密集点数据中使用聚合图层
  4. 04排查地图空白或控件缺失

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ferminrp/agent-skills --skill mapcn

安装后在 Claude Code 中输入/mapcn确认已加载。

附带文件references/api-cheatsheet.mdreferences/docs-pages.md

详细介绍

mapcn

何时使用此技能

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

常见触发词：

  • integrate mapcn
  • add mapcn to shadcn project
  • mapcn MapControls/Markers/Routes/Clusters
  • controlled map viewport with mapcn
  • useMap hook mapcn
  • MapLibre with mapcn components

库概述

mapcn 提供基于 MapLibre GL JS 构建、与 shadcn/ui 工作流保持一致的地图组件，采用复制粘贴式的使用方式。

前提条件：

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

默认行为：

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

安装

标准安装命令：

npx shadcn@latest add @mapcn/map

预期集成结果：

  • 地图 UI 组件会添加到项目中（通常位于 components/ui 下）。
  • 导入方式通常如下：
import { Map } from "@/components/ui/map";

快速开始

使用固定高度的容器，并渲染 Map 和 MapControls。

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>
  );
}

重要提示：

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

核心组件

Map 和受控视口

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

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

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

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

  • showZoom
  • showCompass
  • showLocate
  • showFullscreen
  • position
标记及标记 UI 组件系列

使用标记组合来构建更丰富的 UI：

  • MapMarker
  • MarkerContent
  • MarkerPopup
  • MarkerTooltip
  • MarkerLabel
独立弹出窗口

使用 MapPopup 来显示未严格绑定到标记组件的弹出窗口 UI。

路线

使用 MapRoute 绘制基于路径的叠加层和类似路线的线条。

聚类

对密集点数据集使用 MapClusterLayer 和 GeoJSON 输入。

高级集成

MapRef

使用 MapRef 执行命令式地图操作，例如 flyTo、自定义相机过渡和直接操作地图实例。

useMap

使用 useMap 安全地访问地图上下文，并以符合生命周期的方式注册和清理事件监听器。

自定义样式

当默认瓦片无法满足需求时，使用 styles 属性（或相应的地图样式配置选项），并指定兼容 MapLibre 的样式 URL/规范。

性能指南

  • DOM 标记适用于中小规模数据量（通常最多几百个点）。
  • 对于大型数据集，优先使用基于 GeoJSON 图层的渲染和聚类（MapClusterLayer）。
  • 稳定属性和处理函数，避免过度重新渲染。
  • 使用高级地图事件时，务必清理事件监听器。

故障排除

地图空白

请检查：

  • 是否为容器明确设置了高度。
  • 样式 URL/规范是否有效。
  • 瓦片请求是否被阻止（网络/CORS）。
Hydration / 应用框架问题
  • 确保在 SSR 应用配置中以兼容客户端的方式渲染地图。
  • 在挂载前避免直接访问地图实例。
控件或标记缺失
  • 确认组件嵌套在正确的地图上下文中。
  • 核实标记和弹出窗口组件的子级层次结构是否符合预期。
类型/坐标错误
  • 验证坐标的形状和顺序，以及属性类型。
  • 确保回调函数签名与组件预期一致。

Agent 工作流

  1. 判断用户意图：安装、基础地图、标记、弹出窗口、路线、聚类或高级事件。
  2. 首先实现最小可用集成。
  3. 仅在需要同步状态时切换到受控视口。
  4. 点的数量增加时，切换到聚类/图层模式。
  5. 返回简洁的代码，然后说明决策和后续步骤。

不在范围内

  • 非 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

评论

支持 Markdown