mapcn

mapcn

通过 shadcn CLI 安装的 React 地图组件。所有内容都位于一个文件 components/ui/map.tsx 中，基于 MapLibre GL 构建，并采用项目的 shadcn 主题样式。区块是使用这些组件构建的完整页面，例如仪表板、追踪器和定位器。

用户尚未指定地图用途时

如果用户询问 mapcn 能为其应用做什么，或者地图适合放在哪里：

1. 查看技术栈（package.json、components.json），并快速浏览页面和数据模型。
2. 按显眼程度从高到低，建议 2–4 个适合放置地图的位置。结合代码中已有的实际内容，并说明会使用什么组件或区块，例如：
   • 地址或地点，可制作 Store Locator，或带弹出窗口的标记
   • 订单或货运，可制作 Delivery Tracker（MapRoute + RouteProgress）
   • 按国家或地区统计的数据，可制作 Choropleth 或 Analytics Map
   • 地点之间的连接（航班、交通、供应链），可使用 MapArc 或 Logistics Network
3. 只安装并构建用户选定的内容。

开始之前

1. shadcn/ui 和 Tailwind CSS。 检查 components.json。如果不存在，告知用户 mapcn 需要 shadcn/ui，并提出先运行 npx shadcn@latest init。
2. 是否已安装？ 检查 components.json 中的 aliases.ui（通常是 @/components/ui）下是否有 map.tsx。如果有，不要重复安装，而是先阅读该文件。

安装

npx shadcn@latest add @mapcn/map

这会添加 components/ui/map.tsx、安装 maplibre-gl，并在全局 CSS 中添加一些弹出窗口和版权归属样式。区块的安装方式相同：npx shadcn@latest add @mapcn/<block>，并会自行引入地图组件。区块文件会安装到 Next.js App Router 路径（app/<route>/page.tsx）。如果使用其他配置，请移动文件并注册路由：参见 references/blocks.md。

切勿手动编写或粘贴 map.tsx。如果 CLI 执行失败，请阅读 https://mapcn.dev/r/map.json，安装其中列出的依赖项，并说明失败原因。

规则

• 为地图设置高度。 <Map> 会填满父元素，而没有高度的父元素不会显示任何内容。请将它包在 <div className="h-[400px]"> 或 <Card className="h-[320px] overflow-hidden p-0"> 中。
• 坐标顺序为 [longitude, latitude]。 center={[-74.006, 40.7128]} 表示纽约。标记使用 longitude 和 latitude 属性。调换顺序是最常见的错误。
• 仅限客户端组件。 map.tsx 已经包含 "use client"。任何使用 useMap、引用或地图事件处理程序的组件也需要它。在 Next.js 中，请将数据获取放在服务端组件中，再将数据传入客户端。
• 属性已在已安装的 map.tsx 中记录。 每个属性都有 JSDoc 注释。请阅读其中的类型定义，不要凭猜测使用。除非用户提出要求，否则不要编辑该文件。
• 路由组件不负责获取数据。 MapRoute 只绘制传入的坐标；RouteProgress 和 RouteMarker 放在其中，并基于同一条线路工作。请在父组件中获取路线（OSRM、Mapbox、Google），再传入 [lng, lat][]。参见 references/components.md 中 Routes 部分链接的 OSRM 示例。MapGeoJSON 和 MapClusterLayer 接受 GeoJSON 对象或 URL。
• 在自定义界面中使用主题颜色。 标记内容、弹出窗口和叠加层都是普通 React 内容，因此请使用 bg-background、text-muted-foreground、border 等类。线路和填充区域上的数据颜色（MapRoute color、paint 属性）可以使用实际颜色值。
• 主题跟随应用设置。 底图会根据 <html> 上的 dark 或 light 类，或 data-theme 属性切换明暗主题（开箱即支持 next-themes）；如果未设置，则使用系统偏好。只有在需要强制指定主题时才传入 theme。
• 需要时可直接使用 MapLibre： 在 <Map> 内调用 useMap() 会返回 { map, isLoaded }，也可以将 ref（MapRef）传给 <Map>。添加数据源或图层前，请等待 isLoaded，并在清理时移除它们。

底图选择

• 使用不带 blank 的 <Map>，以使用默认的免费 CARTO 底图瓦片。这最适合门店定位、配送跟踪、物流地图、地址地图，以及用户需要街道、地点标签或地理背景的任何 UI。
• 使用 <Map blank> 创建透明且不含瓦片的画布。单独使用时不会渲染任何内容；添加自己的图层，例如 MapGeoJSON、MapArc、标记、集群或自定义 MapLibre 图层。最适合分级统计地图、弧线地图、点地图、仪表板和数据可视化，这些场景应由数据定义地理信息。
• 如果用户需要仅显示国家或国界的空白地图，请将 <Map blank> 与 <MapGeoJSON data={WORLD_GEOJSON} /> 搭配使用。对于世界各国，Natural Earth GeoJSON 数据源很适用：https://cdn.jsdelivr.net/gh/nvkelso/[email protected]/geojson/ne_110m_admin_0_countries.geojson。用户也可以向 MapGeoJSON 提供自己的 GeoJSON URL 或 GeoJSON 对象。
• 使用 styles 属性指定自定义的 MapLibre 兼容样式 URL 或样式对象，例如 MapTiler、OpenFreeMap、CARTO 或可自托管的样式。显式设置的 styles 会覆盖 blank。

组件

所有内容均从 @/components/ui/map 导入：

• 地图： Map、useMap
• 控件： MapControls
• 标记： MapMarker、MarkerContent、MarkerPopup、MarkerTooltip、MarkerLabel
• 弹出窗口： MapPopup
• 路线： MapRoute、RouteProgress、RouteMarker
• 弧线： MapArc
• GeoJSON： MapGeoJSON
• 集群： MapClusterLayer

参考资料

只阅读任务所需的内容。与其从已安装的技能中阅读，不如从 URL 阅读？相同的文件位于 https://raw.githubusercontent.com/AnmolSaini16/mapcn/main/skills/mapcn/references/。

• references/components.md：每个导出项的用途、文档页面以及示例源代码链接
• references/blocks.md：每个区块的展示内容、添加的文件及其安装命令
• references/patterns.md：受控视口、飞行定位、路线获取、自定义图层、大型数据集、Web Worker 和 CSP