3 步搭出生产级地图界面：mapcn React 地图组件完全指南

【免费下载链接】mapcnBeautiful map components. 100% Free, Zero config, one command setup.项目地址: https://gitcode.com/gh_mirrors/map/mapcn

做地图最耗时间的往往不是画点，而是把地图嵌进 React、调好主题、再拼上弹窗和缩放控件，一套下来半天就没了。mapcn把这些封装成一组免费的、零配置的 React 地图组件：它基于 MapLibre GL 绘制、用 Tailwind 和 shadcn/ui 风格着色，一条npx shadcn add命令装完即用。下面按"你要完成的任务"带你从零走到第一个能上线的地图界面。

一条命令，从 0 到第一张地图

这一步解决"怎么在现有 React 项目里跑起第一张地图"。前提是项目已装好 Tailwind CSS 和 shadcn/ui（也就是有components.json）。

装组件只要一行：

npx shadcn@latest add @mapcn/map

它会写入components/ui/map.tsx并自动装好maplibre-gl。接下来给地图一个有高度的容器——<Map>会填满父级，没高度就是一片空白：

<Card className="h-[320px] overflow-hidden p-0"> <Map center={[-74.006, 40.7128]} zoom={11}> <MapControls /> </Map> </Card>

center是[经度, 纬度]。底图默认免费，会跟随你的深浅色主题自动切换，不用额外配置。

让每个点位开口说话：标记、标签与弹窗

真实业务里，一个点通常要同时回答"这是什么"和"详情在哪"。mapcn 用三个子组件各司其职：MarkerContent放图标、MarkerLabel放常驻文字、MarkerPopup放点击后才展开的详情。

以项目里"兴趣点列表"的场景为例，把评分、营业时间这类信息塞进弹窗，图标上加一行常驻标签：

<MapMarker longitude={-73.9772} latitude={40.7527}> <MarkerContent> <div className="size-5 rounded-full border-2 border-white bg-rose-500 shadow-lg" /> <MarkerLabel position="bottom">Transit</MarkerLabel> </MarkerContent> <MarkerPopup className="w-62 p-0"> <p className="text-foreground font-semibold">Grand Central Terminal</p> <p className="text-muted-foreground text-xs">Open 5:15 AM – 2:00 AM</p> </MarkerPopup> </MapMarker>

弹窗里是普通 React 节点，直接套bg-background、text-muted-foreground这类主题色即可，外观立刻跟你的页面统一。完整的多点位写法见 src/app/(main)/docs/_components/examples/markers-example.tsx/docs/_components/examples/markers-example.tsx)。

如果你需要用户"自己拖动定位"，把draggable打开、在onDrag里回写坐标就行，参考 src/app/(main)/docs/_components/examples/draggable-marker-example.tsx/docs/_components/examples/draggable-marker-example.tsx)。

万级点位不糊成一团：用集群层做聚合

点位一多，散点会叠成一坨色块。MapClusterLayer直接把相邻点聚合成一个带计数的圆点，缩放放大时再自动拆开，性能观感都好看很多。

它接一个 GeoJSON 对象或 URL，调两个参数就能用：clusterRadius控制聚合范围，clusterMaxZoom控制到第几级还保持聚合：

<Map center={[-103.59, 40.66]} zoom={3.4}> <MapClusterLayer data={earthquakeData} clusterRadius={50} clusterMaxZoom={14} onPointClick={(feature, coordinates) => setPoint(feature)} /> </Map>

点中某个点后用独立MapPopup弹出详情，data支持直接传 GeoJSON 对象或 URL。完整可运行的地震数据示例在 src/app/(main)/docs/_components/examples/cluster-example.tsx/docs/_components/examples/cluster-example.tsx)。

整块地图功能直接搬进项目：现成的 Blocks

组件适合"嵌一块地图"，但有时候你要的是"一整页"——门店定位、配送追踪、区域分析仪表盘。mapcn 提供了一组可直接安装的Blocks，每块就是一个带数据的完整页面，内部已经组合好上面的组件。

安装方式和组件一致，换个名字即可：

npx shadcn@latest add @mapcn/store-locator

它会落到 Next.js App Router 的app/<route>/page.tsx路径下（其它框架需手动迁移并注册路由）。所有可用 Blocks 及说明见 src/app/(main)/blocks//blocks/) 与 src/lib/blocks.ts。

新手最常踩的 4 个坑

这几处几乎决定了你的地图"为什么显示不出来"，先记牢再动手能省大量排查时间。

主题不用你管：地图读取<html>上的dark/lightclass 或data-theme属性，跟 next-themes 开箱即配；只在需要"强制某一主题"时才传theme。

下一步

打开一个 shadcn 项目，跑一条npx shadcn@latest add @mapcn/map，先用一个带高度的<Card>装出基础地图，再往里加标记与弹窗。

• 全部组件源码与类型：src/registry/map.tsx
• 文档页（安装 / 基础地图 / 标记 / 弹窗 / 集群）：src/app/(main)/docs//docs/)
• 现成地图页面 Blocks：src/app/(main)/blocks//blocks/)
• 让编码 Agent 直接会用 mapcn 的技能说明：skills/mapcn/SKILL.md

【免费下载链接】mapcnBeautiful map components. 100% Free, Zero config, one command setup.项目地址: https://gitcode.com/gh_mirrors/map/mapcn