# @djangocfg/widget-map 中文文档

规范地址：https://npmcn.com/package/%40djangocfg/widget-map/

版本：0\.1\.36
npm 元数据更新时间：2026-11-11T03:53:41.124Z
中文译文更新时间：2026-11-12T12:15:30.262Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40djangocfg/widget-map
原文对照：https://npmcn.com/package/%40djangocfg/widget-map/?lang=original
项目主页：https://djangocfg.com/
源码仓库：https://github.com/markolofsen/django-cfg

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

- 包体积（解压后）：284 kB，76 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react ^19\.0\.0，react-dom ^19\.0\.0，lucide-react ^1\.68\.0，@djangocfg/ui-core ^2\.1\.648
- 首次发布：2026-09-09T08:12:56.920Z
- 最新版本发布：2026-11-11T03:53:40.930Z
- 近 30 天下载量：4803（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：32（近 12 个月 32 个）

## 中文简介

MapLibre GL上的交互式地图:标记、集群GeoJSON、层工厂、无密钥底图、地形、地理编码和计量

## 安装

```sh
npm install @djangocfg/widget-map
```

也可以使用：`pnpm add @djangocfg/widget-map`、`yarn add @djangocfg/widget-map`、`bun add @djangocfg/widget-map`

## README

# 地图

交互式地图 `@djangocfg/widget-map`,在 [地图Libre GL](https://maplibre.org/) 通过 `react-map-gl` ——标记,集群的GeoJSON,弹出,层厂,免费的OpenFreeMap / PMTiles basemaps,运行时基图切换器,3D地形,地址/位置自动完成(geocoder),指南针,点击量度,可拖动标记,自定义标记图标,以及一个选入定位我(GPS)芯片,全部被放在一个小的提供商/康特表面后.

> **装舱警告.** MapLibre GL为重(~800 KB gziped). 这个 `@djangocfg/widget-map` 条目已经是 **懒惰** 一个 - `LazyMapContainer` 将 MapLibre 块推迟到挂起 。 所有组件都是 `'use client'`;从不在 Next.js 服务器上渲染出.

## 安装

```bash
pnpm add @djangocfg/widget-map @djangocfg/ui-core
```

## 快开始

```tsx
import { LazyMapContainer, MapMarker } from '@djangocfg/widget-map';

<div className="h-96 rounded-xl overflow-hidden">
  <LazyMapContainer
    initialViewport={{ latitude: 25.08, longitude: 55.14, zoom: 13 }}
    mapStyle="light"
  >
    <MapMarker
      marker={{ id: 'home', latitude: 25.08, longitude: 55.14 }}
      color="#10b981"
      size={32}
    />
  </LazyMapContainer>
</div>
```

集装箱自行提供 `MapProvider`。使用兄弟会的地图上下文(例如按钮调用) `flyTo`,将你的树包入 `<MapProvider>` 提供 `<MapView>` 内在的 见 [集装箱](https://npmcn.com/package/%40djangocfg/widget-map/@docs/container.md)。 。 。 .

## 公共出口 - `@djangocfg/widget-map`

包子路径解决了懒惰入门. 它的表面:

**构成部分** —— 说 `LazyMapContainer`, (中文(简体) ), `LazyMapView` (代码分割), `MapView`\- 通过..`MapContainer` 类型,加上浅原始: `MapMarker`, (中文(简体) ), `MapPopup`, (中文(简体) ), `MapCluster`, (中文(简体) ), `MapSource`, (中文(简体) ), `MapLayer`, (中文(简体) ), `MapControls`, (中文(简体) ), `CustomOverlay`, (中文(简体) ), `MapLegend`, (中文(简体) ), `LayerSwitcher`, (中文(简体) ), `MeasureControl`, (中文(简体) ), `DraggableMarkers`, (中文(简体) ), `GeocoderInput`, (中文(简体) ), `GeocoderControl`, (中文(简体) ), `CompassChip`, (中文(简体) ), `MarkerCard`, (中文(简体) ), `MapMarkers`。 。 。 .

**A. 背景情况** —— 说 `MapProvider`, (中文(简体) ), `useMapContext`, (中文(简体) ), `MapContext`。 。 。 .

**样式** —— 说 `MAP_STYLES`, (中文(简体) ), `getMapStyle`, (中文(简体) ), `MAP_STYLE_LABELS`, (中文(简体) ), `KEY_FREE_STYLES`, (中文(简体) ), `resolveBasemapOptions`,以及自由地形 DEM 来源 `TERRAIN_DEM` 编号 : `TERRAIN_DEM_URL`。 。 。 .

**导弹** —— 说 `addPMTilesProtocol`, (中文(简体) ), `pmtilesSourceUrl` (自发托管/离线基底图).

**地理编码器** —— 说 `photonResolve` (默认无密钥光子解析器), `cameraForResult` (智能-zoom 帮助),和类型 `GeocodeResult`, (中文(简体) ), `GeocodeKind`, (中文(简体) ), `ResolveGeocode`。见 [地理编码器](https://npmcn.com/package/%40djangocfg/widget-map/@docs/geocoder.md)。 。 。 .

**类型** —— 说 `MapContainerProps`, (中文(简体) ), `GeolocateOptions`, (中文(简体) ), `GeolocatePosition`, (中文(简体) ), `MapMarkerProps`, (中文(简体) ), `MapPopupProps`, (中文(简体) ), `MapClusterProps`, (中文(简体) ), `MapSourceProps`, (中文(简体) ), `MapLayerProps`, (中文(简体) ), `MapControlsProps`, (中文(简体) ), `MeasureControlProps`, (中文(简体) ), `DraggableMarkersProps`, (中文(简体) ), `DraggablePoint`, (中文(简体) ), `GeocoderInputProps`, (中文(简体) ), `GeocoderControlProps`, (中文(简体) ), `CompassChipProps`, (中文(简体) ), `MapProviderProps`, (中文(简体) ), `MapViewport`, (中文(简体) ), `MapStyleKey`, (中文(简体) ), `MarkerData`,加上钩型 `GeolocationFix`, (中文(简体) ), `GeolocationStatus`, (中文(简体) ), `UseGeolocationOptions`, (中文(简体) ), `UseGeolocationResult`, (中文(简体) ), `UseGeocoderOptions`, (中文(简体) ), `UseGeocoderResult`, (中文(简体) ), `UseCompassResult`, (中文(简体) ), `UseTerrainOptions`, (中文(简体) ), `UseMeasureResult`, (中文(简体) ), `MeasureMode`, (中文(简体) ), `MapImage`, (中文(简体) ), `UseMapImagesResult`, (中文(简体) ), `UseDraggableMarkersOptions`, (中文(简体) ), `UseDraggableMarkersResult`, (中文(简体) ), `DraggableMarkerHandlers`,加上标记卡类型 `MarkerCardProps`, (中文(简体) ), `MapMarkersProps`, (中文(简体) ), `MarkerWithCard`, (中文(简体) ), `MarkerCardInfo` (卡片数据形状), `MarkerCardAction`, (中文(简体) ), `MarkerCardData`, (中文(简体) ), `MarkerCardActionData`, (中文(简体) ), `UseMarkerCardResult`。 。 。 .

**钩子** —— 说 `useMap`, (中文(简体) ), `useMapControl`, (中文(简体) ), `useMarkers`, (中文(简体) ), `useMapEvents`, (中文(简体) ), `useMapViewport`, (中文(简体) ), `useMapLayers`, (中文(简体) ), `useControl`, (中文(简体) ), `useSpiderfy` (+ 数) `UseSpiderfyOptions` 编号 : `UseSpiderfyResult` 类型), `useMarkerCard` (单开标记卡选择状态),功能钩 `useCompass`, (中文(简体) ), `useTerrain`, (中文(简体) ), `useMeasure`, (中文(简体) ), `useMapImages`, (中文(简体) ), `useDraggableMarkers`, (中文(简体) ), `useGeocoder`和地图独立 `useGeolocation` (自定义“我在哪里”的浏览器位置;见 [钩子](https://npmcn.com/package/%40djangocfg/widget-map/@docs/hooks.md#usegeolocationoptions)) (中文(简体) ). `useMapScrollProtection` 编号 : `useMapTouchMode` 也出口——它们的力量 `scrollProtection`用来给你的.

**层工厂** —— 说 `createClusterLayers`, (中文(简体) ), `createPointLayer`, (中文(简体) ), `createHeatmapLayer`, (中文(简体) ), `createPolygonLayer`, (中文(简体) ), `createPolygonOutlineLayer`, (中文(简体) ), `createHighlightLayer`, (中文(简体) ), `createLineLayer`, (中文(简体) ), `createRouteLayers`, (中文(简体) ), `createDashedLineLayer`, (中文(简体) ), `createAnimatedLineLayer`, (中文(简体) ), `createSymbolLayer`。 。 。 .

**几何曲线** —— 说 `calculateBounds`, (中文(简体) ), `calculateCenter`, (中文(简体) ), `calculateDistance`, (中文(简体) ), `isPointInBounds`, (中文(简体) ), `expandBounds`, (中文(简体) ), `toGeoJSON`, (中文(简体) ), `fromGeoJSON`, (中文(简体) ), `createPoint`, (中文(简体) ), `createPolygon`, (中文(简体) ), `createLineString`, (中文(简体) ), `createFeatureCollection`。 。 。 .

**蜘蛛鱼利用** —— 说 `offsetOverlappingMarkers`, (中文(简体) ), `getSpiderfyPositions`, (中文(简体) ), `groupOverlappingMarkers`, (中文(简体) ), `hasOverlappingMarkers`, (中文(简体) ), `getOverlapStats`。 。 。 .

## 文档

| 医生 | 封面 |
| --- | --- |
| [集装箱](https://npmcn.com/package/%40djangocfg/widget-map/@docs/container.md) | `MapContainer` 编号 : `MapView` ——全道具,控制工具栏(搜索 地形 指南针 定位-我/GPS芯片),滚动保护与移动,全屏对话框. |
| [基图.md](https://npmcn.com/package/%40djangocfg/widget-map/@docs/basemaps.md) | 地图样式 运行时基图切换器 OpenFreeMap 卫星/密钥 PMTiles 3D地形 (free DEM). |
| [标记-poups.md](https://npmcn.com/package/%40djangocfg/widget-map/@docs/markers-popups.md) | `MapMarker`, (中文(简体) ), `MapPopup`, (中文(简体) ), `MapCluster`,标记信息卡(`MarkerCard` 编号 : `MapMarkers` 编号 : `useMarkerCard`),可拖动标记,相重叠点/蛛网. |
| [层.md](https://npmcn.com/package/%40djangocfg/widget-map/@docs/layers.md) | `MapSource` 编号 : `MapLayer`,分层工厂,自定义标记图标(符号层),几何功能. |
| [地理编码器](https://npmcn.com/package/%40djangocfg/widget-map/@docs/geocoder.md) | 地址/地点自动完成 - `GeocoderInput` 编号 : `GeocoderControl`工具栏搜索芯片, `photonResolve`,智能缩放`cameraForResult`, (中文(简体) ), `useGeocoder`。 。 。 . |
| [钩子( m)](https://npmcn.com/package/%40djangocfg/widget-map/@docs/hooks.md) | 每钩取出一一譬. |
| [高级](https://npmcn.com/package/%40djangocfg/widget-map/@docs/advanced.md) | `CustomOverlay`, (中文(简体) ), `MapLegend`, (中文(简体) ), `LayerSwitcher`, (中文(简体) ), `MeasureControl`抽取控制食谱 懒惰的装入 SSR. |
| [故事内容](https://npmcn.com/package/%40djangocfg/widget-map/@docs/stories.md) | 童话故事列表. |

## 两个条目

| 导入 | 集装箱 | 对于 |
| --- | --- | --- |
| `@djangocfg/widget-map` | 后面 `React.lazy` | 一切——这是默认的原因 |
| `@djangocfg/widget-map/eager` | 静态边缘 | 地图是页面,占位符读作闪光 |

`eager` 来源于根 (`export * from './index'` 加上静态 因此,两个表面不能漂移; `src/entries.test.ts` 走着走着 静态导入图, 并自控分割 .

**在一个应用程序中导入两者都会使拆分失败** 静态边缘拉起 MapLibre进入条目,不管其他一半做什么.

## 校验

```bash
pnpm --filter @djangocfg/widget-map check-types test
```

## 相关

-   底线: [`react-map-gl` (MapLibre适配器)](https://visgl.github.io/react-map-gl/) 顶上 [MapLibre GL 联合来文](https://maplibre.org/maplibre-gl-js/docs/)

## 常见问题

### @djangocfg/widget-map 是什么？

MapLibre GL上的交互式地图:标记、集群GeoJSON、层工厂、无密钥底图、地形、地理编码和计量

### 如何安装 @djangocfg/widget-map？

在项目目录运行 npm install @djangocfg/widget-map，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）、react-dom（^19\.0\.0）、lucide-react（^1\.68\.0）、@djangocfg/ui-core（^2\.1\.648）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @djangocfg/widget-map 支持 TypeScript 吗？

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

### @djangocfg/widget-map 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @djangocfg/widget-map 可以商用吗？

@djangocfg/widget-map 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @djangocfg/widget-map 的下载量有多少？

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

### @djangocfg/widget-map 还在维护吗？

最新版本 0\.1\.36 发布于 2026/11/11（1 天前）；至今共发布 32 个版本，其中过去 12 个月发布了 32 个；首次发布于 2026/09/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。