# @getsoren/map 中文文档

规范地址：https://npmcn.com/package/%40getsoren/map/

版本：1\.11\.2
npm 元数据更新时间：2026-11-09T09:27:43.633Z
中文译文更新时间：2026-11-16T07:01:44.316Z
软件包许可：UNLICENSED

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40getsoren/map
原文对照：https://npmcn.com/package/%40getsoren/map/?lang=original
项目主页：https://github.com/getsoren/map#readme
源码仓库：https://github.com/getsoren/map

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：188 kB，40 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 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
- 首次发布：2026-05-15T22:03:43.493Z
- 最新版本发布：2026-11-09T09:27:43.439Z
- 近 30 天下载量：3496（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

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

## 安装

```sh
npm install @getsoren/map
```

也可以使用：`pnpm add @getsoren/map`、`yarn add @getsoren/map`、`bun add @getsoren/map`

## README

# @ getsoren/ 地图

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

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

[![License](https://img.shields.io/badge/license-UNLICENSED-red.svg)](https://npmcn.com/package/%40getsoren/map/LICENSE)

* * *

## \* 安装

```bash
npm install @getsoren/map
```

或者说

```bash
yarn add @getsoren/map
```

或者说

```bash
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 (英语)](https://account.mapbox.com/access-tokens/)。 。 。 .

* * *

## \* 特性

✅ **声明性 API** ——用简单的道具管理复杂的地图互动  
✅ **标记弹出( P)** ——可自定义的 React 组件或基于图像的图标  
✅ **运行和异色龙** ——可视化出行时间区或计算出最佳路线  
✅ **地层** ——动态渲染矢量数据  
✅ **最接近的标记搜索** - 立即发现和突出最接近的点  
✅ **类型安全 API** ——智能IntelliSense的完整类型脚本支持  
✅ **响应设计** ——自动适应任何容器或屏幕大小  
✅ **为履约而建** ——最少重交,高效地图更新  
✅ **多个运行引擎** ——支持 OSRM (免费) 和 Mapbox 方向 API  
✅ **灵活映射样式** – 使用 Mapbox 样式、 OpenStreetMap 或自定义光栅砖

* * *

## QQ 快速启动

```tsx
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 访问符

```tsx
<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` | \- 说吧 | 标记样式变体 |

**带有自定义图标的示例 :**

```tsx
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 分 ” ) |

**示例**

```tsx
<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>` | \- 说吧 | 自动生成行程的样式覆盖 |

**最接近的结果类型 :**

```tsx
interface NearestResult {
  id: number | string;
  point: [number, number]; // [lng, lat]
  distance: number; // in meters
  routeFeature?: Feature<LineString> | null;
}
```

**示例**

```tsx
<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 结果召回 |

**示例**

```tsx
<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 数据 |

**示例**

```tsx
<MapView
  features={{
    type: "Feature",
    geometry: {
      type: "LineString",
      coordinates: [
        [2.3, 48.8],
        [2.4, 48.9],
        [2.5, 48.85]
      ]
    },
    properties: {
      color: "#ef4444"
    }
  }}
/>
```

* * *

## 高级使用案例

### \* 实时全球定位系统跟踪

```tsx
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 查询

```tsx
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}
    />
  );
}
```

### 自定义标记组件

```tsx
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 }
  }]}
/>
```

### ++ 多路比较

```tsx
<MapView
  features={[
    {
      type: "Feature",
      geometry: {
        type: "LineString",
        coordinates: route1
      },
      properties: { color: "#3b82f6" }
    },
    {
      type: "Feature",
      geometry: {
        type: "LineString",
        coordinates: route2
      },
      properties: { color: "#ef4444" }
    }
  ]}
/>
```

### QQ 点击到添加标记

```tsx
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}
    />
  );
}
```

### ++ 合并运行和最近的搜索

```tsx
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+
-   图形

### 设置

```bash
# 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
```

### 测试

```bash
# 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 文档和沙盒](https://tracktor.github.io/map)**

沙盒包括:

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

* * *

## \* 出版和部署

### 发布到 npm

```bash
# Update version and generate changelog
bun run version

# Build and publish
bun run release
```

### 向 GitHub 页面部署沙盒

```bash
bun run deploy:sandbox
```

这将:

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

* * *

## \* 解决问题

### 共同问题

**映射地图 :**

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

**类型脚本错误 :**

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

**业绩问题:**

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

**运行不工作 :**

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

### 获取帮助

-   请检查 [文档](https://github.com/Tracktor/map)
-   🐛 [报告错误](https://github.com/tracktor-tech/tracktor-map/issues)
-   \* 加入GitHub讨论的讨论

* * *

## 许可证

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

* * *

## 链接

-   📦 **无**数字 : [@ getsoren/ 地图](https://www.npmjs.com/package/@getsoren/map)
-   💻 **GitHub 图像**数字 : [@ getsoren/ 地图](https://github.com/Tracktor/map)
-   🌐 **文档**数字 : [tracktor.github.io/地图](https://tracktor.github.io/map)
-   🎨 **设计系统**数字 : [@ getsoren/ 设计系统](https://www.npmjs.com/package/@getsoren/design-system)
-   沙盒 Demo : (中文(简体) ) [tracktor.github.io/地图/沙盒](https://tracktor.github.io/map)

* * *

## 承认

以下列方式建造:

-   [地图盒 GL JS](https://docs.mapbox.com/mapbox-gl-js/) - 强大的地图渲染
-   [反应-映射-gl](https://visgl.github.io/react-map-gl/) — Mapbox 的回放包装
-   [OSRM 操作程序](http://project-osrm.org/) ——自由路由引擎
-   [@ getsoren/ 设计系统](https://www.npmjs.com/package/@getsoren/design-system) ——UI组件

## 常见问题

### @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 和提交记录判断。

