af-mobile-client-vue3 1.3.12 → 1.3.14

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

@@ -1,227 +1,227 @@
-# OpenLayers 地图组件 (XOlMap)
-
-基于 OpenLayers 封装的 Vue 3 地图组件，支持多种底图切换、图层管理、点位标注等功能。
-
-## 特性
-
-- 支持多种底图切换
-  - 高德地图（矢量）
-  - 高德卫星图
-  - 天地图（矢量）
-  - 天地图卫星图
-- 图层管理
-  - WMS 图层支持
-  - 矢量点位图层
-  - 图层显示/隐藏控制
-- 点位标注
-  - 支持自定义图标
-  - 支持点位标题显示
-  - 支持点击回调
-- 定位功能
-  - 支持手机 GPS 定位
-  - 支持地址解析
-- 交互控制
-  - 缩放控制
-  - 比例尺显示
-  - 地图拖动
-
-## 安装
-
-```bash
-# 项目依赖
-npm install ol vant
-```
-
-## 使用示例
-
-```vue
-<template>
-  <XOlMap ref="mapRef" @centerChange="handleCenterChange" />
-</template>
-
-<script setup lang="ts">
-import { ref } from 'vue'
-import type { InitParams } from './types'
-import XOlMap from '@/components/data/XOlMap/index.vue'
-
-const mapRef = ref()
-
-// 初始化参数
-const initParams: InitParams = {
-  center: [116.404, 39.915],  // 初始中心点
-  zoom: 12,                   // 初始缩放级别
-  maxZoom: 18,               // 最大缩放级别
-  minZoom: 4,                // 最小缩放级别
-}
-
-// 中心点变化回调
-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
-
-### Props
-
-| 参数 | 说明 | 类型 | 默认值 |
-| --- | --- | --- | --- |
-| initParams | 初始化参数 | InitParams | - |
-
-### InitParams 类型定义
-
-```typescript
-interface InitParams {
-  center?: [number, number]     // 地图中心点坐标 [经度, 纬度]
-  zoom?: number                 // 地图缩放级别
-  maxZoom?: number             // 最大缩放级别
-  minZoom?: number             // 最小缩放级别
-  tianDiTuKey?: string         // 天地图密钥
-  amapKey?: string             // 高德地图 API key
-}
-```
-
-### 事件
-
-| 事件名 | 说明 | 回调参数 |
-| --- | --- | --- |
-| centerChange | 地图中心点变化时触发 | (center: [number, number]) |
-
-### 方法
-
-| 方法名 | 说明 | 参数 | 返回值 |
-| --- | --- | --- | --- |
-| 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> |
-
-## 注意事项
-
-1. 使用天地图和高德地图需要配置对应的密钥
-2. 组件默认高度为 100%，需要在父容器中设置具体高度
-3. 手机定位功能需要设备支持并授予定位权限
-4. WMS 图层需要配置正确的服务地址和图层参数
-
-# 地址选择器 (XLocationPicker)
-
-基于 XOlMap 封装的地址选择器组件，支持地图选点和地址解析功能。
-
-### 使用示例
-
-```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: '北京市天安门'
-}
-
-// 确认选择回调
-const handleConfirm = (location: LocationResult) => {
-  console.log('选择的位置:', location)
-  // location 包含:
-  // - longitude: 经度
-  // - latitude: 纬度
-  // - address: 地址描述
-  showPicker.value = false
-}
-
-// 取消选择回调
-const handleCancel = () => {
-  showPicker.value = false
-}
-
-// 打开选择器
-const openPicker = () => {
-  showPicker.value = true
-}
-</script>
-```
-
-### Props
-
-| 参数 | 说明 | 类型 | 默认值 |
-| --- | --- | --- | --- |
-| visible | 是否显示选择器 | boolean | false |
-| initLocation | 初始位置 | LocationResult | - |
-| title | 选择器标题 | string | '选择位置' |
-| confirmText | 确认按钮文字 | string | '确定' |
-| cancelText | 取消按钮文字 | string | '取消' |
-
-### 事件
-
-| 事件名 | 说明 | 回调参数 |
-| --- | --- | --- |
-| confirm | 点击确认按钮时触发 | (location: LocationResult) |
-| cancel | 点击取消按钮时触发 | - |
-| update:visible | 更新 visible 值 | (visible: boolean) |
-
-### LocationResult 类型定义
-
-```typescript
-interface LocationResult {
-  longitude: number    // 经度
-  latitude: number     // 纬度
-  address: string      // 地址描述
-}
-```
-
-### 特性
-
-- 支持地图拖动选点
-- 实时解析地址信息
-- 支持初始位置设置
-- 支持自定义标题和按钮文字
-- 移动端友好的交互体验
-
-### 注意事项
-
-1. 需要配置高德地图 API Key 用于地址解析
-2. 建议在移动端使用时增加必要的权限检查
-3. 可以通过 CSS 变量自定义样式
-4. 选择器会自动适配屏幕高度
-
-## 贡献
-
-如果你有任何问题或建议，欢迎提出 Issue 或 Pull Request。 
+# OpenLayers 地图组件 (XOlMap)
+
+基于 OpenLayers 封装的 Vue 3 地图组件，支持多种底图切换、图层管理、点位标注等功能。
+
+## 特性
+
+- 支持多种底图切换
+  - 高德地图（矢量）
+  - 高德卫星图
+  - 天地图（矢量）
+  - 天地图卫星图
+- 图层管理
+  - WMS 图层支持
+  - 矢量点位图层
+  - 图层显示/隐藏控制
+- 点位标注
+  - 支持自定义图标
+  - 支持点位标题显示
+  - 支持点击回调
+- 定位功能
+  - 支持手机 GPS 定位
+  - 支持地址解析
+- 交互控制
+  - 缩放控制
+  - 比例尺显示
+  - 地图拖动
+
+## 安装
+
+```bash
+# 项目依赖
+npm install ol vant
+```
+
+## 使用示例
+
+```vue
+<script setup lang="ts">
+import type { InitParams } from './types'
+import { ref } from 'vue'
+import XOlMap from '@/components/data/XOlMap/index.vue'
+
+const mapRef = ref()
+
+// 初始化参数
+const initParams: InitParams = {
+  center: [116.404, 39.915], // 初始中心点
+  zoom: 12, // 初始缩放级别
+  maxZoom: 18, // 最大缩放级别
+  minZoom: 4, // 最小缩放级别
+}
+
+// 中心点变化回调
+function handleCenterChange(center: [number, number]) {
+  console.log('地图中心点变化:', center)
+}
+
+// 添加点位示例
+function 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>
+
+<template>
+  <XOlMap ref="mapRef" @center-change="handleCenterChange" />
+</template>
+```
+
+## API
+
+### Props
+
+| 参数       | 说明       | 类型       | 默认值 |
+| ---------- | ---------- | ---------- | ------ |
+| initParams | 初始化参数 | InitParams | -      |
+
+### InitParams 类型定义
+
+```typescript
+interface InitParams {
+  center?: [number, number] // 地图中心点坐标 [经度, 纬度]
+  zoom?: number // 地图缩放级别
+  maxZoom?: number // 最大缩放级别
+  minZoom?: number // 最小缩放级别
+  tianDiTuKey?: string // 天地图密钥
+  amapKey?: string // 高德地图 API key
+}
+```
+
+### 事件
+
+| 事件名       | 说明                 | 回调参数                   |
+| ------------ | -------------------- | -------------------------- |
+| centerChange | 地图中心点变化时触发 | (center: [number, number]) |
+
+### 方法
+
+| 方法名           | 说明                     | 参数                                                        | 返回值        |
+| ---------------- | ------------------------ | ----------------------------------------------------------- | ------------- |
+| 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> |
+
+## 注意事项
+
+1. 使用天地图和高德地图需要配置对应的密钥
+2. 组件默认高度为 100%，需要在父容器中设置具体高度
+3. 手机定位功能需要设备支持并授予定位权限
+4. WMS 图层需要配置正确的服务地址和图层参数
+
+# 地址选择器 (XLocationPicker)
+
+基于 XOlMap 封装的地址选择器组件，支持地图选点和地址解析功能。
+
+### 使用示例
+
+```vue
+<script setup lang="ts">
+import type { LocationResult } from './types'
+import { ref } from 'vue'
+import { XLocationPicker } from '@/components/data/XOlMap'
+
+// 控制选择器显示
+const showPicker = ref(false)
+
+// 初始位置
+const initLocation = {
+  longitude: 116.404,
+  latitude: 39.915,
+  address: '北京市天安门'
+}
+
+// 确认选择回调
+function handleConfirm(location: LocationResult) {
+  console.log('选择的位置:', location)
+  // location 包含:
+  // - longitude: 经度
+  // - latitude: 纬度
+  // - address: 地址描述
+  showPicker.value = false
+}
+
+// 取消选择回调
+function handleCancel() {
+  showPicker.value = false
+}
+
+// 打开选择器
+function openPicker() {
+  showPicker.value = true
+}
+</script>
+
+<template>
+  <XLocationPicker
+    v-model:visible="showPicker"
+    :init-location="initLocation"
+    @confirm="handleConfirm"
+    @cancel="handleCancel"
+  />
+</template>
+```
+
+### Props
+
+| 参数         | 说明           | 类型           | 默认值     |
+| ------------ | -------------- | -------------- | ---------- |
+| visible      | 是否显示选择器 | boolean        | false      |
+| initLocation | 初始位置       | LocationResult | -          |
+| title        | 选择器标题     | string         | '选择位置' |
+| confirmText  | 确认按钮文字   | string         | '确定'     |
+| cancelText   | 取消按钮文字   | string         | '取消'     |
+
+### 事件
+
+| 事件名         | 说明               | 回调参数                   |
+| -------------- | ------------------ | -------------------------- |
+| confirm        | 点击确认按钮时触发 | (location: LocationResult) |
+| cancel         | 点击取消按钮时触发 | -                          |
+| update:visible | 更新 visible 值    | (visible: boolean)         |
+
+### LocationResult 类型定义
+
+```typescript
+interface LocationResult {
+  longitude: number // 经度
+  latitude: number // 纬度
+  address: string // 地址描述
+}
+```
+
+### 特性
+
+- 支持地图拖动选点
+- 实时解析地址信息
+- 支持初始位置设置
+- 支持自定义标题和按钮文字
+- 移动端友好的交互体验
+
+### 注意事项
+
+1. 需要配置高德地图 API Key 用于地址解析
+2. 建议在移动端使用时增加必要的权限检查
+3. 可以通过 CSS 变量自定义样式
+4. 选择器会自动适配屏幕高度
+
+## 贡献
+
+如果你有任何问题或建议，欢迎提出 Issue 或 Pull Request。