tdt-map-vue 1.0.2 → 1.0.4

package/README.md

@@ -1,6 +1,8 @@
 # tdt-map-vue
 
-一个基于 **Vue 2 / Vue 3** 的天地图（Tianditu）地图组件库，面向实际业务场景封装了地图初始化、标注管理、文字标签、信息窗体、地理编码搜索和组件实例方法调用等能力。你可以像使用普通 Vue 组件一样快速接入到项目中，也可以通过 `ref` 控制地图的增删改查、搜索定位和视图刷新，适合用于后台管理系统、地理信息展示页面、业务地图看板等场景。
+`tdt-map-vue` 是一个基于 **Vue 2 / Vue 3** 的天地图（Tianditu）地图组件库，适合快速集成到后台管理系统、地理信息展示页面、业务看板等项目中。
+
+它对天地图常用能力做了二次封装，包括地图初始化、标注管理、文字标签、信息窗体、地理编码搜索，以及通过 `ref` 调用组件方法进行二次控制。
 
 ## 特性
 
@@ -12,18 +14,19 @@
 - 支持新增标注、隐藏标注、获取全部标注和销毁地图实例
 - 支持地理编码搜索，可根据地址关键字快速定位
 - 支持通过 `ref` 调用组件公开方法，便于在业务代码中做二次控制
+- 提供稳定的 npm 发布结构，便于在 Vue 2 / Vue 3 项目中直接安装使用
 
 ## 安装
 
 ```bash
-npm install tdt-map-vue --save
+npm install tdt-map-vue  --save
 ```
 
 如果你使用的是 Vue 3 项目，通常只需要正常安装即可；如果是 Vue 2 项目，则需要确保 `vue-demi` 的运行环境配置正确。组件库内部通过 `vue-demi` 做了兼容处理，因此同一套 API 可以在两种版本中使用。
 
 ### 安装说明
 
-- **Vue 2**：确保项目中已正确配置 `vue-demi` 所需环境
+- **Vue 2**：确保项目中已正确配置 `vue-demi` 和 `vue-template-compiler` 所需环境
 - **Vue 3**：正常安装即可
 
 > 组件库通过 `vue-demi` 处理 Vue 2 / Vue 3 兼容场景。
@@ -42,7 +45,7 @@ npm install tdt-map-vue --save
 
 - CommonJS 入口：`dist/index.cjs.js`
 - ESM 入口：`dist/index.es.js`
-- UMD 产物：`dist/vue2/index.umd.js`、`dist/vue3/index.umd.js`
+- UMD 产物：`dist/index.umd.js`
 
 > 注意：Vue 2 项目应优先使用 `require` / `main` 对应的 CJS 入口；Vue 3 项目优先使用 `import` / `module` 对应的 ESM 入口。
 
@@ -106,9 +109,163 @@ export default {
 - `geocodeSearch(keyword)`：地理编码搜索
 - `hideMarkers(markers)`：隐藏标注
 - `getAllMarkers()`：获取全部标注
+- `setCenterAndZoom(center, zoom)`：设置地图中心点和缩放级别
+- `getMapLngLat()`：获取当前拾取到的坐标点
+- `getLngLat(lnglat)`：由坐标拾取回调写入当前坐标
 - `destroyMap()`：销毁地图
 - `resizeMap()`：重新计算地图尺寸
 
+### 方法使用示例
+
+下面给出几个最常用的方法调用示例，方便父组件通过 `ref` 直接控制地图。
+
+#### 1. 新增标注 `addMarkers(markers)`
+
+`markers` 参数是一个数组，每一项的格式如下：
+
+```js
+[
+  {
+    id: "marker-1",
+    lng: 116.397428,
+    lat: 39.90923,
+    option: {
+      content: "<div>北京</div>",
+      iconInfo: {
+        icon: "https://example.com/icon.png",
+        offsetX: 32,
+        offsetY: 32,
+      },
+      textInfo: {
+        text: "北京",
+        offsetX: 0,
+        offsetY: -30,
+      },
+    },
+  },
+]
+```
+
+Vue 3 调用示例：
+
+```vue
+<template>
+  <div>
+    <TiandiMap ref="mapRef" tk="your-tianditu-api-key" />
+    <button @click="addMarker">新增标注</button>
+  </div>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import TiandiMap from "tdt-map-vue";
+
+const mapRef = ref(null);
+
+const addMarker = () => {
+  mapRef.value?.addMarkers([
+    {
+      id: "marker-1",
+      lng: 116.397428,
+      lat: 39.90923,
+      option: {
+        content: "<div>北京</div>",
+      },
+    },
+  ]);
+};
+</script>
+```
+
+
+#### 2 设置中心点 `setCenterAndZoom(center, zoom)`
+
+- `center`：数组，格式为 `[lng, lat]`
+- `zoom`：缩放级别，类型为 `number`
+
+```vue
+<template>
+  <div>
+    <TiandiMap ref="mapRef" tk="your-tianditu-api-key" />
+    <button @click="goToCity">定位到城市</button>
+  </div>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import TiandiMap from "tdt-map-vue";
+
+const mapRef = ref(null);
+
+const goToCity = () => {
+  mapRef.value?.setCenterAndZoom([117.017362, 25.075884], 12);
+};
+</script>
+```
+
+#### 3 获取拾取坐标 `getMapLngLat()`
+
+`getMapLngLat()` 没有入参，返回值为当前拾取到的坐标对象，格式如下：
+
+```js
+{
+  lng: 117.017362,
+  lat: 25.075884
+}
+```
+
+```vue
+<template>
+  <div>
+    <TiandiMap ref="mapRef" tk="your-tianditu-api-key" />
+    <button @click="getPickedPoint">获取拾取坐标</button>
+  </div>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import TiandiMap from "tdt-map-vue";
+
+const mapRef = ref(null);
+
+const getPickedPoint = () => {
+  const point = mapRef.value?.getMapLngLat();
+  console.log("当前拾取坐标：", point);
+};
+</script>
+```
+
+#### 4 隐藏标注 `hideMarkers(markers)`
+
+`markers` 参数是一个数组，通常只需要传入要隐藏标注的 `id`。
+
+```js
+[
+  { id: "marker-1" },
+  { id: "marker-2" },
+]
+```
+
+```vue
+<template>
+  <div>
+    <TiandiMap ref="mapRef" tk="your-tianditu-api-key" />
+    <button @click="hideMarker">隐藏标注</button>
+  </div>
+</template>
+
+<script setup>
+import { ref } from "vue";
+import TiandiMap from "tdt-map-vue";
+
+const mapRef = ref(null);
+
+const hideMarker = () => {
+  mapRef.value?.hideMarkers([{ id: "marker-1" }]);
+};
+</script>
+```
+
 ### Vue 3 示例
 
 ```vue
@@ -211,39 +368,29 @@ export default {
 | `search-success` | `(location)`              | 地理编码搜索成功           |
 | `search-error`   | `(error)`                 | 地理编码搜索失败           |
 
-window.T.Map 地图对象
-window.T.Marker 标记对象
-window.T.InfoWindow 信息窗口对象
-window.T.LngLat 经纬度对象
-window.T.Point 点位/偏移对象
-map 天地图对象 可以拿来调用原生的api
+## 天地图原生对象说明
 
-## 标注数据格式
+在组件初始化完成后，你可以通过 `ready` 事件拿到地图实例 `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,
-      },
-    },
-  },
-];
-```
+- `window.T.Map`：地图对象
+- `window.T.Marker`：标记对象
+- `window.T.InfoWindow`：信息窗口对象
+- `window.T.LngLat`：经纬度对象
+- `window.T.Point`：点位 / 偏移对象
+
+`map` 是天地图的地图实例，可以直接拿来调用原生 API。
+
+
+## 使用建议
+
+- 地图容器必须有明确高度，否则地图不会显示
+- `tk` 必须替换成你自己的天地图 API Key
+- 如果需要在 Vue 2 项目中使用，请确保安装了 `vue-template-compiler` 且版本与 `vue` 保持一致
+- 如果你最近刚发布过新版本，但本地项目还是旧代码，请先删除缓存并重新安装依赖
+- 如果你要在父组件里拿到拾取坐标，可以通过 `ref` 调用 `getMapLngLat()`
+- 如果你想拿到天地图拾取回调中的原始坐标对象，可以结合 `ready` 事件和组件实例方法做二次封装
 
 ## 常见问题
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tdt-map-vue",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "基于 Vue 2/3 的天地图二次封装组件，提供地图初始化、标注管理、地理编码搜索和常用实例方法调用能力。",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",