@cn-map/gaode-react 0.0.0 → 0.0.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024-present Jungzl.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2024-present Jungzl.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,307 @@
 # @cn-map/gaode-react
 
-高德地图 react 组件。
+高德地图 React 组件库，基于高德地图 JavaScript API 2.0 开发。提供了一套 React 组件、Hooks 和工具，用于构建高德地图应用。
 
-- 仓库：https://github.com/Jungzl/amap
-- 许可证：MIT
+## 特性
+
+- 🎯 **类型友好** - 组件与 Hooks 提供类型定义
+- 🚀 **React 19 兼容** - 支持最新的 React 特性
+- 🎨 **丰富的组件** - 覆盖地图、覆盖物、图层、控件与常用工具
+- 🧩 **可与原生 API 混用** - WebService 等未封装能力可直接调用原生 `AMap.*`
+- 📊 **3D 可视化** - 基于 Loca 的可视化组件
+- 🛠️ **易于使用** - 简洁的 API 设计
+- 📦 **按需加载** - 支持组件按需导入
+
+## 安装
+
+```bash
+npm install @cn-map/gaode-react
+```
+
+```bash
+yarn add @cn-map/gaode-react
+```
+
+```bash
+pnpm add @cn-map/gaode-react
+```
+
+```bash
+bun add @cn-map/gaode-react
+```
+
+TypeScript 类型见 [`@cn-map/gaode-types`](../types/README.md)。
+
+## 使用示例
+
+### 基础地图
+
+```tsx
+import { APILoader, LoadStatus, Map, Marker, useAPIStatus } from '@cn-map/gaode-react'
+
+const App = () => {
+  const status = useAPIStatus('AMap')
+
+  return (
+    <APILoader apiKey="YOUR_AMAP_KEY">
+      {status === LoadStatus.Loaded && (
+        <Map center={[116.397428, 39.90923]} style={{ height: '400px' }} zoom={13}>
+          <Marker position={[116.397428, 39.90923]} />
+        </Map>
+      )}
+    </APILoader>
+  )
+}
+
+export default App
+```
+
+or
+
+```tsx
+import { APILoader, LoadStatus, Map, Marker } from '@cn-map/gaode-react'
+
+const App = () => {
+  return (
+    <APILoader apiKey="YOUR_AMAP_KEY">
+      {status => {
+        if (status.AMap === LoadStatus.Loaded) {
+          return (
+            <Map center={[116.397428, 39.90923]} style={{ height: '400px' }} zoom={13}>
+              <Marker position={[116.397428, 39.90923]} />
+            </Map>
+          )
+        }
+      }}
+    </APILoader>
+  )
+}
+
+export default App
+```
+
+### 使用 Loca 可视化
+
+```tsx
+import { APILoader, LoadStatus, Map, useAPIStatus } from '@cn-map/gaode-react'
+import { GeoJSONSource, HeatMapLayer, Loca } from '@cn-map/gaode-react/loca'
+
+const App = () => {
+  const status = useAPIStatus()
+
+  return (
+    <APILoader apiKey={import.meta.env.VITE_AMAP_KEY} Loca={{}}>
+      {status.AMap === LoadStatus.Loaded && (
+        <Map
+          center={[102.618687, 31.790976]}
+          mapStyle="amap://styles/whitesmoke"
+          pitch={40}
+          style={{ height: '400px' }}
+          viewMode="3D"
+          zoom={4}
+          zooms={[4, 7]}
+        >
+          {status.Loca === LoadStatus.Loaded && (
+            <Loca>
+              <GeoJSONSource url="https://a.amap.com/Loca/static/loca-v2/demos/mock_data/traffic.json">
+                <HeatMapLayer<{
+                  avg: number
+                  city: string
+                  index: number
+                  lnglat: string
+                  mom: string
+                  prov: string
+                  ranking: number
+                  yoy: string
+                }>
+                  opacity={1}
+                  style={{
+                    gradient: {
+                      0.1: '#2A85B8',
+                      0.2: '#16B0A9',
+                      0.3: '#29CF6F',
+                      0.4: '#5CE182',
+                      0.5: '#7DF675',
+                      0.6: '#FFF100',
+                      0.7: '#FAA53F',
+                      1.0: '#D04343',
+                    },
+                    height: 500000,
+                    heightBezier: [0, 0.53, 0.37, 0.98],
+                    radius: 200000,
+                    value(index, feature) {
+                      const value = Number.parseFloat(feature.properties.mom)
+                      return value + 10 * Math.random()
+                    },
+                    unit: 'meter',
+                  }}
+                  visible={true}
+                  zIndex={10}
+                />
+              </GeoJSONSource>
+            </Loca>
+          )}
+        </Map>
+      )}
+    </APILoader>
+  )
+}
+
+export default App
+```
+
+## 核心组件
+
+### API 加载器
+
+| 导出名称           | 类型 | 描述                           |
+| ------------------ | ---- | ------------------------------ |
+| `APILoader`        | 组件 | 高德地图 JavaScript API 加载器 |
+| `APILoaderOptions` | 类型 | APILoader 组件的配置选项       |
+| `LoadStatus`       | 枚举 | 表示加载状态的枚举值           |
+| `useAPIError`      | Hook | 获取 API 加载错误信息的钩子    |
+| `useAPILoader`     | Hook | 加载高德地图 API 的钩子        |
+| `useAPIStatus`     | Hook | 检查 API 加载状态的钩子        |
+
+### 地图组件
+
+| 导出名称 | 类型 | 描述               |
+| -------- | ---- | ------------------ |
+| `Map`    | 组件 | 地图容器组件       |
+| `useMap` | Hook | 获取地图实例的钩子 |
+
+### 地图控制组件
+
+| 导出名称      | 类型 | 描述             |
+| ------------- | ---- | ---------------- |
+| `ControlBar`  | 组件 | 组合控件         |
+| `Geolocation` | 组件 | 定位控件         |
+| `HawkEye`     | 组件 | 鹰眼控件         |
+| `MapType`     | 组件 | 地图类型切换控件 |
+| `Scale`       | 组件 | 比例尺控件       |
+| `ToolBar`     | 组件 | 工具条控件       |
+
+### 地图图层
+
+| 导出名称                     | 类型 | 描述             |
+| ---------------------------- | ---- | ---------------- |
+| `Buildings`, `BuildingLayer` | 组件 | 楼块图层         |
+| `CanvasLayer`                | 组件 | Canvas 图层      |
+| `CustomLayer`                | 组件 | 自定义图层       |
+| `DistrictLayer`              | 组件 | 行政区图层       |
+| `Country`                    | 组件 | 国家图层         |
+| `Province`                   | 组件 | 省份图层         |
+| `World`                      | 组件 | 世界图层         |
+| `GLCustomLayer`              | 组件 | WebGL 自定义图层 |
+| `HeatMap`                    | 组件 | 热力图图层       |
+| `ImageLayer`                 | 组件 | 图片图层         |
+| `IndoorMap`                  | 组件 | 室内地图图层     |
+| `LabelsLayer`                | 组件 | 标注图层         |
+| `LayerGroup`                 | 组件 | 图层群组         |
+| `Mapbox`                     | 组件 | Mapbox 图层      |
+| `MapboxVectorTileLayer`      | 组件 | MVT 图层         |
+| `TileLayer`                  | 组件 | 切片图层         |
+| `Flexible`                   | 组件 | 灵活切片图层     |
+| `Mark`                       | 组件 | 白嫖标记图层     |
+| `RoadNet`                    | 组件 | 路网图层         |
+| `Satellite`                  | 组件 | 卫星图层         |
+| `Traffic`                    | 组件 | 实时交通图层     |
+| `WMS`                        | 组件 | WMS 图层         |
+| `WMTS`                       | 组件 | WMTS 图层        |
+| `VectorLayer`                | 组件 | 矢量图层         |
+
+### 覆盖物组件
+
+| 导出名称        | 类型 | 描述       |
+| --------------- | ---- | ---------- |
+| `BezierCurve`   | 组件 | 贝塞尔曲线 |
+| `Circle`        | 组件 | 圆形       |
+| `CircleMarker`  | 组件 | 圆点标记   |
+| `ContextMenu`   | 组件 | 右键菜单   |
+| `ElasticMarker` | 组件 | 灵活点标记 |
+| `Ellipse`       | 组件 | 椭圆       |
+| `IndexCluster`  | 组件 | 索引点聚合 |
+| `InfoWindow`    | 组件 | 信息窗体   |
+| `LabelMarker`   | 组件 | 标注标记   |
+| `Marker`        | 组件 | 点标记     |
+| `MarkerCluster` | 组件 | 点聚合     |
+| `MassMarks`     | 组件 | 海量点     |
+| `OverlayGroup`  | 组件 | 覆盖物群组 |
+| `Polygon`       | 组件 | 多边形     |
+| `Polyline`      | 组件 | 折线       |
+| `Rectangle`     | 组件 | 矩形       |
+| `Text`          | 组件 | 文本标记   |
+
+### 工具组件
+
+| 导出名称            | 类型 | 描述             |
+| ------------------- | ---- | ---------------- |
+| `BezierCurveEditor` | 组件 | 贝塞尔曲线编辑器 |
+| `CircleEditor`      | 组件 | 圆形编辑器       |
+| `EllipseEditor`     | 组件 | 椭圆编辑器       |
+| `MouseTool`         | 组件 | 鼠标工具         |
+| `PolygonEditor`     | 组件 | 多边形编辑器     |
+| `PolylineEditor`    | 组件 | 折线编辑器       |
+| `RangingTool`       | 组件 | 测距工具         |
+| `RectangleEditor`   | 组件 | 矩形编辑器       |
+
+## Loca 可视化组件
+
+基于 Loca 库的高级 3D 可视化组件，从 `@cn-map/gaode-react/loca` 导入：：
+
+### Loca 容器
+
+| 导出名称  | 类型 | 描述                 |
+| --------- | ---- | -------------------- |
+| `Loca`    | 组件 | Loca 容器组件        |
+| `useLoca` | Hook | 访问 Loca 实例的钩子 |
+
+### Loca 图层
+
+| 导出名称         | 类型 | 描述         |
+| ---------------- | ---- | ------------ |
+| `GridLayer`      | 组件 | 网格图层     |
+| `HeatMapLayer`   | 组件 | 热力图图层   |
+| `HexagonLayer`   | 组件 | 蜂窝图层     |
+| `IconLayer`      | 组件 | 图标图层     |
+| `LabelsLayer`    | 组件 | 标注图层     |
+| `LaserLayer`     | 组件 | 激光图层     |
+| `LineLayer`      | 组件 | 线图层       |
+| `LinkLayer`      | 组件 | 连接图层     |
+| `PointLayer`     | 组件 | 点图层       |
+| `PolygonLayer`   | 组件 | 面图层       |
+| `PrismLayer`     | 组件 | 棱柱图层     |
+| `PulseLineLayer` | 组件 | 脉冲线图层   |
+| `PulseLinkLayer` | 组件 | 脉冲连接图层 |
+| `ScatterLayer`   | 组件 | 散点图层     |
+| `ZMarkerLayer`   | 组件 | Z轴标记图层  |
+
+### Loca 光照
+
+| 导出名称           | 类型 | 描述   |
+| ------------------ | ---- | ------ |
+| `AmbientLight`     | 组件 | 环境光 |
+| `DirectionalLight` | 组件 | 平行光 |
+| `PointLight`       | 组件 | 点光源 |
+
+### Loca UI 组件
+
+| 导出名称 | 类型 | 描述     |
+| -------- | ---- | -------- |
+| `Legend` | 组件 | 图例组件 |
+
+### Loca 数据源
+
+| 导出名称          | 类型 | 描述             |
+| ----------------- | ---- | ---------------- |
+| `GeoBufferSource` | 组件 | GeoBuffer 数据源 |
+| `GeoJSONSource`   | 组件 | GeoJSON 数据源   |
+
+## 相关链接
+
+- [高德地图 JavaScript API 文档](https://lbs.amap.com/api/jsapi-v2/summary)
+- [Loca 可视化文档](https://lbs.amap.com/api/loca-v2/intro)
+
+## 许可证
+
+[MIT](https://github.com/Jungzl/amap/blob/main/LICENSE)

package/dist/context-ChPGCKoP.js

@@ -0,0 +1,100 @@
+import { createContext, use, useEffect, useEffectEvent, useState } from "react";
+import { eventToProp, lostContextError, lowercase } from "@cn-map/gaode-shared/utils";
+// src/hooks/use-event-listeners.ts
+function useEventListeners(target, eventProps, eventTypes = []) {
+	const getHandler = useEffectEvent((eventType) => {
+		return eventProps[eventToProp(eventType)];
+	});
+	useEffect(() => {
+		const _target = typeof target === "function" ? target() : target;
+		if (!_target) return;
+		const cleanupFunctions = [];
+		for (const eventType of eventTypes) {
+			const handler = (event) => {
+				getHandler(eventType)?.(event);
+			};
+			_target.on(lowercase(eventType), handler);
+			cleanupFunctions.push(() => {
+				_target.off(lowercase(eventType), handler);
+			});
+		}
+		return () => {
+			cleanupFunctions.forEach((cleanup) => cleanup());
+		};
+	}, [target, eventTypes]);
+}
+// src/hooks/use-lazy-init.ts
+function useLazyInit(init) {
+	const [instance] = useState(init);
+	return instance;
+}
+// src/utils/helpers.ts
+/**
+* Splits an object into multiple objects based on the specified keys. [solid-js `splitProps`](https://github.com/solidjs/solid/blob/62305456041c0970f628449c67bc2579af330940/packages/solid/src/server/rendering.ts#L138)
+* @param props
+* @param keys
+*/
+function splitProps(props, ...keys) {
+	const descriptors = Object.getOwnPropertyDescriptors(props);
+	const split = (k) => {
+		const clone = {};
+		for (let i = 0; i < k.length; i++) {
+			const key = k[i];
+			if (descriptors[key]) {
+				Object.defineProperty(clone, key, descriptors[key]);
+				delete descriptors[key];
+			}
+		}
+		return clone;
+	};
+	return keys.map(split).concat(split(Reflect.ownKeys(descriptors)));
+}
+/**
+* Type guard to check if a value is a React ref object
+* @param ref The value to check
+* @returns True if the value is a ref object, false otherwise
+*/
+function isRefObject(ref) {
+	return ref !== null && typeof ref === "object" && Object.prototype.hasOwnProperty.call(ref, "current");
+}
+/**
+* Resolve target from RefObject, accessor function, or direct instance.
+*
+* @template T The type of the target instance
+* @param {Target<T>} target The target to resolve, which can be a RefObject, an accessor function, or a direct instance
+* @returns The resolved instance or undefined
+*/
+function resolveTarget(target) {
+	return isRefObject(target) ? target.current : typeof target === "function" ? target() : target;
+}
+/**
+* Synchronize a property of an instance with a given value.
+*
+* @template T The type of the instance
+* @template K The key of the property to synchronize
+* @param {T} instance The instance whose property is to be synchronized
+* @param {K} property The key of the property to synchronize
+* @param {T[K]} value The value to set for the property
+*/
+function syncProperty(instance, property, value) {
+	instance[property] = value;
+}
+// src/map/context.ts
+const EMPTY = Symbol("No Map");
+const MapContext = createContext(EMPTY);
+/**
+* 获取地图实例 hook
+*/
+function useMap() {
+	const map = use(MapContext);
+	if (map === EMPTY) throw lostContextError("`AMap.Map`");
+	return map;
+}
+/**
+* 获取合并props的地图实例
+*/
+function useMapInstance(mapInProps) {
+	const mapInCtx = use(MapContext);
+	return mapInProps ?? (mapInCtx === EMPTY ? null : mapInCtx);
+}
+export { splitProps as a, useEventListeners as c, resolveTarget as i, useMap as n, syncProperty as o, useMapInstance as r, useLazyInit as s, MapContext as t };