@getsoren/map

中文文档
1.11.2发布于 2026/11/09UNLICENSEDTypeScriptESM + CJS近 30 天下载 3496

用多种工具轻松显示地图的 React 库

中文使用文档
文档目录43 节
  1. * 安装
  2. 所需经费
  3. * 特性
  4. QQ 快速启动
  5. * 构成部分概览
  6. MapProvider
  7. MapView 编号 : MarkerMap
  8. 专业部分
  9. 推荐参考
  10. MapView 道具
  11. 标记道具( M) MarkerProps (中文(简体) )
  12. 线性道具 itineraryParams (中文(简体) )
  13. 最接近的标记搜索( E) findNearestMarker (中文(简体) )
  14. 异色龙道具( E) isochrone (中文(简体) )
  15. GeoJSON 地物 features (中文(简体) )
  16. 高级使用案例
  17. * 实时全球定位系统跟踪
  18. QQ 动态数据与 React 查询
  19. 自定义标记组件
  20. ++ 多路比较
  21. QQ 点击到添加标记
  22. ++ 合并运行和最近的搜索
  23. QQ 提示和最佳做法
  24. 性能优化
  25. UX 改进
  26. 推广最佳做法
  27. 发展
  28. 先决条件
  29. 设置
  30. 可用的脚本
  31. 项目结构
  32. 测试
  33. 捐款
  34. 文档和实例
  35. * 出版和部署
  36. 发布到 npm
  37. 向 GitHub 页面部署沙盒
  38. * 解决问题
  39. 共同问题
  40. 获取帮助
  41. 许可证
  42. 链接
  43. 承认

@ getsoren/ 地图

Mapbox GL JS上方建有现代轻量级React地图库并反应-map-gl. 设计简单,灵活,有视觉优雅.

容易地结合了标记,路线,GeoJSON特征,同位素,和最接近的点数计算——都有一个宣告性,型号安全的API.

License


* 安装

npm install @getsoren/map

或者说

yarn add @getsoren/map

或者说

bun add @getsoren/map

所需经费

依赖性版本目的
react17+/18+/19+ (英语)核心反应运行时间
react-dom17+/18+/19+ (英语)反应 DOM 渲染
mapbox-gl≥ 3.0.0映射引擎
@getsoren/design-system≥ 4.0.0UI 主题和组件
@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类型默认说明
centerLngLatLike | number[][2.3522, 48.8566]初始地图中心坐标 [lng, lat]
zoomnumber5初始缩放级别 (0-22)
widthstring | number"100%"映射容器宽度
heightstring | number300映射容器高度
loadingbooleanfalse显示骨架加载器
squarebooleanfalse执行 1:1 宽比
containerStyleSxPropsundefined自定义 MUI sx 样式

地图外观

Prop类型默认说明
theme"light" | "dark""light"映射颜色主题
baseMapView"street" | "satellite""street"底图层类型
mapStylestring- 说吧自定义映射箱样式 URL
projectionProjectionSpecification"mercator"地图投影系统

交互支持

Prop类型默认说明
cooperativeGesturesbooleantrue缩放/ 宽度需要修改键
doubleClickZoombooleantrue启用双击以缩放
onMapClick(lng, lat, marker?) => void- 说吧回调地图点击( 如果适用, 包括点击的标记)

标记道具

Prop类型默认说明
markersMarkerProps[][]要显示的标记阵列
markerImageURLstring- 说吧自定义标记图标 URL
openPopupstring | numberundefined打开弹出标记的标识
openPopupOnHoverbooleanfalse悬浮时打开弹出而非点击
popupMaxWidthstring"300px"最大弹出宽度

定义和动画

Prop类型默认说明
fitBoundsbooleantrue显示所有标记的自动适应地图
fitBoundsPaddingnumber0装有边框的平板(px)
fitBoundDurationnumber500动画持续时间(分)
disableAnimationbooleanfalse禁用所有动画
fitBoundsAnimationKeyunknown- 说吧更改为重新触发适值

标记道具( M)MarkerProps(中文(简体) )

Prop类型需求说明
idstring | number✅唯一标记标识符
lngnumber✅经度坐标
latnumber✅纬度坐标
TooltipReactNode- 说吧弹出/ 工具提示的内容
IconComponentReact.ComponentType- 说吧自定义反应图标组件
iconPropsobject- 说吧向图标组件传递道具
colorstring- 说吧标记颜色( MUI 调色板)
variantstring- 说吧标记样式变体

带有自定义图标的示例 :

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"要使用的运行服务
itineraryLineStylePartial<ItineraryLineStyle>{ color: "#3b82f6", width: 4, opacity: 0.8 }路线线外观
initialRouteFeature<LineString>- 说吧GeoJSON 预计算路线
onRouteComputed(route) => void- 说吧计算路线时调用
itineraryLabelReactNode- 说吧沿途显示标签( 如 “ 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]
destinationsArray<{id, lng, lat}>- 说吧候选目的地
maxDistanceMetersnumber- 说吧最大搜索半径( 公尺)
profile"driving" | "walking" | "cycling""driving"远程计算运行配置文件
engine"OSRM" | "Mapbox""OSRM"运行要使用的引擎
onNearestFound(results) => void- 说吧以所有最近的结果召回
initialNearestResultsNearestResult[]- 说吧预算的最近结果
itineraryLineStylePartial<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"运输模式
intervalsnumber[][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类型说明
featuresFeature | 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

捐款

我们欢迎捐款! 请:

  1. 叉子存储器
  2. 创建特性分支( E)git checkout -b feature/amazing-feature(中文(简体) )
  3. 做你的改变
  4. 进行测试和起伏bun run test && bun run lint(中文(简体) )
  5. 提交更改( E)git commit -m 'Add amazing feature'(中文(简体) )
  6. 推向分行(git push origin feature/amazing-feature(中文(简体) )
  7. 打开拉请求

代码样式 :

  • 遵循现有模式和公约
  • 对所有新代码使用类型脚本
  • 添加新特性测试
  • 视需要更新文件

文档和实例

探索互动实例和综合API文档:

👉 Live 文档和沙盒

沙盒包括:

  • 交互式代码示例
  • 所有特性的现场预览
  • 复制已准备好的片断
  • 搜索时的 API 引用

* 出版和部署

发布到 npm

# Update version and generate changelog
bun run version

# Build and publish
bun run release

向 GitHub 页面部署沙盒

bun run deploy:sandbox

这将:

  1. 以生产优化方式建造沙盒
  2. 生成用于客户端路由的404.html
  3. 推进到 gh-pages 分支
  4. 更新实时文件网站

* 解决问题

共同问题

映射地图 :

  • 校验您的 Mapbox 令牌是有效的
  • 检查浏览器控制台的错误
  • 确保导入映射框- gl CSS

类型脚本错误 :

  • 运行 bun install 以更新类型定义
  • 检查对等依赖版本匹配

业绩问题:

  • 减少标记数或使用分组
  • 禁用大型数据集的动画
  • 纪念标记数据
  • 使用 initialRoute 财务报告和审定财务报表 initialNearestResults 缓存数据

运行不工作 :

  • 校验坐标为 [lng, lat] (不是 lat, Ing) 格式
  • 请检查可访问的路由引擎
  • 确保配置符合您的使用大小写
  • 校验最大离相表对最近的搜索是合理的

获取帮助


许可证

无效 ——这个包是专有软件.
[追踪器——凯文·格拉夫]



承认

以下列方式建造:

版本与发布记录

@getsoren/map 共发布 8 个版本,首次发布于 2026/05/16;过去 12 个月发布了 8 个版本。

版本发布日期距今
1.11.2latest2026/11/096 天前
1.11.12026/11/0511 天前
1.11.02026/06/115 个月前
1.10.02026/06/105 个月前
1.9.12026/06/105 个月前
1.9.02026/06/105 个月前

关于 @getsoren/map 的常见问题

@getsoren/map 是什么?

用多种工具轻松显示地图的 React 库

如何安装 @getsoren/map?

在项目目录运行 npm install @getsoren/map,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(^17.0.0 || ^18.0.0 || ^19.0.0)、mapbox-gl(>=3.0.0)、react-dom(^17.0.0 || ^18.0.0 || ^19.0.0)、@mui/x-license(*)、@getsoren/react-utils(>=1.0.0)、@getsoren/design-system(>=4.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@getsoren/map 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@getsoren/map 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@getsoren/map 可以商用吗?

@getsoren/map 使用 UNLICENSED 许可。作者声明为 UNLICENSED,即不授予公开使用许可(与公共领域的 Unlicense 不同)。使用前需获得作者授权。以上为概括,不构成法律意见,请以许可原文为准。

@getsoren/map 的下载量有多少?

根据 npm 官方下载统计,@getsoren/map 在 2026/10/17 – 2026/11/15 这 30 天内被下载 3,496 次,日均约 117 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@getsoren/map 还在维护吗?

最新版本 1.11.2 发布于 2026/11/09(6 天前);至今共发布 8 个版本,其中过去 12 个月发布了 8 个;首次发布于 2026/05/16。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。