Taro 位置相关 API 介绍

1. 位置相关

在移动应用开发中，位置服务是不可或缺的功能。Taro 框架提供了三个核心的位置 API，让开发者能够轻松实现地理位置获取、地图查看和位置选择等功能。本文将深入探讨这三个 API 的使用方法和最佳实践。

1.1 Taro.getLocation：获取地理位置

Taro.getLocation是获取用户当前地理位置信息的基础 API，它能够获取到用户的经纬度、速度、精度等详细数据。

基本用法

javascript 复制代码

import Taro from '@tarojs/taro';

// 基础获取位置
Taro.getLocation({
  type: 'wgs84',
  success: function (res) {
    const latitude = res.latitude;
    const longitude = res.longitude;
    const speed = res.speed;
    const accuracy = res.accuracy;

    console.log('当前位置：', {
      latitude,
      longitude,
      speed,
      accuracy,
    });
  },
  fail: function (error) {
    console.error('获取位置失败：', error);
  },
});

参数详解

参数名	类型	必填	说明
type	String	否	坐标系类型，默认为 wgs84 返回 gps 坐标，可选 gcj02 返回国测局坐标
altitude	Boolean	否	是否返回高度，默认 false
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数

返回参数说明

参数名	类型	说明
latitude	Number	纬度，浮点数，范围为-90~90，负数表示南纬
longitude	Number	经度，浮点数，范围为-180~180，负数表示西经
speed	Number	速度，浮点数，单位 m/s
accuracy	Number	位置的精确度
altitude	Number	高度，单位 m
verticalAccuracy	Number	垂直精度，单位 m（Android 无法获取，返回 0）
horizontalAccuracy	Number	水平精度，单位 m

实际应用示例

javascript 复制代码

// 获取位置并计算距离
async function getCurrentLocation() {
  try {
    const location = await Taro.getLocation({
      type: 'gcj02',
      altitude: true,
    });

    // 保存位置信息到全局状态
    const locationData = {
      latitude: location.latitude,
      longitude: location.longitude,
      timestamp: Date.now(),
      accuracy: location.accuracy,
    };

    // 可以结合逆地址解析获取详细地址
    const address = await reverseGeocoding(location.latitude, location.longitude);

    return {
      ...locationData,
      address,
    };
  } catch (error) {
    // 处理权限拒绝等错误
    if (error.errMsg.includes('auth deny')) {
      Taro.showModal({
        title: '提示',
        content: '需要获取您的地理位置才能使用此功能',
        showCancel: false,
      });
    }
    throw error;
  }
}

// 逆地址解析（需要结合地图服务）
async function reverseGeocoding(latitude, longitude) {
  // 这里以腾讯地图为例
  const result = await Taro.request({
    url: 'https://apis.map.qq.com/ws/geocoder/v1/',
    data: {
      location: `${latitude},${longitude}`,
      key: 'YOUR_TENCENT_MAP_KEY',
      get_poi: 1,
    },
  });

  return result.data.result;
}

1.2 Taro.openLocation：使用地图查看位置

Taro.openLocation用于在系统内置地图中查看指定位置，支持导航、缩放等交互功能。

基本用法

javascript 复制代码

import Taro from '@tarojs/taro';

Taro.openLocation({
  latitude: 23.10229,
  longitude: 113.334521,
  name: '腾讯大厦',
  address: '广东省深圳市南山区深南大道10000号',
  scale: 18,
});

参数详解

参数名	类型	必填	说明
latitude	Number	是	纬度，范围为-90~90，负数表示南纬
longitude	Number	是	经度，范围为-180~180，负数表示西经
scale	Number	否	缩放比例，范围 5~18，默认为 18
name	String	否	位置名
address	String	否	地址的详细说明

实际应用场景

javascript 复制代码

// 在商品详情页展示门店位置
function showStoreLocation(storeInfo) {
  Taro.openLocation({
    latitude: storeInfo.latitude,
    longitude: storeInfo.longitude,
    name: storeInfo.name,
    address: storeInfo.address,
    scale: 16,
  });
}

// 结合获取当前位置后导航
async function navigateToStore(storeLocation) {
  try {
    // 先获取当前位置
    const currentLocation = await Taro.getLocation({
      type: 'gcj02',
    });

    // 打开目标位置
    Taro.openLocation({
      latitude: storeLocation.latitude,
      longitude: storeLocation.longitude,
      name: storeLocation.name,
      address: storeLocation.address,
      scale: 16,
    });

    // 可以记录用户行为
    trackUserAction('open_location', {
      from: currentLocation,
      to: storeLocation,
    });
  } catch (error) {
    Taro.showToast({
      title: '获取位置失败',
      icon: 'none',
    });
  }
}

1.3 Taro.chooseLocation：选择位置

Taro.chooseLocation打开地图选择位置，用户可以在地图上选择或搜索一个位置，适用于地址选择、收货地址设置等场景。

基本用法

javascript 复制代码

import Taro from '@tarojs/taro';

Taro.chooseLocation({
  success: function (res) {
    console.log('选择的位置信息：', res);
    // res包含name、address、latitude、longitude
  },
  fail: function (error) {
    console.error('选择位置失败：', error);
  },
});

返回参数说明

参数名	类型	说明
name	String	位置名称
address	String	详细地址
latitude	Number	纬度，浮点数，范围为-90~90
longitude	Number	经度，浮点数，范围为-180~180

实际应用示例

javascript 复制代码

// 收货地址选择
function selectDeliveryAddress() {
  return new Promise((resolve, reject) => {
    Taro.chooseLocation({
      success: (res) => {
        const addressInfo = {
          name: res.name,
          address: res.address,
          latitude: res.latitude,
          longitude: res.longitude,
        };

        // 可以进一步解析地址
        parseAddressDetail(addressInfo).then(resolve);
      },
      fail: (error) => {
        if (error.errMsg !== 'chooseLocation:fail cancel') {
          Taro.showToast({
            title: '选择位置失败',
            icon: 'none',
          });
        }
        reject(error);
      },
    });
  });
}

// 地址解析和格式化
async function parseAddressDetail(location) {
  // 调用地图API获取更详细的地址信息
  const detail = await getAddressDetail(location.latitude, location.longitude);

  return {
    ...location,
    province: detail.province,
    city: detail.city,
    district: detail.district,
    street: detail.street,
    streetNumber: detail.streetNumber,
  };
}

// 在表单中使用
function AddressSelector({ onAddressChange }) {
  const handleSelectAddress = async () => {
    try {
      const address = await selectDeliveryAddress();
      onAddressChange(address);
    } catch (error) {
      console.error('地址选择失败', error);
    }
  };

  return (
    <View className='address-selector' onClick={handleSelectAddress}>
      <Text>选择收货地址</Text>
    </View>
  );
}

最佳实践和注意事项

1. 权限处理

在使用位置相关 API 前，需要确保用户已授权位置权限：

javascript 复制代码

// 检查并请求位置权限
async function checkLocationAuth() {
  const setting = await Taro.getSetting();
  const locationAuth = setting.authSetting['scope.userLocation'];

  if (locationAuth === false) {
    // 用户之前拒绝过，需要引导用户开启
    const modalRes = await Taro.showModal({
      title: '提示',
      content: '需要获取您的地理位置才能使用此功能，是否前往设置？',
      confirmText: '去设置',
      cancelText: '取消',
    });

    if (modalRes.confirm) {
      await Taro.openSetting();
    }
    return false;
  } else if (locationAuth === undefined) {
    // 首次请求权限
    try {
      await Taro.authorize({
        scope: 'scope.userLocation',
      });
      return true;
    } catch (error) {
      return false;
    }
  }

  return true;
}

2. 错误处理策略

javascript 复制代码

// 统一的错误处理
function handleLocationError(error) {
  const errorMap = {
    'getLocation:fail auth deny': '用户拒绝授权获取地理位置',
    'getLocation:fail system deny': '系统拒绝获取地理位置',
    'getLocation:fail': '获取位置失败，请检查网络或GPS',
    'chooseLocation:fail cancel': '用户取消了位置选择',
    'openLocation:fail': '打开地图失败',
  };

  const message = errorMap[error.errMsg] || '位置服务异常';

  Taro.showToast({
    title: message,
    icon: 'none',
    duration: 2000,
  });
}

3. 性能优化

javascript 复制代码

// 位置缓存机制
class LocationCache {
  constructor() {
    this.cache = null;
    this.lastUpdate = 0;
    this.cacheTime = 5 * 60 * 1000; // 5分钟缓存
  }

  async getLocation() {
    const now = Date.now();

    if (this.cache && now - this.lastUpdate < this.cacheTime) {
      return this.cache;
    }

    try {
      const location = await Taro.getLocation({
        type: 'gcj02',
        altitude: false,
      });

      this.cache = location;
      this.lastUpdate = now;

      return location;
    } catch (error) {
      throw error;
    }
  }

  clear() {
    this.cache = null;
    this.lastUpdate = 0;
  }
}

// 使用示例
const locationCache = new LocationCache();

// 在需要位置的地方
async function getCachedLocation() {
  try {
    return await locationCache.getLocation();
  } catch (error) {
    handleLocationError(error);
    throw error;
  }
}

总结

Taro 提供的这三个位置相关 API 构成了完整的地理位置解决方案：

getLocation：获取当前位置，适合需要实时位置的场景
openLocation：查看指定位置，适合展示和导航场景
chooseLocation：选择位置，适合地址录入和选择场景

在实际开发中，需要注意权限处理、错误处理和性能优化，确保用户体验的流畅性。通过合理的封装和缓存机制，可以大大提升应用的响应速度和用户体验。