# @craft-native/ts-maps 中文文档

规范地址：https://npmcn.com/package/%40craft-native/ts-maps/

版本：0\.0\.413
npm 元数据更新时间：2026-10-31T21:01:51.931Z
中文译文更新时间：2026-10-31T21:17:18.007Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：2.4 MB，31 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-05-12T23:44:52.774Z
- 最新版本发布：2026-10-31T21:01:51.416Z
- 已发布版本数：213（近 12 个月 213 个）

## 中文简介

为ts-maps交互式地图运行时制作SDK绑定。提供一个由MapProvider支持的跨平台MapView组件。Zig核心中的ts\_maps变量。

## 安装

```sh
npm install @craft-native/ts-maps
```

也可以使用：`pnpm add @craft-native/ts-maps`、`yarn add @craft-native/ts-maps`、`bun add @craft-native/ts-maps`

## README

# @craft-native / ts-maps

制作SDK绑定 [ts-maps](https://github.com/stacksjs/ts-maps) 交互式地图运行时。

的TypeScript端 `MapProvider.ts_maps` 在Craft的Zig核心。 它的 `MapView` 拥有一个DOM容器，并在浏览器或 WebView，没有API键。它不是STX原生的 `Map` 组件。

对于一个完全本地的STX屏幕，使用 `Map`， `MapMarker`, `MapPolyline`. Craft使用MapKit在iOS和配置的原生Android地图上渲染它们 提供者。安卓的 `mapProvider: 'maplibre'` 选择一个无键的本地GL视图； 它不挂载这个包的DOM适配器。

## 安装

```bash
bun add @craft-native/ts-maps
```

## 快速启动

```ts
import { createMapView, defaultMapConfiguration, tsMapsProvider } from '@craft-native/ts-maps'

const view = createMapView({
  configuration: { ...defaultMapConfiguration, provider: tsMapsProvider },
  initialCamera: {
    center: { latitude: 37.7749, longitude: -122.4194 },
    zoom: 12,
    pitch: 0,
    heading: 0,
  },
  markers: [
    {
      id: 1,
      coordinate: { latitude: 37.7749, longitude: -122.4194 },
      title: 'San Francisco',
      subtitle: null,
      color: 'red',
      is_draggable: false,
      is_selected: false,
      custom_icon: null,
      anchor_x: 0.5,
      anchor_y: 1,
    },
  ],
  onTap: (coord) => console.log('tapped', coord),
  onMarkerTap: (id, coord) => console.log('marker', id, coord),
})

document.body.appendChild(view.container)
```

## API概述

| 出口 | 它是什么？ |
| --- | --- |
| `createMapView(props)` | 工厂返回 `MapViewInstance` 与 `id`， `container`， `map`，以及命令式方法(`setCamera`， `addMarker`， `fitToMarkers`,……)。 |
| `MapViewProps` / `MapViewInstance` | 组件的类型。 |
| `Coordinate`， `MapRegion`， `MapCamera`， `MapMarker`,…… | 中的结构体的镜像 `packages/zig/src/maps.zig`． 字段名完全匹配，因此JSON往返是免费的。 |
| `craftCoordToLatLng`， `latLngToCraftCoord`， `craftRegionToBounds`， `craftCameraToOptions`， `craftMarkerToMarker`,…… | Craft和ts-map类型之间的纯适配器函数。 |
| `tsMapsProvider` | 常数 `'ts_maps'` 匹配枚举标记的。 |
| 从 `ts-maps` | `TsMap`， `LatLng`， `Marker`， `Polyline`， `marker()`， `tileLayer()`等都是再出口的，所以你只需要一次进口。 |

## 桥的协议

当在Craft WebView中运行时， `createMapView` 将自身注册为 `getBridge()` 并监听中声明的方法 `./bridge-protocol`：

-   `setCamera`， `setRegion`， `addMarker`， `removeMarker`， `addPolyline`， `addPolygon`， `addCircle`， `fitToMarkers`， `selectMarker`， `deselectAll`， `setConfiguration`.

它返回这些事件：

-   `map:tap`， `map:markerTap`， `map:regionChanged`， `map:cameraChanged`.

如果没有桥接可用（仅限浏览器、测试等），组件就会静默地退回到仅限本地的行为——通过props传递的事件回调仍然会触发。

## 开发

```bash
bun run typecheck
bun test
bunx --bun pickier .
```

## 常见问题

### @craft-native/ts-maps 是什么？

为ts-maps交互式地图运行时制作SDK绑定。提供一个由MapProvider支持的跨平台MapView组件。Zig核心中的ts\_maps变量。

### 如何安装 @craft-native/ts-maps？

在项目目录运行 npm install @craft-native/ts-maps，或使用 pnpm add / yarn add / bun add。

### @craft-native/ts-maps 支持 TypeScript 吗？

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

### @craft-native/ts-maps 支持 ESM 还是 CommonJS？

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

### @craft-native/ts-maps 可以商用吗？

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

### @craft-native/ts-maps 还在维护吗？

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