# Location
# openLocation
iOS requires Extension SDK or MapSDK dependency. If both Extension SDK and MapSDK are depended on, the openLocation provided by MapSDK takes precedence.
Android requires MapSDK dependency (Google solution is temporarily not supported)
openLocation(Object object)
Opens the built-in map to view a location.
Parameters
Object object
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| latitude | number | Yes | Latitude, range -90~90, negative values indicate south latitude. Uses gcj02 coordinate system | |
| longitude | number | Yes | Longitude, range -180~180, negative values indicate west longitude. Uses gcj02 coordinate system | |
| scale | number | 16 | No | Zoom level, range 5~18 |
| name | string | No | Location name | |
| address | string | No | Detailed address description | |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for API call completion (executed for both success and failure) |
Sample Code
ft.getLocation({
type: 'gcj02', //Returns coordinates that can be used with ft.openLocation
success (res) {
const latitude = res.latitude
const longitude = res.longitude
ft.openLocation({
latitude,
longitude,
scale: 18
})
}
})
Note
- API authorization failure (iOS):
- User denied authorization, returns error: unauthorized, user has not granted location permission
- Host-App prohibits Mini-Program from actively applying for permissions, returns error: unauthorized disableauthorized, SDK is prohibited from applying for location permission
- API authorization failure (Android):
- User denied authorization, the map View will locate to the default position, subsequent manual search and location selection is allowed
# getLocation
Supported from Base Library 1.3.9, iOS version 2.1.23
iOS requires Extension SDK dependency
Android requires Extension SDK or MapSDK dependency. If both Extension SDK and MapSDK are depended on, the getLocation provided by MapSDK takes precedence.
If encountering slow positioning or unsatisfactory positioning success rate when using Extension SDK on Android, you can integrate MapSDK to utilize the positioning capabilities provided by third-party positioning SDKs (Amap, Baidu, Tencent, Google). Otherwise, it is recommended to use the getLocation provided by the Extension SDK.
getLocation(Object object)
Gets the current geographic location and other information. This API cannot be called after the user leaves the Mini-Program.
Parameters
Object object
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| type | string | wgs84 | No | wgs84 returns GPS coordinates, gcj02 returns coordinates that can be used with ft.openLocation |
| isHighAccuracy | boolean | false | No | Enable high-accuracy positioning (Supported from iOS SDK 2.38.1, Android SDK 2.35.1) |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for API call completion (executed for both success and failure) |
Note
- API authorization failure (iOS):
- User denied authorization, returns error: unauthorized, user has not granted location permission
- Host-App prohibits Mini-Program from actively applying for permissions, returns error: unauthorized disableauthorized, SDK is prohibited from applying for location permission
- API authorization failure (Android):
- User denied authorization, returns error: unauthorized, user has not granted permission to obtain location information
- Host-App prohibits Mini-Program from actively applying for permissions, returns error: unauthorized disableauthorized, SDK is prohibited from actively initiating permission requests
# choosePoi
iOS requires Extension SDK dependency
Android requires MapSDK dependency (Google solution is temporarily not supported)
choosePoi(Object object)
Opens POI list to select a location, supporting mixed selection of fuzzy positioning (accurate to city level) and precise positioning.
Parameters
Object object
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for API call completion (executed for both success and failure) |
object.success Callback Function
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| type | number | Value is 0 when selecting not to show location, 1 when selecting city, 2 when selecting precise location |
| city | string | City name |
| name | string | Location name |
| address | string | Detailed address |
| latitude | string | Latitude, floating-point number, range -90~90, negative values indicate south latitude. Uses gcj02 coordinate system |
| longitude | string | Longitude, floating-point number, range -180~180, negative values indicate west longitude. Uses gcj02 coordinate system |
Note
- API authorization failure (iOS):
- User denied authorization, returns error: unauthorized, user has not granted location permission
- Host-App prohibits Mini-Program from actively applying for permissions, returns error: unauthorized disableauthorized, SDK is prohibited from applying for location permission
- API authorization failure (Android):
- User denied authorization, the map View will locate to the default position, subsequent manual search and location selection is allowed
# chooseLocation
Supported from Base Library 1container.3.9, iOS version 2.1.23
iOS requires Extension SDK or MapSDK dependency. If both Extension SDK and MapSDK are depended on, the openLocation provided by MapSDK takes precedence.
Android requires MapSDK dependency (Google solution is temporarily not supported)
chooseLocation(Object object)
Opens the map to select a location.
Parameters
Object object
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| latitude | number | No | Target latitude | |
| longitude | number | No | Target longitude | |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for API call completion (executed for both success and failure) |
object.success Callback Function
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| name | string | Location name |
| address | string | Detailed address |
| latitude | string | Latitude, floating-point number, range -90~90, negative values indicate south latitude. Uses gcj02 coordinate system |
| longitude | string | Longitude, floating-point number, range -180~180, negative values indicate west longitude. Uses gcj02 coordinate system |
Note
- API authorization failure (iOS):
- User denied authorization, returns error: unauthorized, user has not granted location permission
- Host-App prohibits Mini-Program from actively applying for permissions, returns error: unauthorized disableauthorized, SDK is prohibited from applying for location permission
- API authorization failure (Android):
- User denied authorization, the map View will locate to the default position, subsequent manual search and location selection is allowed
# stopLocationUpdate
Supported from Base Library 3.0.18, iOS SDK 2.39.1, Android SDK 2.39.1
stopLocationUpdate(Object object)
Stops listening for real-time location changes, stops receiving messages in both foreground and background.
Parameters
Object object
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for API call completion (executed for both success and failure) |
# startLocationUpdateBackground
Supported from Base Library 3.0.18, iOS SDK 2.39.1, Android SDK 2.39.1
startLocationUpdateBackground(Object object)
Enables receiving location messages when the Mini-Program enters both foreground and background.
Parameters
Object object
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| type | string | gcj02 | No | wgs84 returns GPS coordinates, gcj02 returns coordinates that can be used with ft.openLocation |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for API call completion (executed for both success and failure) |
# startLocationUpdate
Supported from Base Library 3.0.18, iOS SDK 2.39.1, Android SDK 2.39.1
startLocationUpdate(Object object)
Enables receiving location messages when the Mini-Program enters the foreground.
Parameters
Object object
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| type | string | gcj02 | No | wgs84 returns GPS coordinates, gcj02 returns coordinates that can be used with ft.openLocation |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for API call completion (executed for both success and failure) |
# onLocationChange
Supported from Base Library 3.0.18, iOS SDK 2.39.1, Android SDK 2.39.1
onLocationChange(Object object)
Listens for real-time geographic location change events.
Parameters
Object object
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| latitude | number | Latitude, range -90~90, negative values indicate south latitude. Uses gcj02 coordinate system | ||
| longitude | number | Longitude, range -180~180, negative values indicate west longitude. Uses gcj02 coordinate system | ||
| speed | number | Speed, unit m/s | ||
| accuracy | number | Position accuracy | ||
| altitude | number | Altitude, unit m | ||
| verticalAccuracy | number | Vertical accuracy, unit m (Cannot be obtained on Android, returns 0) | ||
| horizontalAccuracy | number | Horizontal accuracy, unit m |
# offLocationChange
Supported from Base Library 3.0.18, iOS SDK 2.39.1, Android SDK 2.39.1
offLocationChange(Object object)
Removes the listener function for real-time geographic location change events.
Parameters
Object object
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| listener | function | The listener function passed to onLocationChange. If this parameter is not passed, all listener functions are removed. |
# onLocationChangeError
Supported from Base Library 3.0.18, iOS SDK 2.39.1, Android SDK 2.39.1
onLocationChangeError(Object object)
Triggered when listening for continuous positioning API returns failure.
Parameters
Object object
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| errCode | number | Error code |
# offLocationChangeError
Supported from Base Library 3.0.18, iOS SDK 2.39.1, Android SDK 2.39.1
offLocationChangeError(Object object)
Removes the listener function triggered when the continuous positioning API returns failure.
Parameters
Object object
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| listener | function |
# convertCoordinateFromMap
Supported from Base Library 3.0.19
This API is implemented via Registering Custom Mini-Program Synchronous APIs, the Base Library itself does not directly provide this API
convertCoordinateFromMap(Object object)
Converts the latitude and longitude returned by the SDK using this API.
Parameters
Object object
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| latitude | number | Yes | Target latitude | |
| longitude | number | Yes | Target longitude |
Note
- This is a synchronous API. After the APP implements this API, the Base Library will automatically call this API to convert coordinates in related APIs and components.
- APIs converted by the Base Library: chooseLocation, choosePoi, MapContext related APIs.
- Map component related events and properties will also be converted, e.g., latitude and longitude carried in bindtap, bindmarkertap...
# convertCoordinateFromApplet
Supported from Base Library 3.0.19
This API is implemented via Registering Custom Mini-Program Synchronous APIs
convertCoordinateFromApplet(Object object)
Converts the latitude and longitude input by the user using this API.
Parameters
Object object
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| latitude | number | Yes | Target latitude | |
| longitude | number | Yes | Target longitude |
Note
- This is a synchronous API. After the APP implements this API, the Base Library will automatically call this API to convert coordinates in related APIs and components.
- APIs converted by the Base Library: openLocation, MapContext related APIs.
- Map component related events and properties will also be converted, e.g., latitude, longitude, polyline and other properties...