tdt-map-vue 1.0.0

package/README.md

@@ -0,0 +1,243 @@
+# @80458/tdt-map
+
+一个基于 **Vue 2 / Vue 3** 的天地图（Tianditu）地图组件库，面向实际业务场景封装了地图初始化、标注管理、文字标签、信息窗体、地理编码搜索和组件实例方法调用等能力。你可以像使用普通 Vue 组件一样快速接入到项目中，也可以通过 `ref` 控制地图的增删改查、搜索定位和视图刷新，适合用于后台管理系统、地理信息展示页面、业务地图看板等场景。
+
+## 特性
+
+- 同时兼容 Vue 2 与 Vue 3，可直接在不同版本项目中复用
+- 自动加载天地图 JS API，无需在业务项目里手动引入脚本
+- 支持地图初始化，并可配置中心点、缩放级别、最小/最大缩放范围
+- 支持拖拽、滚轮缩放、缩放控件等常用地图交互能力
+- 支持自定义标注图标、文字标签、信息窗内容
+- 支持新增标注、隐藏标注、获取全部标注和销毁地图实例
+- 支持地理编码搜索，可根据地址关键字快速定位
+- 支持通过 `ref` 调用组件公开方法，便于在业务代码中做二次控制
+
+## 安装
+
+```bash
+npm install tdt-map-vue  --save
+```
+
+如果你使用的是 Vue 3 项目，通常只需要正常安装即可；如果是 Vue 2 项目，则需要确保 `vue-demi` 的运行环境配置正确。组件库内部通过 `vue-demi` 做了兼容处理，因此同一套 API 可以在两种版本中使用。
+
+### 安装说明
+
+- **Vue 2**：确保项目中已正确配置 `vue-demi` 所需环境
+- **Vue 3**：正常安装即可
+
+> 组件库通过 `vue-demi` 处理 Vue 2 / Vue 3 兼容场景。
+
+## 快速开始
+
+下面分别给出 Vue 2 和 Vue 3 的使用方式。无论哪种版本，都可以通过组件形式直接渲染地图，并通过 `tk` 传入天地图 API Key。
+
+###  全局注册
+
+```js
+import Vue from "vue";
+import TiandiMap from "tdt-map-vue";
+
+Vue.use(TiandiMap);
+```
+
+### 局部注册
+
+```vue
+<template>
+  <TiandiMap tk="your-tianditu-api-key" :zoom="12" />
+</template>
+
+<script>
+import TiandiMap from "tdt-map-vue
+
+export default {
+  components: {
+    TiandiMap,
+  },
+};
+</script>
+```
+
+## 通过 `ref` 调用方法
+
+组件支持通过 `ref` 直接调用实例方法，这也是它比较适合做业务封装的原因之一。比如你可以在按钮点击后新增标注、清空搜索条件、重新计算地图尺寸，或者根据外部业务状态控制地图行为，而不必把逻辑全部写死在地图组件内部。
+
+### 常用方法
+
+- `addMarkers(markers)`：新增标注
+- `clearSearch()`：清空搜索框
+- `geocodeSearch(keyword)`：地理编码搜索
+- `hideMarkers(markers)`：隐藏标注
+- `getAllMarkers()`：获取全部标注
+- `destroyMap()`：销毁地图
+- `resizeMap()`：重新计算地图尺寸
+
+### Vue 3 示例
+
+```vue
+<template>
+  <div>
+    <TiandiMap ref="mapRef" tk="your-tianditu-api-key" :zoom="12" />
+    <button @click="addMarker">添加标注</button>
+  </div>
+</template>
+
+<script>
+import { ref } from "vue";
+import TiandiMap from "tdt-map-vue"
+
+export default {
+  components: {
+    TiandiMap,
+  },
+  setup() {
+    const mapRef = ref(null);
+
+    const addMarker = () => {
+      mapRef.value?.addMarkers([
+        {
+          lng: 116.397428,
+          lat: 39.90923,
+          option: {
+            content: "<div>北京</div>",
+          },
+        },
+      ]);
+    };
+
+    return {
+      mapRef,
+      addMarker,
+    };
+  },
+};
+</script>
+```
+
+### Vue 2 示例
+
+```vue
+<template>
+  <div>
+    <TiandiMap ref="mapRef" tk="your-tianditu-api-key" :zoom="12" />
+    <button @click="addMarker">添加标注</button>
+  </div>
+</template>
+
+<script>
+export default {
+  methods: {
+    addMarker() {
+      this.$refs.mapRef.addMarkers([
+        {
+          lng: 116.397428,
+          lat: 39.90923,
+          option: {
+            content: "<div>北京</div>",
+          },
+        },
+      ]);
+    },
+  },
+};
+</script>
+```
+
+## Props
+
+这些属性用于控制地图的初始状态和交互行为。对于大多数业务场景，你只需要传入 `tk`、中心点和缩放级别即可；如果需要更强的定制能力，还可以继续配置标注、拖拽、滚轮缩放等选项。
+
+| 参数              | 类型      | 默认值                              | 说明             |
+| ----------------- | --------- | ----------------------------------- | ---------------- |
+| `tk`              | `String`  | 必填                                | 天地图 API Key   |
+| `version`         | `String`  | `4.0`                               | 天地图 API 版本  |
+| `containerStyle`  | `Object`  | `{ width: '100%', height: '100%' }` | 地图容器样式     |
+| `center`          | `Array`  | `[117.017362,25.075884]`             | 地图中心点经度   |
+| `zoom`            | `Number`  | `10`                                | 初始缩放级别     |
+| `minZoom`         | `Number`  | `1`                                 | 最小缩放级别     |
+| `maxZoom`         | `Number`  | `18`                                | 最大缩放级别     |
+| `markers`         | `Array`   | `[]`                                | 初始标注数组     |
+| `dragEnable`      | `Boolean` | `true`                              | 是否允许拖拽     |
+| `scrollWheelZoom` | `Boolean` | `true`                              | 是否允许滚轮缩放 |
+
+## Events
+
+组件在地图初始化、标注点击、搜索结果和异常场景下都会向外抛出事件，便于业务层统一处理状态、提示信息和联动操作。
+
+| 事件名           | 参数                      | 说明                       |
+| ---------------- | ------------------------- | -------------------------- |
+| `ready`          | `(map)`                   | 地图初始化完成             |
+| `error`          | `(error)`                 | 地图初始化、加载或搜索失败 |
+| `marker-click`   | `({ markerData, event })` | 标注点击事件               |
+| `addsuccess`     | `(markers)`               | 新增标注成功               |
+| `hidesuccess`    | `()`                      | 隐藏标注成功               |
+| `search-success` | `(location)`              | 地理编码搜索成功           |
+| `search-error`   | `(error)`                 | 地理编码搜索失败           |
+
+window.T.Map 地图对象
+window.T.Marker 标记对象
+window.T.InfoWindow 信息窗口对象
+window.T.LngLat 经纬度对象
+window.T.Point 点位/偏移对象
+map 天地图对象 可以拿来调用原生的api
+
+## 标注数据格式
+
+标注数据建议统一使用数组结构传入，每一项都可以包含坐标、唯一标识和扩展配置。`option` 中支持图标、文字标签和弹窗内容，因此既能展示基础点位，也能满足更复杂的业务展示需求。
+
+```js
+[
+  {
+    id: "marker-1",
+    lng: 116.397428,
+    lat: 39.90923,
+    option: {
+      iconInfo: {
+        icon: "https://example.com/icon.png",
+        offsetX: 32,
+        offsetY: 32,
+      },
+      content: "<div>北京市中心</div>",
+      textInfo: {
+        text: "北京",
+        offsetX: 0,
+        offsetY: -30,
+      },
+    },
+  },
+];
+```
+
+## 常见问题
+
+下面整理了一些接入时最容易遇到的问题，建议在安装和使用前先快速浏览一遍，可以节省很多排查时间。
+
+### 1. Vue 2 项目里能用吗？
+
+可以，当前组件库就是按 Vue 2 / Vue 3 双兼容方向整理的。
+
+### 2. Vue 3 能通过 ref 调用方法吗？
+
+可以，直接通过 `ref` 访问组件实例并调用公开方法。
+
+### 3. 地图不显示怎么办？
+
+请检查以下几点：
+
+- `tk` 是否填写正确
+- 页面容器是否设置了高度
+- 天地图 API 是否能正常加载
+- 当前网络环境是否允许访问天地图资源
+
+### 4. 标注不显示怎么办？
+
+请确认：
+
+- `lng` 和 `lat` 是数字
+- `markers` 是数组
+- 地图已经初始化完成
+
+## License
+
+MIT