位置

需要设置权限

getCurrentLocation在使用之前需要设置位置权限。请先查看权限设置指南。

---

1. 获取当前位置

SDK 函数： getCurrentLocation

这是一个只获取设备当前位置一次的函数。用于在地图上显示用户位置，或搜索附近门店时很有用。

签名

function getCurrentLocation(options: { accuracy: Accuracy }): Promise<Location>;

参数

• options · 必填 · object

  获取位置信息时使用的选项对象。

  • options.accuracy · 必填 · Accuracy

    这是位置信息精度级别。详细值请参考下面的 Accuracy 类型。

返回值

• Promise<Location>

  返回包含设备位置信息的对象。详细内容请参考下面的 Location 类型。

权限方法

• getCurrentLocation.getPermission

  返回位置权限的当前状态。 allowed · denied · notDetermined · osPermissionDenied 之一。
• getCurrentLocation.openPermissionDialog

  显示重新请求位置权限的对话框。允许时 allowed，拒绝时 denied则返回。

错误

当权限被拒绝时 GetCurrentLocationPermissionError会发生。

class GetCurrentLocationPermissionError extends PermissionError {
  constructor();
}

示例

Web（JS）

import { Accuracy, getCurrentLocation, GetCurrentLocationPermissionError } from '@apps-in-toss/web-framework';

async function handleGetCurrentLocation() {
  try {
    const response = await getCurrentLocation({ accuracy: Accuracy.Balanced });
    console.log(`位置: ${response.coords.latitude}, ${response.coords.longitude}`);
  } catch (error) {
    if (error instanceof GetCurrentLocationPermissionError) {
      console.log('没有位置权限');
    }
  }
}

Web（React）

import { Accuracy, getCurrentLocation, GetCurrentLocationPermissionError, Location } from '@apps-in-toss/web-framework';
import { useState } from 'react';

function CurrentPosition() {
  const [position, setPosition] = useState<Location | null>(null);

  const handlePress = async () => {
    try {
      const response = await getCurrentLocation({ accuracy: Accuracy.Balanced });
      setPosition(response);
    } catch (error) {
      if (error instanceof GetCurrentLocationPermissionError) {
        // 没有位置权限
      }
    }
  };

  return (
    <div>
      {position ? (
        <span>
          位置: {position.coords.latitude}, {position.coords.longitude}
        </span>
      ) : (
        <span>尚未获取位置信息</span>
      )}
      <input type="button" value="获取当前位置" onClick={handlePress} />
      <input
        type="button"
        value="检查权限"
        onClick={async () => alert(await getCurrentLocation.getPermission())}
      />
      <input
        type="button"
        value="请求权限"
        onClick={async () => alert(await getCurrentLocation.openPermissionDialog())}
      />

  );
}

React Native

import { Accuracy, getCurrentLocation, GetCurrentLocationPermissionError, Location } from '@apps-in-toss/framework';
import { useState } from 'react';
import { Alert, Button, Text, View } from 'react-native';

function CurrentPosition() {
  const [position, setPosition] = useState<Location | null>(null);

  const handlePress = async () => {
    try {
      const response = await getCurrentLocation({ accuracy: Accuracy.Balanced });
      setPosition(response);
    } catch (error) {
      if (error instanceof GetCurrentLocationPermissionError) {
        // 没有位置权限
      }
    }
  };

  return (
    <View>
      {position ? (
        <Text>
          位置: {position.coords.latitude}, {position.coords.longitude}
        </Text>
      ) : (
        <Text>尚未获取位置信息</Text>
      )}
      <Button title="获取当前位置" onPress={handlePress} />
      <Button title="检查权限" onPress={async () => Alert.alert(await getCurrentLocation.getPermission())} />
      <Button
        title="请求权限"
        onPress={async () => Alert.alert(await getCurrentLocation.openPermissionDialog())}
      />
    </View>
  );
}

---

2. 实时追踪位置

SDK 函数： startUpdateLocation

这是一个在位置变化时执行回调的函数。可用于运动应用记录移动距离，或在地图上实时更新位置。调用返回的 cleanup 函数后，追踪将停止。

签名

function startUpdateLocation(options: {
  onError: (error: unknown) => void;
  onEvent: (location: Location) => void;
  options: StartUpdateLocationOptions;
}): () => void;

参数

• onEvent · 必填 · (location: Location) => void

  这是在位置信息变化时调用的回调函数。
• onError · 必填 · (error: unknown) => void

  这是在位置信息检测失败时调用的回调函数。
• options · 必填 · StartUpdateLocationOptions

  这是位置信息检测所需的设置对象。

  • options.accuracy · Accuracy

    设置位置精度。
  • options.timeInterval · number

    这是更新位置信息的最小周期。单位为毫秒(ms)。
  • options.distanceInterval · number

    将位置变化距离设置为米(m)单位。

返回值

• () => void

  这是停止位置追踪的 cleanup 函数。组件卸载时请务必调用。

权限方法

• startUpdateLocation.getPermission

  返回位置权限的当前状态。
• startUpdateLocation.openPermissionDialog

  显示重新请求位置权限的对话框。

错误

当权限被拒绝时 StartUpdateLocationPermissionError会发生。 error instanceof StartUpdateLocationPermissionError即可确认。

const StartUpdateLocationPermissionError: typeof GetCurrentLocationPermissionError;

示例

Web（JS）

import { Accuracy, startUpdateLocation, StartUpdateLocationPermissionError } from '@apps-in-toss/web-framework';

let cleanup;

function handleStartUpdateLocation() {
  cleanup?.();

  cleanup = startUpdateLocation({
    options: { accuracy: Accuracy.Balanced, timeInterval: 3000, distanceInterval: 10 },
    onEvent: (location) => {
      console.log(`纬度: ${location.coords.latitude}, 经度: ${location.coords.longitude}`);
    },
    onError: (error) => {
      if (error instanceof StartUpdateLocationPermissionError) {
        console.log('没有位置权限');
      }
    },
  });
}

window.addEventListener('pagehide', () => cleanup?.());

Web（React）

import {
  Accuracy,
  Location,
  startUpdateLocation,
  StartUpdateLocationPermissionError,
} from '@apps-in-toss/web-framework';
import { useCallback, useState } from 'react';

function LocationWatcher() {
  const [location, setLocation] = useState<Location | null>(null);

  const handlePress = useCallback(() => {
    startUpdateLocation({
      options: { accuracy: Accuracy.Balanced, timeInterval: 3000, distanceInterval: 10 },
      onEvent: (location) => setLocation(location),
      onError: (error) => {
        if (error instanceof StartUpdateLocationPermissionError) {
          // 没有位置权限
        }
      },
    });
  }, []);

  return (
    <div>
      {location != null && (
        <>
          <span>纬度: {location.coords.latitude}</span>
          <span>经度: {location.coords.longitude}</span>
        </>
      )}
      <input type="button" value="开始追踪位置" onClick={handlePress} />

  );
}

React Native

import { Accuracy, Location, startUpdateLocation, StartUpdateLocationPermissionError } from '@apps-in-toss/framework';
import { useCallback, useState } from 'react';
import { Button, Text, View } from 'react-native';

function LocationWatcher() {
  const [location, setLocation] = useState<Location | null>(null);

  const handlePress = useCallback(() => {
    startUpdateLocation({
      options: { accuracy: Accuracy.Balanced, timeInterval: 3000, distanceInterval: 10 },
      onEvent: (location) => setLocation(location),
      onError: (error) => {
        if (error instanceof StartUpdateLocationPermissionError) {
          // 没有位置权限
        }
      },
    });
  }, []);

  return (
    <View>
      {location != null && (
        <>
          <Text>纬度: {location.coords.latitude}</Text>
          <Text>经度: {location.coords.longitude}</Text>
        </>
      )}
      <Button title="开始追踪位置" onPress={handlePress} />
    </View>
  );
}

---

类型 · 对象

位置精度选项（Accuracy)

这是设置位置精度级别的 enum。

enum Accuracy {
  Lowest = 1, // 误差范围在 3KM 以内
  Low = 2, // 误差范围在 1KM 以内
  Balanced = 3, // 误差范围在数百米以内
  High = 4, // 误差范围在 10M 以内
  Highest = 5, // 最高精度
  BestForNavigation = 6, // 用于导航的最高精度
}

---

位置对象（Location)

这是表示位置信息的对象。

interface Location {
  accessLocation?: 'FINE' | 'COARSE'; // 仅限 Android。FINE：精确位置，COARSE：大致位置
  timestamp: number; // 位置更新时的 Unix 时间戳
  coords: LocationCoords; // 详细坐标信息
}

---

详细位置坐标信息（LocationCoords)

这是表示详细位置坐标信息的对象。

interface LocationCoords {
  latitude: number; // 纬度
  longitude: number; // 经度
  altitude: number; // 高度
  accuracy: number; // 位置精度
  altitudeAccuracy: number; // 海拔精度
  heading: number; // 方向
}