HomeLease/components/map-location/README.md

# MapLocation 地图定位组件

一个可复用的地图定位组件，集成了地址输入、位置获取、地图打开等功能。

## 功能特性

- 📍 自动获取当前位置
- 🗺️ 一键打开系统地图
- 📝 支持手动输入地址
- 📱 跨平台支持（APP、微信小程序、H5）
- 🎨 美观的UI设计
- 🔧 高度可配置

## 使用方法

### 基础用法

```vue
<template>
  <map-location
    v-model="address"
    label="地址"
    placeholder="请输入或选择收货地址"
  />
</template>

<script>
import MapLocation from '@/components/map-location/map-location.vue'

export default {
  components: {
    MapLocation
  },
  data() {
    return {
      address: ''
    }
  }
}
</script>
```

### 完整用法

```vue
<template>
  <map-location
    v-model="formData.address"
    label="收货地址"
    placeholder="请输入或选择收货地址"
    @location-success="onLocationSuccess"
    @location-error="onLocationError"
    @use-location="onUseLocation"
    @map-opened="onMapOpened"
    @address-focus="onAddressFocus"
    @address-input="onAddressInput"
  />
</template>

<script>
import MapLocation from '@/components/map-location/map-location.vue'

export default {
  components: {
    MapLocation
  },
  data() {
    return {
      formData: {
        address: ''
      }
    }
  },
  methods: {
    // 位置获取成功
    onLocationSuccess(location) {
      console.log('位置获取成功:', location)
      // location 包含: { address, latitude, longitude }
    },

    // 位置获取失败
    onLocationError(error) {
      console.error('位置获取失败:', error)
    },

    // 使用位置
    onUseLocation(location) {
      console.log('使用位置:', location)
    },

    // 地图打开成功
    onMapOpened() {
      console.log('地图已打开')
    },

    // 地址输入框获得焦点
    onAddressFocus() {
      console.log('地址输入框获得焦点')
    },

    // 地址输入
    onAddressInput(value) {
      console.log('地址输入:', value)
    }
  }
}
</script>
```

## Props 属性

| 属性名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| label | String | '地址' | 表单标签 |
| placeholder | String | '请输入或选择收货地址' | 输入框占位符 |
| value | String | '' | 地址值（支持v-model） |
| showLocationCard | Boolean | true | 是否显示位置建议卡片 |

## Events 事件

| 事件名 | 参数 | 说明 |
|--------|------|------|
| input | String | 地址值变化时触发 |
| location-success | Object | 位置获取成功时触发 |
| location-error | Error | 位置获取失败时触发 |
| use-location | Object | 点击使用位置时触发 |
| map-opened | - | 地图打开成功时触发 |
| address-focus | - | 地址输入框获得焦点时触发 |
| address-input | String | 地址输入时触发 |

## 位置对象结构

```javascript
{
  address: "纬度: 39.123456, 经度: 116.123456",
  latitude: 39.123456,
  longitude: 116.123456
}
```

## 方法

组件提供了以下方法供外部调用：

### setLocation(location)
手动设置位置信息

```javascript
// 在父组件中调用
this.$refs.mapLocation.setLocation({
  address: '北京市朝阳区',
  latitude: 39.123456,
  longitude: 116.123456
})
```

### clearLocation()
清空位置信息

```javascript
// 在父组件中调用
this.$refs.mapLocation.clearLocation()
```

## 平台支持

- ✅ APP-PLUS：使用系统地图应用
- ✅ MP-WEIXIN：使用微信小程序地图
- ✅ H5：使用高德地图在线版

## 依赖

- `@/utils/permission.js`：权限处理工具
- uni-app 定位API
- uni-app 地图API

## 注意事项

1. 首次使用需要用户授权定位权限
2. 不同平台的权限处理可能略有差异
3. H5环境下需要网络连接才能使用地图功能
4. 建议在真机上测试定位功能