跳到主要内容

mapcn 地图组件库

mapcn 是一个受 shadcn/ui 启发的开源地图组件库，专为 React 打造。它基于 MapLibre GL 和 Tailwind CSS，旨在提供美观、可访问且高度可定制的地图组件。

1. 核心特性​

  • 零配置：开箱即用，内置免费地图瓦片（MapTiler 提供），基础设置无需 API Key。
  • shadcn 原生风格：完全遵循 shadcn/ui 的设计规范，无缝集成到现有的 Tailwind 项目中。
  • 主题适配：完美支持深色模式（Dark Mode），地图样式会随应用主题自动切换。
  • 组合式组件：类似 shadcn 的原子化组件设计，你可以自由组合 Marker、Popup、Controls 等。
  • TypeScript 支持：提供完整的类型定义。

2. 快速开始​

安装依赖​

npm install maplibre-gl mapcn tailwind-merge lucide-react

基础用法事例​

import { Map, Marker, Popup, NavigationControl } from "mapcn";
import "maplibre-gl/dist/maplibre-gl.css";

export default function MyMap() {
  return (
    <div className="h-[500px] w-full border rounded-lg overflow-hidden">
      <Map
        initialViewState={{
          longitude: 116.39,
          latitude: 39.9,
          zoom: 10,
        }}
        mapStyle="https://tiles.openfreemap.org/styles/liberty" // 可选样式
      >
        <NavigationControl position="top-right" />

        <Marker longitude={116.39} latitude={39.9}>
          <div className="text-red-500">📍</div>
        </Marker>

        <Popup longitude={116.39} latitude={39.9} anchor="bottom">
          <p className="p-2">这里是北京</p>
        </Popup>
      </Map>
    </div>
  );
}

3. 核心 API 与 Hooks​

useMap Hook​

通过 useMap 可以直接访问底层的 MapLibre 实例，进行高级操作：

import { useMap } from "mapcn";

const MyMapControl = () => {
  const { current: map } = useMap();

  const flyToHome = () => {
    map?.flyTo({ center: [116.39, 39.9], zoom: 12 });
  };

  return <button onClick={flyToHome}>回到中心</button>;
};

支持的控件​

  • NavigationControl：缩放、罗盘。
  • GeolocateControl：定位当前位置。
  • FullscreenControl：全屏切换。
  • ScaleControl：比例尺。

4. 进阶技巧：自定义地图样式​

由于 mapcn 基于 MapLibre，你可以轻松接入各种矢量瓦片源：

  • OpenFreeMap (默认推荐，免费且精美)
  • MapTiler (需要 API Key，提供高质量商业地图)
  • 自研 OMT 样式 (通过配置文件完全控制地图颜色、图层)

5. 为什么选择 mapcn？​

  1. 开发者体验 (DX)：如果你已经在项目中使用 shadcn/ui，mapcn 的代码风格几乎没有任何学习成本。
  2. 轻量快捷：相比 Google Maps 或 Mapbox 的笨重 SDK，它更符合现代前端的组件化思维。
  3. 免费额度：配合免费瓦片源，可以极大降低早期项目的地图成本。

相关资源：