前言

在 Web 前端，"给页面加一张可交互的地图"似乎从来都不是一件轻松的事。开发者往往要在「引入一个庞大的地图 SDK」「配置 API Key」「与一堆命令式 API 搏斗」之间反复横跳。mapcn 试图把这件事变得更像写普通 UI：组件化、可组合、可定制，且代码归你所有。

mapcn 是一套免费、开源、可复制粘贴的 React 地图组件库。它构建于 MapLibre GL 之上，使用 Tailwind CSS 进行样式设计，并刻意契合 shadcn/ui 的使用习惯。你不必把整座地图引擎"安装"进项目，只需要把需要的组件文件复制进来，它们就是你的代码——这正是它区别于传统地图 SDK 的根本之处。

本书的由来，是想给中文世界的 React 开发者一本"既能入门、又能进阶"的 mapcn 专著。它的内容完全建立在 mapcn 官方文档的基础之上——我们通读了项目文档，并按"由浅入深、面面俱到"的原则重新编排了章节结构。你读到的每一处组件 API、每一个属性、每一项用法，都尽量回溯到官方文档的对应出处；涉及版本差异或行为约束处，也如实标注。

全书分为四个部分、共十四章：

• 第一部分 入门与环境（第 1–2 章）：从 mapcn 是什么、它和主流方案有何不同，到环境准备、安装与项目脚手架，为后续打下地基。
• 第二部分 地图基础与交互（第 3–6 章）：渲染第一张地图，掌握地图控件与视口交互，使用标记点（Marker）、弹窗（Popup）与提示框（Tooltip）。
• 第三部分 图形与数据（第 7–10 章）：用路线（Route）与弧线（Arc）连接点位，用 GeoJSON 绘制区域地图，以及海量点的聚合（Cluster）渲染。
• 第四部分 进阶与实战（第 11–14 章）：深入 MapLibre 实例与 useMap，自定义主题与底图，性能优化与最佳实践，并以一个完整的"门店地图应用"收尾。

阅读建议：完全的初学者建议从第 1 章顺序读到第 6 章，把基础打牢；有一定 React 或地图开发经验的读者，可以跳过前几章的入门铺垫，直接从交互或图形数据部分切入；希望理解"组件之下发生了什么"的读者，第四部分值得精读。每章末尾都配有"本章小结"，便于复习与速查。

书中的代码示例以"可运行、可复现"为第一原则，默认基于 mapcn 当前文档所对应版本；涉及版本差异处均显式标注。建议读者在自己的项目中动手敲一遍代码——mapcn 的"复制即拥有"特性，让这种即时实验的成本几乎为零。

最后说明：本书由 AI 辅助文档生成流程编撰而成，内容力求准确、并已尽量对照官方文档核验；但在涉及生产环境的关键决策（如性能调优、数据安全、版本升级）时，仍请以官方文档与社区的最新结论为准。