# @asteby/metacore-maps 中文文档

规范地址：https://npmcn.com/package/%40asteby/metacore-maps/

版本：0\.2\.25
npm 元数据更新时间：2026-11-04T14:49:09.384Z
中文译文更新时间：2026-11-07T00:38:49.367Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40asteby/metacore-maps
原文对照：https://npmcn.com/package/%40asteby/metacore-maps/?lang=original
源码仓库：https://github.com/asteby/metacore-sdk

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

- 包体积（解压后）：263 kB，39 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：1 个
- peer 依赖：react \>=18，pmtiles \>=3，react-dom \>=18，maplibre-gl \>=4，react-i18next \>=13，@asteby/metacore-sdk ^3\.18\.1，@asteby/metacore-runtime-react ^53\.14\.0
- 首次发布：2026-10-17T21:33:58.143Z
- 最新版本发布：2026-11-04T14:49:09.219Z
- 近 30 天下载量：6352（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 35 个）

## 中文简介

用于元主机和附加器的懒散地图 — MapView, 标记, 集群, 路线, 地峡, 位置选择器, 跟踪时间线和声明 `map`编号 :`timeline` 造物师. MapLibre GL 按需加载; 无 API 密钥 .

## 安装

```sh
npm install @asteby/metacore-maps
```

也可以使用：`pnpm add @asteby/metacore-maps`、`yarn add @asteby/metacore-maps`、`bun add @asteby/metacore-maps`

## README

# @asteby/metacore-映射

模拟企业资源规划系统及其附加物的懒惰地图。 一个包,三个工作:

-   **构成部分** —— 说 `MapView`, (中文(简体) ), `Marker`, (中文(简体) ), `ClusterLayer`, (中文(简体) ), `Polyline`编号 :`Route`, (中文(简体) ), `Geofence`, (中文(简体) ), `LocationPicker`, (中文(简体) ), `TrackingTimeline`。 。 。 .
-   **宣告渲染器** —— 说 `view_type: map` 财务报告和审定财务报表 `kind: map | timeline` 内核清单的详细面板,在 `@asteby/metacore-runtime-react`登记簿.
-   **没有锁,没有钥匙** —— 说 [地图Libre GL](https://maplibre.org/) 渲染; 底图为样式( 或 PMTiles) **您的主机服务 URL**。没有 API 密钥,没有第三方看到您的客户位置.

性能合同(计划§0.2):包件本身的初始块是: **~11 KB克齐普** (由 `src/size-budget.test.ts`,限制 15 KB)和 `maplibre-gl` 实值 **永远** 在一个静态导入图中 —— 它是第一次获取地图挂载。 登记条目`/register`)在一KB以下,所以一个从不显示地图的宿主几乎一文不值.

## 安装

```bash
pnpm add @asteby/metacore-maps maplibre-gl
# optional, only for pmtiles:// base maps
pnpm add pmtiles
```

`react`, (中文(简体) ), `maplibre-gl` 和《古兰经》 `@asteby/metacore-runtime-react`, (中文(简体) ), `@asteby/metacore-sdk`, (中文(简体) ), `react-i18next` 是同龄人。 在联邦版 `@asteby/metacore-maps` 财务报告和审定财务报表 `maplibre-gl` 懒惰的股份(`METACORE_PAGE_SHARES`:遥控器从不捆绑自己的副本.

## 配置底图( 一次, 在主机中)

```ts
import { configureMaps } from '@asteby/metacore-maps'

configureMaps({
  style: {
    light: 'https://cdn.example.com/map/light.json', // style JSON URL, or an inline style object
    dark: 'https://cdn.example.com/map/dark.json',
  },
  // PMTiles (self-hosted, range requests, no key): style sources use `pmtiles://https://…/mx.pmtiles`.
  pmtiles: () => import('pmtiles'),
  attribution: '© OpenStreetMap contributors', // credit for the data in the tiles you serve
  center: [-102.5, 23.6], zoom: 4,             // used when there is nothing to fit
})
```

无 `style` 地图取自一个平地背景(你的点、路线和区域仍在渲染) **没有** 除了MapLibre本身,网络请求。 帮助者 : `blankStyle(scheme)`, (中文(简体) ), `rasterStyle(['https://tiles/{z}/{x}/{y}.png'], attribution)`。 。 。 .

颜色方案跟随主机(`.dark` 类别/ `data-theme="dark"` 打开 `<html>`操作系统;通过 `theme="light|dark"` 把它钉上 图层在主题切换后幸存.

## 构成部分

```tsx
import { MapView, Route, Geofence, LocationPicker, TrackingTimeline } from '@asteby/metacore-maps'

// Points with popups (focusable markers; clusters automatically above 150 points)
<MapView
  ariaLabel="Envíos activos"
  points={[
    { key: 's1', lat: 19.43, lng: -99.13, label: 'TRK-1', status: 'in_transit', statusLabel: 'En tránsito',
      details: [{ label: 'Paquetería', value: 'DHL' }] },
  ]}
  colors={{ in_transit: '#0072B2' }}
  onSelect={(p) => console.log(p.key)}
>
  {/* layers and extra markers are children */}
  <Route path={[{ lat: 19.4, lng: -99.1 }, { lat: 19.9, lng: -100.2 }]} fit />
  <Geofence zones={[{ key: 'z', label: 'Cobertura', center: { lat: 19.43, lng: -99.13 }, radiusM: 5000 }]} />
</MapView>

// Pick a place: click, drag the pin, type coordinates, device GPS, optional address search
<LocationPicker value={point} onChange={setPoint} geocode={(q) => api.geocode(q)} />

// Shipment tracking — no map required
<TrackingTimeline
  events={[{ status: 'En tránsito', at: '2026-10-17T09:00:00Z', location: { label: 'Querétaro', lat: 20.59, lng: -100.39 } }]}
  timeZone="America/Mexico_City"
/>
```

| 导出 | 它会做什么 |
| --- | --- |
| `MapView` | 集装箱+懒马普利布尔. 道具 : `points`, (中文(简体) ), `cluster`, (中文(简体) ), `colors`, (中文(简体) ), `fit`, (中文(简体) ), `theme`, (中文(简体) ), `mapStyle`, (中文(简体) ), `height`, (中文(简体) ), `labels`, (中文(简体) ), `selectedKey`, (中文(简体) ), `onSelect`, (中文(简体) ), `onMapClick`, (中文(简体) ), `listExtra`孩子们. |
| `Marker` | 可焦点 DOM 标记 (`aria-label`弹出的孩子, `draggable`) (中文(简体) ). 最多几百个. |
| `ClusterLayer` | WebGL 点出本土集群,可提供上千个特性. |
| `Polyline` 编号 : `Route` | 在命令点上行; `Route` 添加编号站。 直通区段——不需要线路服务. |
| `Geofence` | 多边形和圆形`center` + 键 `radiusM`) (中文(简体) ). |
| `LocationPicker` | 地图+标有标签的纬度/经度输入(可访问路径)+GPS+可选地理编码器. |
| `TrackingTimeline` | 状态 / 时间 / 地点事件, 状态用文字描述 。 帮助者 `toTrackingEvents`, (中文(简体) ), `sortTrackingEvents`。 。 。 . |
| `MapList` | 列表等同地图(由 `MapView`) (中文(简体) ). |
| `configureMaps`, (中文(简体) ), `loadMaplibre`, (中文(简体) ), `useMap`, (中文(简体) ), `useMapScheme` | 主机配置(Host config),共享的懒惰加载器,以及自定义层的钩. |
| `distanceKm`, (中文(简体) ), `formatDistance`, (中文(简体) ), `isValidPoint`, (中文(简体) ), `parseLatLng`, (中文(简体) ), `directionsUrl` | 从 `@asteby/storefront/geo` ——与店面共用的一个地模. |

### 无障碍

-   每张地图都有对应的 **列表** ("Ver lista"),键盘可被接通,每个状态被写出并有一个"在地图中打开"链接. 当WebGL 或 MapLibre 不可用时, 列表是唯一的视图, 有信件这么说 .
-   标记为按钮 `aria-label`;颜色从来不是唯一的通道(状态文本,glyphs);弹出由文本节点构建(没有HTML注入).
-   `prefers-reduced-motion` 制造 `fitBounds` 编号 : `easeTo` 即时. 字符串可通过 `labels` (和 `metacore.maps.*` 键在渲染器中.

## 声明性观点(内核合同)

```ts
// host start-up — tiny and MapLibre-free
import { registerMapRenderers } from '@asteby/metacore-maps/register'

registerMapRenderers({ config: { style: { light: '…', dark: '…' } } })
```

这个叫 `registerViewRenderer('map', …)`, (中文(简体) ), `registerPanelRenderer('map', …)` 财务报告和审定财务报表 `registerPanelRenderer('timeline', …)` 与懒惰的装载者(`/view`, (中文(简体) ), `/panel`, (中文(简体) ), `/timeline-panel`) (中文(简体) ). 过 `{ timeline: false }` 保持运行时间的内置时间面板。 它制造出明显的碎片:

```jsonc
{ "view_type": "map",
  "view": { "map": { "point": { "lat": "dest_lat", "lng": "dest_lng" }, "color_by": "status",
                      "popup": ["tracking_number", "carrier", "status"], "cluster": true,
                      "layers": [{ "kind": "points", "model": "Branch", "point": { "lat": "lat", "lng": "lng" }, "label": "name" },
                                 { "kind": "zones",  "model": "Zone",   "geometry": "area", "label": "name" }] } } }

{ "kind": "map",      "map": { "point": {…}, "route": { "relation": "stops", "point": {…}, "order_by": "seq" } } }
{ "kind": "timeline", "timeline": { "date_field": "at", "title_field": "description", "status_field": "status",
                                    "source": { "capability": "commerce.shipping.track", "input": { "tracking_number": "record.tracking_number" }, "items": "events" } } }
```

行通过同样的纯帮助器成为其列表回落的运行时间用途的特性(`@asteby/metacore-runtime-react/views/map`因此,两个造物师都用同样的语言来阅读。 选项颜色和标签 `color_by` 列来自模型元数据; 渲染器显示服务器返回的内容,而从未计算商业值。 时间线活动开始 `location`编号 :`city` 财务报告和审定财务报表 `lat`编号 :`lng` 列当出.

## 测试

jsdom/happy-dom没有WebGL. 在你自己的测试中,通过一个接棒通过装载器:

```ts
configureMaps({ loadMaplibre: async () => myStub, supportsWebGL: () => true })
```

## 乔罗普莱尔

```tsx
<MapView points={[]}>
  <ChoroplethLayer loader={() => import('./estados.topo.json')} values={{ JAL: 120, CMX: 340 }} keyProperty="code" labelProperty="name" onRegions={setState} />
</MapView>
<ChoroplethList regions={state.regions} label="Ventas por estado" noData="Sin datos" />
```

几何学(GeoJSON或TopoJSON)来自主机/区域通过 `loader`,当层起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起 SDK船没有形状. `ChoroplethList` 是可获取的等同物(每个区域都有其价值).

## 常见问题

### @asteby/metacore-maps 是什么？

用于元主机和附加器的懒散地图 — MapView, 标记, 集群, 路线, 地峡, 位置选择器, 跟踪时间线和声明 map编号 :timeline 造物师\. MapLibre GL 按需加载; 无 API 密钥 \.

### 如何安装 @asteby/metacore-maps？

在项目目录运行 npm install @asteby/metacore-maps，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18）、react-dom（\>=18）、maplibre-gl（\>=4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @asteby/metacore-maps 支持 TypeScript 吗？

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

### @asteby/metacore-maps 支持 ESM 还是 CommonJS？

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

### @asteby/metacore-maps 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @asteby/metacore-maps 可以商用吗？

@asteby/metacore-maps 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @asteby/metacore-maps 的下载量有多少？

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

### @asteby/metacore-maps 还在维护吗？

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