@ getsoren/ 地图
Mapbox GL JS上方建有现代轻量级React地图库并反应-map-gl. 设计简单,灵活,有视觉优雅.
容易地结合了标记,路线,GeoJSON特征,同位素,和最接近的点数计算——都有一个宣告性,型号安全的API.
* 安装
npm install @getsoren/map
或者说
yarn add @getsoren/map
或者说
bun add @getsoren/map
所需经费
| 依赖性 | 版本 | 目的 |
|---|---|---|
react | 17+/18+/19+ (英语) | 核心反应运行时间 |
react-dom | 17+/18+/19+ (英语) | 反应 DOM 渲染 |
mapbox-gl | ≥ 3.0.0 | 映射引擎 |
@getsoren/design-system | ≥ 4.0.0 | UI 主题和组件 |
@mui/icons-material | * 联合国 | 材料用户界面图标 |
@mui/x-license | * 联合国 | MUI X 许可证整合 |
🪶 您还需要一个 Mapbox 访问符 用来制作地图。 来一个 marpbox.com (英语)。 。 。 .
* 特性
✅ 声明性 API ——用简单的道具管理复杂的地图互动
✅ 标记弹出( P) ——可自定义的 React 组件或基于图像的图标
✅ 运行和异色龙 ——可视化出行时间区或计算出最佳路线
✅ 地层 ——动态渲染矢量数据
✅ 最接近的标记搜索 - 立即发现和突出最接近的点
✅ 类型安全 API ——智能IntelliSense的完整类型脚本支持
✅ 响应设计 ——自动适应任何容器或屏幕大小
✅ 为履约而建 ——最少重交,高效地图更新
✅ 多个运行引擎 ——支持 OSRM (免费) 和 Mapbox 方向 API
✅ 灵活映射样式 – 使用 Mapbox 样式、 OpenStreetMap 或自定义光栅砖
QQ 快速启动
import { MapProvider, MarkerMap } from "@getsoren/map";
const markers = [
{
id: 1,
lng: 2.3522,
lat: 48.8566,
Tooltip: <div>Paris</div>,
color: "primary",
variant: "default",
},
{
id: 2,
lng: -0.1276,
lat: 51.5074,
Tooltip: <div>London</div>,
color: "secondary",
variant: "default",
},
];
function App() {
return (
<MapProvider
licenseMuiX="your-muix-license"
licenceMapbox="your-mapbox-token"
>
<MarkerMap
markers={markers}
center={[2.3522, 48.8566]}
zoom={5}
fitBounds
height={500}
width="100%"
onMapClick={(lng, lat, marker) => {
console.log("Clicked at:", lng, lat);
if (marker) console.log("Marker clicked:", marker);
}}
/>
</MapProvider>
);
}
* 构成部分概览
MapProvider
环绕您的地图组件并注入所需的提供者(主题、 符号、 MUI X 许可证) .
必需的道具 :
licenseMuiX- 您的 MUI X 许可证密钥licenceMapbox— 您的 Mapbox 访问符
<MapProvider
licenseMuiX="your-license"
licenceMapbox="your-token"
>
{/* Your map components */}
</MapProvider>
MapView 编号 : MarkerMap
处理的主要地图组件 :
- 带有自定义图标或反应组件的标记渲染
- 有悬浮/ 点击模式的互动弹出
- 自动绑定配置
- 地图点击事件
- 反应容器大小
专业部分
RouteMap— 使用 OSRM 或 Mapbox 绘制两个点之间的路由IsochroneMap+ 计算和显示旅行时间多边形FeatureMap• 显示自定义带有样式的 GeoJSON 层
推荐参考
MapView 道具
核心地图道具
| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
center | LngLatLike | number[] | [2.3522, 48.8566] | 初始地图中心坐标 [lng, lat] |
zoom | number | 5 | 初始缩放级别 (0-22) |
width | string | number | "100%" | 映射容器宽度 |
height | string | number | 300 | 映射容器高度 |
loading | boolean | false | 显示骨架加载器 |
square | boolean | false | 执行 1:1 宽比 |
containerStyle | SxProps | undefined | 自定义 MUI sx 样式 |
地图外观
| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
theme | "light" | "dark" | "light" | 映射颜色主题 |
baseMapView | "street" | "satellite" | "street" | 底图层类型 |
mapStyle | string | - 说吧 | 自定义映射箱样式 URL |
projection | ProjectionSpecification | "mercator" | 地图投影系统 |
交互支持
| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
cooperativeGestures | boolean | true | 缩放/ 宽度需要修改键 |
doubleClickZoom | boolean | true | 启用双击以缩放 |
onMapClick | (lng, lat, marker?) => void | - 说吧 | 回调地图点击( 如果适用, 包括点击的标记) |
标记道具
| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
markers | MarkerProps[] | [] | 要显示的标记阵列 |
markerImageURL | string | - 说吧 | 自定义标记图标 URL |
openPopup | string | number | undefined | 打开弹出标记的标识 |
openPopupOnHover | boolean | false | 悬浮时打开弹出而非点击 |
popupMaxWidth | string | "300px" | 最大弹出宽度 |
定义和动画
| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
fitBounds | boolean | true | 显示所有标记的自动适应地图 |
fitBoundsPadding | number | 0 | 装有边框的平板(px) |
fitBoundDuration | number | 500 | 动画持续时间(分) |
disableAnimation | boolean | false | 禁用所有动画 |
fitBoundsAnimationKey | unknown | - 说吧 | 更改为重新触发适值 |
标记道具( M)MarkerProps(中文(简体) )
| Prop | 类型 | 需求 | 说明 |
|---|---|---|---|
id | string | number | ✅ | 唯一标记标识符 |
lng | number | ✅ | 经度坐标 |
lat | number | ✅ | 纬度坐标 |
Tooltip | ReactNode | - 说吧 | 弹出/ 工具提示的内容 |
IconComponent | React.ComponentType | - 说吧 | 自定义反应图标组件 |
iconProps | object | - 说吧 | 向图标组件传递道具 |
color | string | - 说吧 | 标记颜色( MUI 调色板) |
variant | string | - 说吧 | 标记样式变体 |
带有自定义图标的示例 :
import LocationOnIcon from '@mui/icons-material/LocationOn';
const marker = {
id: 1,
lng: 2.3522,
lat: 48.8566,
IconComponent: LocationOnIcon,
iconProps: { fontSize: 'large', color: 'error' },
Tooltip: <div>Custom Icon Marker</div>
};
线性道具itineraryParams(中文(简体) )
以自定义型式和路由引擎绘制出两个点之间的路线.
| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
from | [number, number] | - 说吧 | 路线起点 [lng, lat] |
to | [number, number] | - 说吧 | 路线终点 [lng, lat] |
profile | "driving" | "walking" | "cycling" | "driving" | 运输模式 |
engine | "OSRM" | "Mapbox" | "OSRM" | 要使用的运行服务 |
itineraryLineStyle | Partial<ItineraryLineStyle> | { color: "#3b82f6", width: 4, opacity: 0.8 } | 路线线外观 |
initialRoute | Feature<LineString> | - 说吧 | GeoJSON 预计算路线 |
onRouteComputed | (route) => void | - 说吧 | 计算路线时调用 |
itineraryLabel | ReactNode | - 说吧 | 沿途显示标签( 如 “ 12 分 ” ) |
示例
<MapView
itineraryParams={{
from: [2.3522, 48.8566], // Paris
to: [-0.1276, 51.5074], // London
profile: "driving",
engine: "OSRM",
itineraryLineStyle: {
color: "#10b981",
width: 5,
opacity: 0.9
},
itineraryLabel: <span>Route principale</span>,
onRouteComputed: (route) => {
console.log("Route computed:", route);
}
}}
/>
最接近的标记搜索( E)findNearestMarker(中文(简体) )
在最大距离内查找和突出最接近给定点的标记.
| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
origin | [number, number] | - 说吧 | 搜索起点 [lng, lat] |
destinations | Array<{id, lng, lat}> | - 说吧 | 候选目的地 |
maxDistanceMeters | number | - 说吧 | 最大搜索半径( 公尺) |
profile | "driving" | "walking" | "cycling" | "driving" | 远程计算运行配置文件 |
engine | "OSRM" | "Mapbox" | "OSRM" | 运行要使用的引擎 |
onNearestFound | (results) => void | - 说吧 | 以所有最近的结果召回 |
initialNearestResults | NearestResult[] | - 说吧 | 预算的最近结果 |
itineraryLineStyle | Partial<ItineraryLineStyle> | - 说吧 | 自动生成行程的样式覆盖 |
最接近的结果类型 :
interface NearestResult {
id: number | string;
point: [number, number]; // [lng, lat]
distance: number; // in meters
routeFeature?: Feature<LineString> | null;
}
示例
<MapView
findNearestMarker={{
origin: [2.3522, 48.8566],
destinations: markers.map(m => ({
id: m.id,
lng: m.lng,
lat: m.lat
})),
maxDistanceMeters: 5000,
profile: "walking",
engine: "OSRM",
onNearestFound: (results) => {
console.log(`Found ${results.length} markers within range`);
results.forEach(r => {
console.log(`Marker ${r.id} at ${r.distance}m`);
});
}
}}
/>
异色龙道具( E)isochrone(中文(简体) )
计算和显示在特定时间间隔内可以到达的区域.
| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
origin | [number, number] | - 说吧 | 同位素中心点 [lng, lat] |
profile | "driving" | "walking" | "cycling" | "driving" | 运输模式 |
intervals | number[] | [5, 10, 15] | 时间间隔( 分钟) |
onIsochroneLoaded | (data) => void | - 说吧 | 用 GeoJSON 结果召回 |
示例
<MapView
isochrone={{
origin: [2.3522, 48.8566],
profile: "driving",
intervals: [5, 10, 15, 20], // 5, 10, 15, 20 minutes
onIsochroneLoaded: (geojson) => {
console.log("Isochrone data:", geojson);
}
}}
/>
GeoJSON 地物features(中文(简体) )
显示多边形、行或点等自定义矢量特性.
| Prop | 类型 | 说明 |
|---|---|---|
features | Feature | Feature[] | FeatureCollection | 要渲染的 GeoJSON 数据 |
示例
<MapView
features={{
type: "Feature",
geometry: {
type: "LineString",
coordinates: [
[2.3, 48.8],
[2.4, 48.9],
[2.5, 48.85]
]
},
properties: {
color: "#ef4444"
}
}}
/>
高级使用案例
* 实时全球定位系统跟踪
function LiveTracking() {
const [position, setPosition] = useState([2.3522, 48.8566]);
useEffect(() => {
const watchId = navigator.geolocation.watchPosition((pos) => {
setPosition([pos.coords.longitude, pos.coords.latitude]);
});
return () => navigator.geolocation.clearWatch(watchId);
}, []);
return (
<MapView
markers={[{
id: 'current',
lng: position[0],
lat: position[1],
Tooltip: <div>You are here</div>
}]}
center={position}
zoom={15}
fitBounds={false}
/>
);
}
QQ 动态数据与 React 查询
import { useQuery } from '@tanstack/react-query';
function DynamicMarkers() {
const { data: markers } = useQuery({
queryKey: ['locations'],
queryFn: fetchLocations,
refetchInterval: 5000 // Refresh every 5s
});
return (
<MapView
markers={markers}
fitBounds
fitBoundsAnimationKey={markers?.length}
/>
);
}
自定义标记组件
function CustomMarker({ isActive, count }) {
return (
<Box
sx={{
width: 40,
height: 40,
borderRadius: '50%',
bgcolor: isActive ? 'success.main' : 'grey.500',
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
color: 'white',
fontWeight: 'bold',
border: '2px solid white',
boxShadow: 2
}}
>
{count}
</Box>
);
}
<MapView
markers={[{
id: 1,
lng: 2.3522,
lat: 48.8566,
IconComponent: CustomMarker,
iconProps: { isActive: true, count: 5 }
}]}
/>
++ 多路比较
<MapView
features={[
{
type: "Feature",
geometry: {
type: "LineString",
coordinates: route1
},
properties: { color: "#3b82f6" }
},
{
type: "Feature",
geometry: {
type: "LineString",
coordinates: route2
},
properties: { color: "#ef4444" }
}
]}
/>
QQ 点击到添加标记
function InteractiveMap() {
const [markers, setMarkers] = useState([]);
const handleMapClick = (lng, lat) => {
setMarkers(prev => [...prev, {
id: Date.now(),
lng,
lat,
Tooltip: <div>Point {markers.length + 1}</div>
}]);
};
return (
<MapView
markers={markers}
onMapClick={handleMapClick}
/>
);
}
++ 合并运行和最近的搜索
function DeliveryMap() {
const [origin] = useState([2.3522, 48.8566]);
const [destinations] = useState([
{ id: 1, lng: 2.35, lat: 48.86 },
{ id: 2, lng: 2.36, lat: 48.85 },
{ id: 3, lng: 2.34, lat: 48.87 }
]);
return (
<MapView
markers={destinations.map(d => ({
id: d.id,
lng: d.lng,
lat: d.lat,
Tooltip: <div>Destination {d.id}</div>
}))}
findNearestMarker={{
origin,
destinations,
maxDistanceMeters: 10000,
profile: "driving",
engine: "OSRM",
itineraryLineStyle: {
color: "#22c55e",
width: 4,
opacity: 0.8
},
onNearestFound: (results) => {
console.log("Nearest destinations:", results);
}
}}
/>
);
}
QQ 提示和最佳做法
性能优化
- 纪念标记数据 防止不必要的重交
- 使用
fitBoundsAnimationKey来控制边框的再计算 - 禁用动画 大数据集:
disableAnimation={true} - 取消动态更新 跟踪实时数据时
- 使用
initialRoute财务报告和审定财务报表initialNearestResults以避免重复的 API 调用
UX 改进
- 组合
openPopupOnHover财务报告和审定财务报表disableAnimation用于平滑互动 - 使用
fitBoundsPadding确保标记不在屏幕边缘 - 设置适当
popupMaxWidth移动响应能力 - 用自定义提供视觉反馈
IconComponent状态 - 使用
itineraryLabel显示路由持续时间或距离
推广最佳做法
- 使用 OSRM (免费)满足基本路线需要
- 使用映射框 用于生产需要SLA和支持的应用软件
- 缓存路由结果
initialRoute以最小化 API 调用 - 处理网络错误
onRouteComputed回调 - 组合
findNearestMarker与itineraryParams最佳路由工作流程
发展
先决条件
- 阿宝 * 1.1.0(建议)或节点18+
- 图形
设置
# Clone the repository
git clone https://github.com/tracktor-tech/tracktor-map.git
cd tracktor-map
# Install dependencies
bun install
# Start development sandbox
bun run sandbox
# or
bun run dev:sandbox
可用的脚本
| 命令 | 说明 |
|---|---|
bun run sandbox | 启动交互式开发游戏场 |
bun run build | 建立用于制作的图书馆 |
bun run build:sandbox | 构建沙盒演示站点 |
bun run deploy:sandbox | 向 GitHub 页面部署沙盒 |
bun run lint | 检查代码质量和类型 |
bun run lint:fix | 自动固定嵌入问题 |
bun run test | 运行测试套件 |
bun run test:watch | 在监视模式下运行测试 |
bun run version | 带有更改日志的弹出版本 |
bun run release | 构建并发布到 npm |
项目结构
@getsoren/map/
├── src/
│ ├── components/ # Reusable map and UI components (Marker, Popup, etc.)
│ ├── constants/ # Shared configuration values and styling constants
│ ├── context/ # React context providers (e.g. map state)
│ ├── features/ # Core map features (routes, isochrones, nearest, etc.)
│ ├── services/ # External APIs and utility services
│ ├── types/ # TypeScript interfaces and types
│ ├── utils/ # Generic helpers and formatting functions
│ └── main.ts # Library entry point
│
├── sandbox/ # Development playground (example app & live demos)
│ ├── context/ # Demo context providers
│ ├── examples/ # Interactive usage examples
│ ├── features/ # Components used in the docs/demo
│ ├── public/ # Static assets (images, previews, etc.)
│ ├── App.tsx # Sandbox root component
│ └── index.tsx # Sandbox entry file
│
└── test/ # Unit and integration tests
测试
# Run all tests
bun test
# Watch mode
bun test:watch
# Run specific test file
bun test src/components/MapView.test.tsx
捐款
我们欢迎捐款! 请:
- 叉子存储器
- 创建特性分支( E)
git checkout -b feature/amazing-feature(中文(简体) ) - 做你的改变
- 进行测试和起伏
bun run test && bun run lint(中文(简体) ) - 提交更改( E)
git commit -m 'Add amazing feature'(中文(简体) ) - 推向分行(
git push origin feature/amazing-feature(中文(简体) ) - 打开拉请求
代码样式 :
- 遵循现有模式和公约
- 对所有新代码使用类型脚本
- 添加新特性测试
- 视需要更新文件
文档和实例
探索互动实例和综合API文档:
沙盒包括:
- 交互式代码示例
- 所有特性的现场预览
- 复制已准备好的片断
- 搜索时的 API 引用
* 出版和部署
发布到 npm
# Update version and generate changelog
bun run version
# Build and publish
bun run release
向 GitHub 页面部署沙盒
bun run deploy:sandbox
这将:
- 以生产优化方式建造沙盒
- 生成用于客户端路由的404.html
- 推进到
gh-pages分支 - 更新实时文件网站
* 解决问题
共同问题
映射地图 :
- 校验您的 Mapbox 令牌是有效的
- 检查浏览器控制台的错误
- 确保导入映射框- gl CSS
类型脚本错误 :
- 运行
bun install以更新类型定义 - 检查对等依赖版本匹配
业绩问题:
- 减少标记数或使用分组
- 禁用大型数据集的动画
- 纪念标记数据
- 使用
initialRoute财务报告和审定财务报表initialNearestResults缓存数据
运行不工作 :
- 校验坐标为 [lng, lat] (不是 lat, Ing) 格式
- 请检查可访问的路由引擎
- 确保配置符合您的使用大小写
- 校验最大离相表对最近的搜索是合理的
获取帮助
许可证
无效 ——这个包是专有软件.
[追踪器——凯文·格拉夫]
链接
- 📦 无数字 : @ getsoren/ 地图
- 💻 GitHub 图像数字 : @ getsoren/ 地图
- 🌐 文档数字 : tracktor.github.io/地图
- 🎨 设计系统数字 : @ getsoren/ 设计系统
- 沙盒 Demo : (中文(简体) ) tracktor.github.io/地图/沙盒
承认
以下列方式建造:
- 地图盒 GL JS - 强大的地图渲染
- 反应-映射-gl — Mapbox 的回放包装
- OSRM 操作程序 ——自由路由引擎
- @ getsoren/ 设计系统 ——UI组件