@cn-map/gaode-vue 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -1,3 +1,294 @@
-# Temporary Holding Version
+# @cn-map/gaode-vue
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+高德地图 Vue 组件库，基于高德地图 JavaScript API 2.0 开发。提供了一套 Vue 3 组件、组合式函数和工具，用于构建高德地图应用。
+
+## 特性
+
+- 🎯 **类型友好** - 组件与 Hooks 提供类型定义
+- 🚀 **Vue 3 兼容** - 支持最新的 Vue 3 特性
+- 🎨 **丰富的组件** - 覆盖地图、覆盖物、图层、控件与常用工具
+- 🧩 **可与原生 API 混用** - WebService 等未封装能力可直接调用原生 `AMap.*`
+- 📊 **3D 可视化** - 基于 Loca 的可视化组件
+- 🛠️ **易于使用** - 简洁的 API 设计
+- 📦 **按需加载** - 支持组件按需导入
+- 🔧 **组合式 API** - 提供组合式函数，便于逻辑复用
+
+## 安装
+
+```bash
+npm install @cn-map/gaode-vue
+```
+
+```bash
+yarn add @cn-map/gaode-vue
+```
+
+```bash
+pnpm add @cn-map/gaode-vue
+```
+
+```bash
+bun add @cn-map/gaode-vue
+```
+
+TypeScript 类型见 [`@cn-map/gaode-types`](../types/README.md)。
+
+## 使用示例
+
+### 基础地图
+
+```vue
+<script setup lang="ts">
+  import { APILoader, LoadStatus, Map, Marker, useAPIStatus } from '@cn-map/gaode-vue'
+
+  const status = useAPIStatus('AMap')
+</script>
+
+<template>
+  <APILoader api-key="YOUR_AMAP_KEY">
+    <Map v-if="status === LoadStatus.Loaded" :center="[116.397428, 39.90923]" style="height: 400px" :zoom="13">
+      <Marker :position="[116.397428, 39.90923]" />
+    </Map>
+  </APILoader>
+</template>
+```
+
+or
+
+```vue
+<script setup lang="ts">
+  import { APILoader, LoadStatus, Map, Marker } from '@cn-map/gaode-vue'
+</script>
+
+<template>
+  <APILoader api-key="YOUR_AMAP_KEY">
+    <template #default="{ status }">
+      <Map v-if="status.AMap === LoadStatus.Loaded" :center="[116.397428, 39.90923]" style="height: 400px" :zoom="13">
+        <Marker :position="[116.397428, 39.90923]" />
+      </Map>
+    </template>
+  </APILoader>
+</template>
+```
+
+### 使用 Loca 可视化
+
+```vue
+<script setup lang="ts">
+  import { APILoader, LoadStatus, Map, useAPIStatus } from '@cn-map/gaode-vue'
+  import { GeoJSONSource, HeatMapLayer, Loca } from '@cn-map/gaode-vue/loca'
+
+  const status = useAPIStatus()
+</script>
+
+<template>
+  <APILoader :Loca="{}" api-key="YOUR_AMAP_KEY">
+    <Map
+      v-if="status.AMap === LoadStatus.Loaded"
+      :center="[102.618687, 31.790976]"
+      map-style="amap://styles/whitesmoke"
+      :pitch="40"
+      style="height: 400px"
+      view-mode="3D"
+      :zoom="4"
+      :zooms="[4, 7]"
+    >
+      <Loca v-if="status.Loca === LoadStatus.Loaded">
+        <GeoJSONSource url="https://a.amap.com/Loca/static/loca-v2/demos/mock_data/traffic.json">
+          <HeatMapLayer
+            :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"
+            :z-index="10"
+          />
+        </GeoJSONSource>
+      </Loca>
+    </Map>
+  </APILoader>
+</template>
+```
+
+## 核心组件
+
+### API 加载器
+
+| 导出名称           | 类型       | 描述                           |
+| ------------------ | ---------- | ------------------------------ |
+| `APILoader`        | 组件       | 高德地图 JavaScript API 加载器 |
+| `APILoaderOptions` | 类型       | APILoader 组件的配置选项       |
+| `LoadStatus`       | 枚举       | 表示加载状态的枚举值           |
+| `useAPIError`      | 组合式函数 | 获取 API 加载错误信息          |
+| `useAPILoader`     | 组合式函数 | 加载高德地图 API               |
+| `useAPIStatus`     | 组合式函数 | 检查 API 加载状态              |
+
+### 地图组件
+
+| 导出名称 | 类型       | 描述         |
+| -------- | ---------- | ------------ |
+| `Map`    | 组件       | 地图容器组件 |
+| `useMap` | 组合式函数 | 获取地图实例 |
+
+### 地图控制组件
+
+| 导出名称      | 类型 | 描述             |
+| ------------- | ---- | ---------------- |
+| `ControlBar`  | 组件 | 组合控件         |
+| `Geolocation` | 组件 | 定位控件         |
+| `HawkEye`     | 组件 | 鹰眼控件         |
+| `MapType`     | 组件 | 地图类型切换控件 |
+| `Scale`       | 组件 | 比例尺控件       |
+| `ToolBar`     | 组件 | 工具条控件       |
+
+### 地图图层
+
+| 导出名称                     | 类型 | 描述             |
+| ---------------------------- | ---- | ---------------- |
+| `Buildings`, `BuildingLayer` | 组件 | 楼块图层         |
+| `CanvasLayer`                | 组件 | Canvas 图层      |
+| `CustomLayer`                | 组件 | 自定义图层       |
+| `DistrictLayer`              | 组件 | 行政区图层       |
+| `Country`                    | 组件 | 国家图层         |
+| `Province`                   | 组件 | 省份图层         |
+| `World`                      | 组件 | 世界图层         |
+| `Flexible`                   | 组件 | 灵活切片图层     |
+| `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`          | 组件 | 文本标记       |
+| `VectorOverlay` | 组件 | 矢量图形覆盖物 |
+
+### 工具组件
+
+| 导出名称            | 类型 | 描述             |
+| ------------------- | ---- | ---------------- |
+| `BezierCurveEditor` | 组件 | 贝塞尔曲线编辑器 |
+| `CircleEditor`      | 组件 | 圆形编辑器       |
+| `EllipseEditor`     | 组件 | 椭圆编辑器       |
+| `MouseTool`         | 组件 | 鼠标工具         |
+| `PolygonEditor`     | 组件 | 多边形编辑器     |
+| `PolylineEditor`    | 组件 | 折线编辑器       |
+| `RangingTool`       | 组件 | 测距工具         |
+| `RectangleEditor`   | 组件 | 矩形编辑器       |
+
+## Loca 可视化组件
+
+基于 Loca 库的高级 3D 可视化组件，从 `@cn-map/gaode-vue/loca` 导入：：
+
+### Loca 容器
+
+| 导出名称  | 类型       | 描述           |
+| --------- | ---------- | -------------- |
+| `Loca`    | 组件       | Loca 容器组件  |
+| `useLoca` | 组合式函数 | 访问 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 数据源   |
+
+## 组合式函数
+
+### 实例相关
+
+| 导出名称      | 描述                         |
+| ------------- | ---------------------------- |
+| `useInstance` | 获取组件实例的通用组合式函数 |
+
+## 相关链接
+
+- [高德地图 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-BEyZOuBr.js

@@ -0,0 +1,88 @@
+import { computed, inject, provide, shallowRef, toRaw, watchEffect } from "vue";
+import { lostContextError, lowercase } from "@cn-map/gaode-shared/utils";
+// src/composables/use-event-listeners.ts
+var use_event_listeners_default = (target, emits, eventTypes = []) => {
+	watchEffect((onCleanup) => {
+		const cleanupFunctions = [];
+		for (const eventType of eventTypes) {
+			const handler = (e) => emits(eventType, e);
+			target.value?.on(lowercase(eventType), handler);
+			cleanupFunctions.push(() => {
+				target.value?.off(lowercase(eventType), handler);
+			});
+		}
+		onCleanup(() => {
+			cleanupFunctions.forEach((cleanup) => cleanup());
+		});
+	});
+};
+// src/utils/helpers.ts
+/**
+* Creates a reactive proxy that omits specific keys from props.
+* Preserves the original semantic type name layout instead of expanding it.
+*/
+function shallowReactiveOmit(props, ...keys) {
+	const flatKeys = new Set(keys.flat(Infinity));
+	return new Proxy(props, {
+		get(target, key, receiver) {
+			if (flatKeys.has(key)) return;
+			return Reflect.get(target, key, receiver);
+		},
+		has(target, key) {
+			if (flatKeys.has(key)) return false;
+			return Reflect.has(target, key);
+		},
+		ownKeys(target) {
+			return Reflect.ownKeys(target).filter((key) => !flatKeys.has(key));
+		},
+		getOwnPropertyDescriptor(target, key) {
+			if (flatKeys.has(key)) return;
+			return Reflect.getOwnPropertyDescriptor(target, key);
+		}
+	});
+}
+/**
+* Creates a new object composed of the properties that are not undefined.
+*
+* Keys are enumerated via `Object.keys(props)` so proxy-based omit helpers like
+* `shallowReactiveOmit` keep applying their key filtering, while values are read
+* from the raw object (`toRaw`) to avoid triggering reactivity tracking.
+*/
+function toDefinedRaw(props) {
+	const result = {};
+	const obj = toRaw(props);
+	const keys = Object.keys(props);
+	for (let i = 0; i < keys.length; i++) {
+		const key = keys[i];
+		const value = obj[key];
+		if (value !== void 0) result[key] = toRaw(value);
+	}
+	return result;
+}
+// src/map/context.ts
+const AMap_Symbol_Map = Symbol("Map");
+/**
+* 设置地图实例Context
+* @param {ShallowRef<Nullable<AMap.Map>>} map - 地图实例ref
+*/
+function setMapContext(map) {
+	provide(AMap_Symbol_Map, map);
+}
+/**
+* 获取地图实例
+* @returns {ShallowRef<Nullable<AMap.Map>>} - 地图实例ref
+*/
+function useMap() {
+	const context = inject(AMap_Symbol_Map);
+	if (!context) throw lostContextError("`AMap.Map`");
+	return context;
+}
+/**
+* 获取地图实例
+* @returns {ComputedRef<Nullable<AMap.Map>>} - 地图实例ref
+*/
+function useMapInstance(props) {
+	const map = inject(AMap_Symbol_Map, shallowRef(null));
+	return computed(() => props.map ?? map.value);
+}
+export { toDefinedRaw as a, shallowReactiveOmit as i, useMap as n, use_event_listeners_default as o, useMapInstance as r, setMapContext as t };