Location and mapping capabilities including GPS positioning, location selection, and map integration with various provider support.
Gets the current geographic location of the device using GPS, network, or passive location providers.
/**
* Get current location
* @param options - Location configuration options
* @returns Promise with location information
*/
function getLocation(options?: GetLocationOptions): Promise<GetLocationResult>;
interface GetLocationOptions {
type?: 'wgs84' | 'gcj02';
altitude?: boolean;
geocode?: boolean;
timeout?: number;
cacheTimeout?: number;
isHighAccuracy?: boolean;
success?: (result: GetLocationResult) => void;
fail?: (result: any) => void;
complete?: (result: any) => void;
}
interface GetLocationResult {
latitude: number;
longitude: number;
speed: number;
accuracy: number;
altitude: number;
verticalAccuracy: number;
horizontalAccuracy: number;
address?: string;
}Usage Example:
import { getLocation } from "@dcloudio/uni-h5";
// Get current location with high accuracy
const location = await getLocation({
type: 'wgs84',
isHighAccuracy: true,
geocode: true
});
console.log(`Latitude: ${location.latitude}, Longitude: ${location.longitude}`);
if (location.address) {
console.log(`Address: ${location.address}`);
}Opens the device's map application to display a specific location with optional navigation and marker customization.
/**
* Open location on map
* @param options - Location display options
*/
function openLocation(options: OpenLocationOptions): void;
interface OpenLocationOptions {
latitude: number;
longitude: number;
scale?: number;
name?: string;
address?: string;
success?: (result: any) => void;
fail?: (result: any) => void;
complete?: (result: any) => void;
}Usage Example:
import { openLocation } from "@dcloudio/uni-h5";
// Open a specific location on the map
openLocation({
latitude: 39.908823,
longitude: 116.39747,
scale: 18,
name: "Forbidden City",
address: "No. 4 Jingshan Front Street, Dongcheng District, Beijing"
});Allows users to interactively select a location from a map interface, returning the selected coordinates and address information.
/**
* Choose location from map
* @returns Promise with selected location information
*/
function chooseLocation(): Promise<ChooseLocationResult>;
interface ChooseLocationResult {
name: string;
address: string;
latitude: number;
longitude: number;
}Usage Example:
import { chooseLocation } from "@dcloudio/uni-h5";
// Let user choose a location
try {
const selectedLocation = await chooseLocation();
console.log(`Selected: ${selectedLocation.name}`);
console.log(`Address: ${selectedLocation.address}`);
console.log(`Coordinates: ${selectedLocation.latitude}, ${selectedLocation.longitude}`);
} catch (error) {
console.log('User cancelled location selection');
}Monitor location changes with configurable update intervals and accuracy requirements for real-time location tracking.
/**
* Location change listener
* @param callback - Function called when location changes
*/
function onLocationChange(callback: (result: LocationChangeResult) => void): void;
/**
* Remove location change listener
* @param callback - Optional specific callback to remove
*/
function offLocationChange(callback?: (result: LocationChangeResult) => void): void;
/**
* Start location updates
*/
function startLocationUpdate(): void;
/**
* Stop location updates
*/
function stopLocationUpdate(): void;
interface LocationChangeResult {
latitude: number;
longitude: number;
speed: number;
accuracy: number;
altitude: number;
verticalAccuracy: number;
horizontalAccuracy: number;
}Usage Example:
import {
onLocationChange,
offLocationChange,
startLocationUpdate,
stopLocationUpdate
} from "@dcloudio/uni-h5";
// Start monitoring location changes
const handleLocationChange = (location: LocationChangeResult) => {
console.log(`New location: ${location.latitude}, ${location.longitude}`);
console.log(`Speed: ${location.speed} m/s, Accuracy: ${location.accuracy}m`);
};
onLocationChange(handleLocationChange);
startLocationUpdate();
// Later, stop monitoring
setTimeout(() => {
stopLocationUpdate();
offLocationChange(handleLocationChange);
}, 60000); // Stop after 1 minuteLocation APIs may fail due to various reasons including permission denial, GPS unavailability, or network issues:
// Handle location errors
try {
const location = await getLocation();
// Use location data
} catch (error) {
console.error('Location error:', error);
// Handle specific error cases:
// - Permission denied
// - Location services disabled
// - Timeout
// - Network error
}