af-mobile-client-vue3 1.1.3 → 1.1.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "af-mobile-client-vue3",
   "type": "module",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Vue + Vite component lib",
   "license": "MIT",
   "engines": {

package/src/components/data/XOlMap/README.md

@@ -1,220 +1,229 @@
-# XOlMap 地图组件使用说明
-
-## 组件简介
-
-XOlMap 是一个基于 OpenLayers 的地图组件，支持多种底图切换、WMS 图层加载、点位渲染等功能。组件使用 Vue 3 + TypeScript 开发，采用 Composition API 和 `<script setup>` 语法。
-
-## 功能特性
-
-- 支持多种底图切换（高德地图、高德卫星图、天地图、天地图卫星图）
-- 支持 WMS 图层加载和控制
-- 支持点位渲染（普通点位、分类点位、海量点）
-- 支持地图基本操作（缩放、平移、中心点设置等）
-- 支持移动端适配
-
-## 安装依赖
+# OpenLayers 地图组件 (XOlMap)
+
+基于 OpenLayers 封装的 Vue 3 地图组件，支持多种底图切换、图层管理、点位标注等功能。
+
+## 特性
+
+- 支持多种底图切换
+  - 高德地图（矢量）
+  - 高德卫星图
+  - 天地图（矢量）
+  - 天地图卫星图
+- 图层管理
+  - WMS 图层支持
+  - 矢量点位图层
+  - 图层显示/隐藏控制
+- 点位标注
+  - 支持自定义图标
+  - 支持点位标题显示
+  - 支持点击回调
+- 定位功能
+  - 支持手机 GPS 定位
+  - 支持地址解析
+- 交互控制
+  - 缩放控制
+  - 比例尺显示
+  - 地图拖动
+
+## 安装
 
 ```bash
+# 项目依赖
 npm install ol vant
 ```
 
-## 基本用法
+## 使用示例
 
 ```vue
 <template>
-  <XOlMap ref="mapRef" />
+  <XOlMap ref="mapRef" @centerChange="handleCenterChange" />
 </template>
 
 <script setup lang="ts">
-import { onMounted, ref } from 'vue'
-import XOlMap from './index.vue'
+import { ref } from 'vue'
+import type { InitParams } from './types'
+import XOlMap from '@/components/data/XOlMap/index.vue'
 
 const mapRef = ref()
 
-onMounted(() => {
-  // 初始化地图
-  mapRef.value.init({
-    center: [116.404, 39.915], // 北京坐标
-    zoom: 12,
-    maxZoom: 18,
-    minZoom: 4,
-    tianDiTuKey: 'your-tianditu-key', // 天地图密钥
+// 初始化参数
+const initParams: InitParams = {
+  center: [116.404, 39.915],  // 初始中心点
+  zoom: 12,                   // 初始缩放级别
+  maxZoom: 18,               // 最大缩放级别
+  minZoom: 4,                // 最小缩放级别
+  tianDiTuKey: 'your_key',   // 天地图密钥
+  amapKey: 'your_key',       // 高德地图密钥
+}
+
+// 中心点变化回调
+const handleCenterChange = (center: [number, number]) => {
+  console.log('地图中心点变化:', center)
+}
+
+// 添加点位示例
+const addPoints = () => {
+  mapRef.value?.addVectorPoints({
+    id: 1,
+    value: '测试点位',
+    show: true,
+    icon: 'path/to/icon.png',
+    data: [{
+      longitude: 116.404,
+      latitude: 39.915,
+      title: '测试点位1'
+    }],
+    onClick: (point) => {
+      console.log('点击了点位:', point)
+    }
   })
-})
+}
 </script>
 ```
 
-## 组件属性
+## API
 
-### 初始化参数 (InitParams)
+### Props
 
-| 参数名 | 类型 | 默认值 | 说明 |
-|--------|------|--------|------|
-| center | [number, number] | [116.404, 39.915] | 地图中心点坐标 [经度, 纬度] |
-| zoom | number | 10 | 地图缩放级别 |
-| maxZoom | number | 18 | 最大缩放级别 |
-| minZoom | number | 4 | 最小缩放级别 |
-| tianDiTuKey | string | '' | 天地图密钥 |
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| initParams | 初始化参数 | InitParams | - |
 
-## 组件方法
+### InitParams 类型定义
 
-### 地图控制
+```typescript
+interface InitParams {
+  center?: [number, number]     // 地图中心点坐标 [经度, 纬度]
+  zoom?: number                 // 地图缩放级别
+  maxZoom?: number             // 最大缩放级别
+  minZoom?: number             // 最小缩放级别
+  tianDiTuKey?: string         // 天地图密钥
+  amapKey?: string             // 高德地图 API key
+}
+```
 
-| 方法名 | 参数 | 返回值 | 说明 |
-|--------|------|--------|------|
-| init | InitParams | void | 初始化地图 |
-| getMap | - | Map \| null | 获取地图实例 |
-| setCenter | center: [number, number], animate?: boolean | void | 设置地图中心点 |
-| setZoom | zoom: number, animate?: boolean | void | 设置地图缩放级别 |
-| getZoom | - | number | 获取当前缩放级别 |
-| setCenterAndZoom | center: [number, number], zoom: number, animate?: boolean | void | 设置地图中心点和缩放级别 |
+### 事件
 
-### 图层控制
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| centerChange | 地图中心点变化时触发 | (center: [number, number]) |
 
-| 方法名 | 参数 | 返回值 | 说明 |
-|--------|------|--------|------|
-| addWMSLayers | options: WMSOptions | void | 添加 WMS 图层 |
-| setWMSLayerVisible | layerName: string, visible: boolean | void | 控制 WMS 图层显示/隐藏 |
-| handleToggleWMSLayer | layer: WMSLayerConfig | void | 切换 WMS 图层显示状态 |
-| addPointLayer | config: PointLayerConfig, points: PointData[] | number | 添加点位图层 |
-| setPointLayerVisible | layerId: number, visible: boolean | void | 控制点位图层显示/隐藏 |
+### 方法
 
-### 点位渲染
+| 方法名 | 说明 | 参数 | 返回值 |
+| --- | --- | --- | --- |
+| init | 初始化地图 | (params: InitParams) | void |
+| setCenter | 设置地图中心点 | (center: [number, number], animate?: boolean) | void |
+| setZoom | 设置缩放级别 | (zoom: number, animate?: boolean) | void |
+| getZoom | 获取当前缩放级别 | - | number |
+| setCenterAndZoom | 同时设置中心点和缩放级别 | (center: [number, number], zoom: number, animate?: boolean) | void |
+| addVectorPoints | 添加矢量点位 | (config: PointLayerConfig) | VectorLayer |
+| addWMSLayers | 添加 WMS 图层 | (options: WMSOptions) | void |
+| handleLocation | 触发定位功能 | - | Promise<void> |
 
-| 方法名 | 参数 | 返回值 | 说明 |
-|--------|------|--------|------|
-| addVectorPoints | config: PointLayerConfig | VectorLayer<VectorSource> \| null | 渲染普通点位 |
-| addWebGLPoints | options: WebGLPointOptions | void | 渲染海量点 |
+## 注意事项
 
-## 类型定义
+1. 使用天地图和高德地图需要配置对应的密钥
+2. 组件默认高度为 100%，需要在父容器中设置具体高度
+3. 手机定位功能需要设备支持并授予定位权限
+4. WMS 图层需要配置正确的服务地址和图层参数
 
-### PointData 点位数据
+# 地址选择器 (XLocationPicker)
 
-```typescript
-interface PointData {
-  longitude: number    // 经度
-  latitude: number     // 纬度
-  title?: string       // 点标题
-  extData?: Record<string, any> // 自定义数据
-}
-```
+基于 XOlMap 封装的地址选择器组件，支持地图选点和地址解析功能。
 
-### PointLayerConfig 点位图层配置
+### 使用示例
 
-```typescript
-interface PointLayerConfig {
-  id: number          // 图层ID
-  value: string       // 图层名称
-  show: boolean       // 是否显示
-  icon: string        // 图标URL
-  iconAnchor?: [number, number] // 图标锚点
-  onClick?: (point: PointData, event: any) => void // 点击回调函数
-  data?: PointData[]  // 点位数据
+```vue
+<template>
+  <XLocationPicker
+    v-model:visible="showPicker"
+    :init-location="initLocation"
+    @confirm="handleConfirm"
+    @cancel="handleCancel"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import type { LocationResult } from './types'
+import { XLocationPicker } from '@/components/data/XOlMap'
+
+// 控制选择器显示
+const showPicker = ref(false)
+
+// 初始位置
+const initLocation = {
+  longitude: 116.404,
+  latitude: 39.915,
+  address: '北京市天安门'
 }
-```
 
-### WebGLPointOptions WebGL渲染配置
+// 确认选择回调
+const handleConfirm = (location: LocationResult) => {
+  console.log('选择的位置:', location)
+  // location 包含:
+  // - longitude: 经度
+  // - latitude: 纬度
+  // - address: 地址描述
+  showPicker.value = false
+}
 
-```typescript
-interface WebGLPointOptions extends PointLayerConfig {
-  iconSize?: [number, number]  // 图标大小
-  enableCluster?: boolean      // 是否开启聚合
-  clusterDistance?: number     // 聚合距离
-  performance?: {              // 性能配置
-    enableChunk?: boolean      // 是否开启分块加载
-    chunkSize?: number         // 每块数据量
-    enableThrottle?: boolean   // 是否开启节流
-    throttleWait?: number      // 节流时间间隔
-  }
+// 取消选择回调
+const handleCancel = () => {
+  showPicker.value = false
+}
+
+// 打开选择器
+const openPicker = () => {
+  showPicker.value = true
 }
+</script>
 ```
 
-## 示例代码
+### Props
 
-### 添加普通点位
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| visible | 是否显示选择器 | boolean | false |
+| initLocation | 初始位置 | LocationResult | - |
+| title | 选择器标题 | string | '选择位置' |
+| confirmText | 确认按钮文字 | string | '确定' |
+| cancelText | 取消按钮文字 | string | '取消' |
 
-```typescript
-mapRef.value.addVectorPoints({
-  icon: 'path/to/icon.png',
-  iconAnchor: [0.5, 1],
-  data: [
-    {
-      longitude: 116.404,
-      latitude: 39.915,
-      title: '测试点位',
-      extData: { type: 'test' }
-    }
-  ],
-  onClick: (point) => {
-    console.log('点击了点位:', point)
-  }
-})
-```
+### 事件
 
-### 添加分类点位
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| confirm | 点击确认按钮时触发 | (location: LocationResult) |
+| cancel | 点击取消按钮时触发 | - |
+| update:visible | 更新 visible 值 | (visible: boolean) |
 
-```typescript
-mapRef.value.addPointLayer(
-  {
-    id: 1,
-    value: '学校',
-    show: true,
-    icon: 'path/to/icon.png',
-    iconAnchor: [0.5, 1],
-    onClick: (point) => {
-      console.log('点击了学校:', point)
-    }
-  },
-  [
-    {
-      longitude: 116.404,
-      latitude: 39.915,
-      title: '北京大学',
-      extData: { type: 'school' }
-    }
-  ]
-)
-```
-
-### 添加海量点
+### LocationResult 类型定义
 
 ```typescript
-mapRef.value.addWebGLPoints({
-  icon: 'path/to/icon.png',
-  iconSize: [6, 6],
-  data: Array.from({ length: 10000 }, (_, i) => ({
-    longitude: 116.404 + Math.random() * 0.1,
-    latitude: 39.915 + Math.random() * 0.1,
-    title: `点位${i + 1}`,
-    extData: { type: 'mass' }
-  })),
-  performance: {
-    enableChunk: true,
-    chunkSize: 1000
-  }
-})
+interface LocationResult {
+  longitude: number    // 经度
+  latitude: number     // 纬度
+  address: string      // 地址描述
+}
 ```
 
-## 注意事项
+### 特性
 
-1. 使用天地图时需要提供有效的天地图密钥
-2. 海量点渲染建议使用 WebGL 方式，性能更好
-3. 点位图层的 zIndex 会根据是否有 ID 自动设置
-4. 移动端适配已内置，无需额外配置
+- 支持地图拖动选点
+- 实时解析地址信息
+- 支持初始位置设置
+- 支持自定义标题和按钮文字
+- 移动端友好的交互体验
 
-## 常见问题
+### 注意事项
 
-1. 地图不显示
-   - 检查容器高度是否设置
-   - 检查网络连接是否正常
-   - 检查天地图密钥是否有效
+1. 需要配置高德地图 API Key 用于地址解析
+2. 建议在移动端使用时增加必要的权限检查
+3. 可以通过 CSS 变量自定义样式
+4. 选择器会自动适配屏幕高度
 
-2. 点位不显示
-   - 检查点位数据格式是否正确
-   - 检查图标 URL 是否可访问
-   - 检查图层是否设置为显示状态
+## 贡献
 
-3. 性能问题
-   - 大量点位建议使用 WebGL 渲染
-   - 开启分块加载和节流功能
-   - 合理设置聚合参数 
+如果你有任何问题或建议，欢迎提出 Issue 或 Pull Request。 

package/src/components/data/XOlMap/XLocationPicker/index.vue

@@ -0,0 +1,191 @@
+<script setup lang="ts">
+import type { LocationResult } from '../types'
+import { Button } from 'vant'
+import { nextTick, onMounted, ref, watch } from 'vue'
+import XOlMap from '../index.vue'
+
+interface Props {
+  modelValue?: LocationResult
+  tianDiTuKey: string
+  amapKey: string
+  defaultCenter?: [number, number]
+  defaultZoom?: number
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  defaultCenter: () => [116.404, 39.915],
+  defaultZoom: 10,
+  tianDiTuKey: '',
+  amapKey: '',
+})
+
+const emit = defineEmits<{
+  (e: 'update:modelValue', value: LocationResult): void
+  (e: 'confirm', value: LocationResult): void
+}>()
+
+const mapRef = ref<InstanceType<typeof XOlMap>>()
+const currentAddress = ref('')
+const currentLocation = ref<[number, number]>(props.defaultCenter)
+
+// 处理地图中心点变化
+async function handleCenterChange(center: [number, number]) {
+  currentLocation.value = center
+  // 获取地址信息
+  if (mapRef.value) {
+    currentAddress.value = await mapRef.value.getAddressInfo(center)
+  }
+}
+
+// 处理确定按钮点击
+function handleConfirm() {
+  const result: LocationResult = {
+    longitude: currentLocation.value[0],
+    latitude: currentLocation.value[1],
+    address: currentAddress.value,
+  }
+  emit('update:modelValue', result)
+  emit('confirm', result)
+}
+
+// 组件挂载时初始化地图
+onMounted(() => {
+  // 使用 nextTick 确保 DOM 已更新
+  nextTick(() => {
+    mapRef.value.init({
+      center: props.defaultCenter,
+      zoom: props.defaultZoom,
+      tianDiTuKey: props.tianDiTuKey,
+      amapKey: props.amapKey,
+    })
+
+    // 初始化后尝试获取地址信息
+    handleCenterChange(props.defaultCenter)
+  })
+})
+
+// 监听弹窗状态变化
+watch(() => props.modelValue, (newVal) => {
+  // 当绑定值变化时，可能需要重新调整地图
+  nextTick(() => {
+    if (mapRef.value && mapRef.value.getMap()) {
+      mapRef.value.getMap().updateSize()
+    }
+  })
+}, { immediate: true })
+</script>
+
+<template>
+  <div class="location-picker">
+    <div class="map-container">
+      <XOlMap
+        ref="mapRef"
+        class="map"
+        @center-change="handleCenterChange"
+      />
+      <!-- 中心点标记 -->
+      <div class="location-picker-marker">
+        <div class="marker-icon" />
+      </div>
+    </div>
+
+    <!-- 底部地址信息面板 -->
+    <div class="location-picker-panel">
+      <div class="address-info">
+        <div class="address-label">
+          位置信息
+        </div>
+        <div class="address-text">
+          {{ currentAddress }}
+        </div>
+        <div class="coordinates-text">
+          经度: {{ currentLocation[0] }}, 纬度: {{ currentLocation[1] }}
+        </div>
+      </div>
+      <Button type="primary" block @click="handleConfirm">
+        确定
+      </Button>
+    </div>
+  </div>
+</template>
+
+<style scoped lang="less">
+.location-picker {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  border-radius: 8px;
+  overflow: hidden;
+}
+
+.map-container {
+  position: relative;
+  flex: 1;
+  min-height: 0;
+}
+
+.map {
+  width: 100%;
+  height: 100%;
+  min-height: 300px;
+}
+
+.location-picker-marker {
+  position: absolute;
+  left: 50%;
+  top: 50%;
+  transform: translate(-50%, -50%);
+  z-index: 1000;
+  pointer-events: none;
+
+  .marker-icon {
+    width: 24px;
+    height: 24px;
+    background: url('data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iIzE5ODlmYSIgZD0iTTEyIDJDOC4xMyAyIDUgNS4xMyA1IDljMCA1LjI1IDcgMTMgNyAxM3M3LTcuNzUgNy0xM2MwLTMuODctMy4xMy03LTctN3ptMCA5LjVjLTEuMzggMC0yLjUtMS4xMi0yLjUtMi41czEuMTItMi41IDIuNS0yLjUgMi41IDEuMTIgMi41IDIuNS0xLjEyIDIuNS0yLjUgMi41eiIvPjwvc3ZnPg==') no-repeat center;
+    background-size: contain;
+  }
+}
+
+.location-picker-panel {
+  background: white;
+  padding: 12px 16px;
+  box-shadow: 0 -1px 4px rgba(0, 0, 0, 0.1);
+  border-radius: 8px 8px 0 0;
+  z-index: 1000;
+
+  .address-info {
+    margin-bottom: 12px;
+
+    .address-label {
+      font-size: 14px;
+      color: #666;
+      margin-bottom: 4px;
+    }
+
+    .address-text {
+      font-size: 15px;
+      color: #333;
+      margin-bottom: 4px;
+      word-break: break-all;
+    }
+
+    .coordinates-text {
+      font-size: 12px;
+      color: #999;
+    }
+  }
+}
+
+// 移动端适配
+@media screen and (max-width: 768px) {
+  .location-picker-panel {
+    padding: 10px 12px;
+
+    .address-info {
+      margin-bottom: 10px;
+    }
+  }
+}
+</style>