From ab894067fa06cabfe11060816aba4f956fec4211 Mon Sep 17 00:00:00 2001 From: shawn_he Date: Wed, 28 Dec 2022 16:54:31 +0800 Subject: [PATCH] update doc Signed-off-by: shawn_he --- .../device/device-location-geocoding.md | 46 ++++---- .../device/device-location-info.md | 102 +++++++----------- .../reference/apis/js-apis-system-location.md | 34 ++++-- 3 files changed, 83 insertions(+), 99 deletions(-) diff --git a/en/application-dev/device/device-location-geocoding.md b/en/application-dev/device/device-location-geocoding.md index f95df63eeb..8a6a9a6751 100644 --- a/en/application-dev/device/device-location-geocoding.md +++ b/en/application-dev/device/device-location-geocoding.md @@ -10,18 +10,17 @@ The geographic description helps users understand a location easily by providing ## Available APIs -The following table describes APIs available for mutual conversion between coordinates and location information. +The following table describes APIs available for mutual conversion between coordinates and geographic description. For details, see [Geolocation Manager](../reference/apis/js-apis-geoLocationManager.md). **Table1** APIs for geocoding and reverse geocoding | API | Description | | -------- | -------- | -| isGeoServiceAvailable(callback: AsyncCallback<boolean>) : void | Checks whether the (reverse) geocoding service is available. This function uses an asynchronous callback to return the result. | -| isGeoServiceAvailable() : Promise<boolean> | Checks whether the (reverse) geocoding service is available. This function uses a promise to return the result. | -| getAddressesFromLocation(request: ReverseGeoCodeRequest, callback: AsyncCallback<Array<GeoAddress>>) : void | Converts coordinates into geographic description through reverse geocoding. This function uses an asynchronous callback to return the result. | -| getAddressesFromLocation(request: ReverseGeoCodeRequest) : Promise<Array<GeoAddress>>; | Converts coordinates into geographic description through reverse geocoding. This function uses a promise to return the result. | -| getAddressesFromLocationName(request: GeoCodeRequest, callback: AsyncCallback<Array<GeoAddress>>) : void | Converts geographic description into coordinates through geocoding. This function uses an asynchronous callback to return the result. | -| getAddressesFromLocationName(request: GeoCodeRequest) : Promise<Array<GeoAddress>> | Converts geographic description into coordinates through geocoding. This function uses a promise to return the result. | +| isGeocoderAvailable(): boolean; | Obtains the (reverse) geocoding service status.| +| getAddressesFromLocation(request: ReverseGeoCodeRequest, callback: AsyncCallback<Array<GeoAddress>>): void | Converts coordinates into geographic description through reverse geocoding. This API uses an asynchronous callback to return the result. | +| getAddressesFromLocation(request: ReverseGeoCodeRequest): Promise<Array<GeoAddress>> | Converts coordinates into geographic description through reverse geocoding. This API uses a promise to return the result. | +| getAddressesFromLocationName(request: GeoCodeRequest, callback: AsyncCallback<Array<GeoAddress>>): void | Converts geographic description into coordinates through geocoding. This API uses an asynchronous callback to return the result. | +| getAddressesFromLocationName(request: GeoCodeRequest): Promise<Array<GeoAddress>> | Converts geographic description into coordinates through geocoding. This API uses a promise to return the result. | ## How to Develop @@ -30,30 +29,29 @@ The following table describes APIs available for mutual conversion between coord > > The **GeoConvert** instance needs to access backend services to obtain information. Therefore, before performing the following steps, ensure that your device is connected to the network. -1. Import the **geolocation** module by which you can implement all APIs related to the geocoding and reverse geocoding conversion capabilities. +1. Import the **geoLocationManager** module by which you can implement all APIs related to the geocoding and reverse geocoding conversion capabilities. - ``` - import geolocation from '@ohos.geolocation'; + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; ``` 2. Query whether geocoder service is available. - Call **isGeoServiceAvailable** to query whether the geocoder service is available. If the service is available, continue with step 3. - ``` - geolocation.isGeoServiceAvailable((err, data) => { - if (err) { - console.log('isGeoServiceAvailable err: ' + JSON.stringify(err)); - } else { - console.log('isGeoServiceAvailable data: ' + JSON.stringify(data)); - } - }); + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + try { + var isAvailable = geoLocationManager.isGeocoderAvailable(); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } ``` 3. Obtain the conversion result. - Call **getAddressesFromLocation** to convert coordinates into geographical location information. - ``` + ```ts var reverseGeocodeRequest = {"latitude": 31.12, "longitude": 121.11, "maxItems": 1}; - geolocation.getAddressesFromLocation(reverseGeocodeRequest, (err, data) => { + geoLocationManager.getAddressesFromLocation(reverseGeocodeRequest, (err, data) => { if (err) { console.log('getAddressesFromLocation err: ' + JSON.stringify(err)); } else { @@ -62,12 +60,12 @@ The following table describes APIs available for mutual conversion between coord }); ``` - Your application can obtain the **GeoAddress** list that matches the specified coordinates and then read location information from it. For details, see [Geolocation](../reference/apis/js-apis-geolocation.md). + Your application can obtain the **GeoAddress** list that matches the specified coordinates and then read location information from it. For details, see [Geolocation](../reference/apis/js-apis-geoLocationManager.md). - Call **getAddressesFromLocationName** to convert geographic description into coordinates. - ``` + ```ts var geocodeRequest = {"description": "No. xx, xx Road, Pudong District, Shanghai", "maxItems": 1}; - geolocation.getAddressesFromLocationName(geocodeRequest, (err, data) => { + geoLocationManager.getAddressesFromLocationName(geocodeRequest, (err, data) => { if (err) { console.log('getAddressesFromLocationName err: ' + JSON.stringify(err)); } else { @@ -76,6 +74,6 @@ The following table describes APIs available for mutual conversion between coord }); ``` - Your application can obtain the **GeoAddress** list that matches the specified location information and read coordinates from it. For details, see [Geolocation](../reference/apis/js-apis-geolocation.md). + Your application can obtain the **GeoAddress** list that matches the specified location information and read coordinates from it. For details, see [Geolocation](../reference/apis/js-apis-geoLocationManager.md). To improve the accuracy of location results, you can set the longitude and latitude ranges in **GeoCodeRequest**. diff --git a/en/application-dev/device/device-location-info.md b/en/application-dev/device/device-location-info.md index a153f69fbf..edd1bb6093 100644 --- a/en/application-dev/device/device-location-info.md +++ b/en/application-dev/device/device-location-info.md @@ -10,68 +10,41 @@ Real-time location of the device is recommended for location-sensitive services. ## Available APIs -The following table describes APIs available for obtaining device location information. - - **Table 1** APIs for obtaining device location information - -| API | Description | -| ------------------------------------------------------------ | ------------------------------------------------------------ | -| on(type: 'locationChange', request: LocationRequest, callback: Callback<Location>) : void | Registers a listener for location changes with a location request initiated. | -| off(type: 'locationChange', callback?: Callback<Location>) : void | Unregisters the listener for location changes with the corresponding location request deleted. | -| on(type: 'locationServiceState', callback: Callback<boolean>) : void | Registers a listener for location service status change events. | -| off(type: 'locationServiceState', callback: Callback<boolean>) : void | Unregisters the listener for location service status change events. | -| on(type: 'cachedGnssLocationsReporting', request: CachedGnssLocationsRequest, callback: Callback<Array<Location>>) : void; | Registers a listener for cached GNSS location reports. | -| off(type: 'cachedGnssLocationsReporting', callback?: Callback<Array<Location>>) : void; | Unregisters the listener for cached GNSS location reports. | -| on(type: 'gnssStatusChange', callback: Callback<SatelliteStatusInfo>) : void; | Registers a listener for satellite status change events. | -| off(type: 'gnssStatusChange', callback?: Callback<SatelliteStatusInfo>) : void; | Unregisters the listener for satellite status change events. | -| on(type: 'nmeaMessageChange', callback: Callback<string>) : void; | Registers a listener for GNSS NMEA message change events. | -| off(type: 'nmeaMessageChange', callback?: Callback<string>) : void; | Unregisters the listener for GNSS NMEA message change events. | -| on(type: 'fenceStatusChange', request: GeofenceRequest, want: WantAgent) : void; | Registers a listener for status change events of the specified geofence. | -| off(type: 'fenceStatusChange', request: GeofenceRequest, want: WantAgent) : void; | Unregisters the listener for status change events of the specified geofence. | -| getCurrentLocation(request: CurrentLocationRequest, callback: AsyncCallback<Location>) : void | Obtains the current location. This API uses an asynchronous callback to return the result. | -| getCurrentLocation(request?: CurrentLocationRequest) : Promise<Location> | Obtains the current location. This API uses a promise to return the result. | -| getLastLocation(callback: AsyncCallback<Location>) : void | Obtains the previous location. This API uses an asynchronous callback to return the result. | -| getLastLocation() : Promise<Location> | Obtains the previous location. This API uses a promise to return the result. | -| isLocationEnabled(callback: AsyncCallback<boolean>) : void | Checks whether the location service is enabled. This API uses an asynchronous callback to return the result. | -| isLocationEnabled() : Promise<boolean> | Checks whether the location service is enabled. This API uses a promise to return the result. | -| requestEnableLocation(callback: AsyncCallback<boolean>) : void | Requests to enable the location service. This API uses an asynchronous callback to return the result. | -| requestEnableLocation() : Promise<boolean> | Requests to enable the location service. This API uses a promise to return the result. | -| enableLocation(callback: AsyncCallback<boolean>) : void | Enables the location service. This API uses an asynchronous callback to return the result. | -| enableLocation() : Promise<boolean> | Enables the location service. This API uses a promise to return the result. | -| disableLocation(callback: AsyncCallback<boolean>) : void | Disables the location service. This API uses an asynchronous callback to return the result. | -| disableLocation() : Promise<boolean> | Disables the location service. This API uses a promise to return the result. | -| getCachedGnssLocationsSize(callback: AsyncCallback<number>) : void; | Obtains the number of cached GNSS locations. This API uses an asynchronous callback to return the result. | -| getCachedGnssLocationsSize() : Promise<number>; | Obtains the number of cached GNSS locations. This API uses a promise to return the result. | -| flushCachedGnssLocations(callback: AsyncCallback<boolean>) : void; | Obtains all cached GNSS locations and clears the GNSS cache queue. This API uses an asynchronous callback to return the result.| -| flushCachedGnssLocations() : Promise<boolean>; | Obtains all cached GNSS locations and clears the GNSS cache queue. This API uses a promise to return the result.| -| sendCommand(command: LocationCommand, callback: AsyncCallback<boolean>) : void; | Sends extended commands to the location subsystem. This API uses an asynchronous callback to return the result.| -| sendCommand(command: LocationCommand) : Promise<boolean>; | Sends extended commands to the location subsystem. This API uses a promise to return the result. | -| isLocationPrivacyConfirmed(type : LocationPrivacyType, callback: AsyncCallback<boolean>) : void; | Checks whether a user agrees with the privacy statement of the location service. This API uses an asynchronous callback to return the result.| -| isLocationPrivacyConfirmed(type : LocationPrivacyType,) : Promise<boolean>; | Checks whether a user agrees with the privacy statement of the location service. This API uses a promise to return the result.| -| setLocationPrivacyConfirmStatus(type : LocationPrivacyType, isConfirmed : boolean, callback: AsyncCallback<boolean>) : void; | Sets the user confirmation status for the privacy statement of the location service. This API uses an asynchronous callback to return the result.| -| setLocationPrivacyConfirmStatus(type : LocationPrivacyType, isConfirmed : boolean) : Promise<boolean>; | Sets the user confirmation status for the privacy statement of the location service. This API uses a promise to return the result.| - +For details about the APIs used to obtain the device location information, see [Geolocation Manager](../reference/apis/js-apis-geoLocationManager.md). ## How to Develop -To learn more about the APIs for obtaining device location information, see [Geolocation](../reference/apis/js-apis-geolocation.md). +To learn more about the APIs for obtaining device location information, see [Geolocation](../reference/apis/js-apis-geoLocationManager.md). 1. Before using basic location capabilities, check whether your application has been granted the permission to access the device location information. If not, your application needs to obtain the permission from the user as described below. The system provides the following location permissions: - ohos.permission.LOCATION + + - ohos.permission.APPROXIMATELY_LOCATION - ohos.permission.LOCATION_IN_BACKGROUND - The **ohos.permission.LOCATION** permission is a must if your application needs to access the device location information. + If your application needs to access the device location information, it must first apply for required permissions. Specifically speaking: + + API versions earlier than 9: Apply for **ohos.permission.LOCATION**. + + API version 9 and later: Apply for **ohos.permission.APPROXIMATELY\_LOCATION**, or apply for **ohos.permission.APPROXIMATELY\_LOCATION** and **ohos.permission.LOCATION**. Note that **ohos.permission.LOCATION** cannot be applied for separately. + + | Target API Level| Location Permission| Permission Application Result| Location Accuracy| + | -------- | -------- | -------- | -------- | + | Earlier than 9| ohos.permission.LOCATION | Success| Location accurate to meters| + | 9 and later| ohos.permission.LOCATION | Failure| No location obtained| + | 9 and later| ohos.permission.APPROXIMATELY_LOCATION | Success| Location accurate to 5 kilometers| + | 9 and later| ohos.permission.APPROXIMATELY_LOCATION and ohos.permission.LOCATION| Success| Location accurate to meters| If your application needs to access the device location information when running on the background, it must be configured to be able to run on the background and be granted the **ohos.permission.LOCATION_IN_BACKGROUND** permission. In this way, the system continues to report device location information after your application moves to the background. You can declare the required permission in your application's configuration file. For details, see [Access Control (Permission) Development](../security/accesstoken-guidelines.md). -2. Import the **geolocation** module by which you can implement all APIs related to the basic location capabilities. +2. Import the **geoLocationManager** module by which you can implement all APIs related to the basic location capabilities. - ``` - import geolocation from '@ohos.geolocation'; + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; ``` 3. Instantiate the **LocationRequest** object. This object provides APIs to notify the system of the location service type and the interval of reporting location information.
@@ -80,7 +53,7 @@ To learn more about the APIs for obtaining device location information, see [Geo To better serve your needs for using APIs, the system has categorized APIs into different packages to match your common use cases of the location function. In this way, you can directly use the APIs specific to a certain use case, making application development much easier. The following table lists the use cases currently supported. - ``` + ```ts export enum LocationRequestScenario { UNSET = 0x300, NAVIGATION, @@ -104,8 +77,8 @@ To learn more about the APIs for obtaining device location information, see [Geo Sample code for initializing **requestInfo** for navigation: - ``` - var requestInfo = {'scenario': geolocation.LocationRequestScenario.NAVIGATION, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0}; + ```ts + var requestInfo = {'scenario': geoLocationManager.LocationRequestScenario.NAVIGATION, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0}; ``` **Method 2:** @@ -113,7 +86,7 @@ To learn more about the APIs for obtaining device location information, see [Geo If the predefined use cases do not meet your needs, you can also use the basic location priority policies provided by the system. - ``` + ```ts export enum LocationRequestPriority { UNSET = 0x200, ACCURACY, @@ -133,14 +106,14 @@ To learn more about the APIs for obtaining device location information, see [Geo Sample code for initializing **requestInfo** for the location accuracy priority policy: - ``` - var requestInfo = {'priority': geolocation.LocationRequestPriority.ACCURACY, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0}; + ```ts + var requestInfo = {'priority': geoLocationManager.LocationRequestPriority.ACCURACY, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0}; ``` 4. Instantiate the **Callback** object for the system to report location results. Your application needs to implement the callback defined by the system. When the system successfully obtains the real-time location of a device, it will report the location result to your application through the callback interface. Your application can implement the callback interface in such a way to complete your own service logic. - ``` + ```ts var locationChange = (location) => { console.log('locationChanger: data: ' + JSON.stringify(location)); }; @@ -148,26 +121,25 @@ To learn more about the APIs for obtaining device location information, see [Geo 5. Start device location. - ``` - geolocation.on('locationChange', requestInfo, locationChange); + ```ts + geoLocationManager.on('locationChange', requestInfo, locationChange); ``` 6. (Optional) Stop device location. - ``` - geolocation.off('locationChange', locationChange); + ```ts + geoLocationManager.off('locationChange', locationChange); ``` If your application does not need the real-time device location, it can use the last known device location cached in the system instead. - ``` - geolocation.getLastLocation((err, data) => { - if (err) { - console.log('getLastLocation: err: ' + JSON.stringify(err)); - } else { - console.log('getLastLocation: data: ' + JSON.stringify(data)); - } - }); + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + try { + var location = geoLocationManager.getLastLocation(); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } ``` To call this method, your application needs to request the **ohos.permission.LOCATION** permission from the user. diff --git a/en/application-dev/reference/apis/js-apis-system-location.md b/en/application-dev/reference/apis/js-apis-system-location.md index b0648efc47..80101da6c8 100644 --- a/en/application-dev/reference/apis/js-apis-system-location.md +++ b/en/application-dev/reference/apis/js-apis-system-location.md @@ -1,9 +1,8 @@ # Geographic Location -> **Noteļ¼š** -> - The APIs of this module are no longer maintained since API version 7. It is recommended that you use [`@ohos.geolocation`](js-apis-geolocation.md) instead. -> +> **NOTE** > - The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> - The APIs provided by this module are no longer maintained since API version 9. You are advised to use [geoLocationManager](js-apis-geoLocationManager.md) instead. ## Modules to Import @@ -19,19 +18,22 @@ import geolocation from '@system.geolocation'; ohos.permission.LOCATION -## geolocation.getLocation +## geolocation.getLocation(deprecated) getLocation(Object): void Obtains the geographic location. +> **NOTE** +> This API is deprecated since API version 9. You are advised to use [geoLocationManager.getCurrentLocation](js-apis-geoLocationManager.md#geolocationmanagergetcurrentlocation). + **System capability**: SystemCapability.Location.Location.Lite **Parameters** | Parameter | Type | Mandatory | Description | | -------- | -------- | -------- | -------- | -| timeout | number | No | Timeout duration, in milliseconds. The default value is **30000**.
The timeout duration is necessary in case the request to obtain the geographic location is rejected for the lack of the required permission, weak positioning signal, or incorrect location settings. After the timeout duration expires, the fail function will be called.
The value is a 32-digit positive integer. If the value set is less than or equal to **0**, the default value will be used. | +| timeout | number | No | Timeout duration, in milliseconds. The default value is **30000**.
The timeout duration is necessary in case the request to obtain the geographic location is rejected for the lack of the required permission, weak positioning signal, or incorrect location settings. After the timeout duration expires, the fail function will be called.
The value is a 32-digit positive integer. If the value set is less than or equal to **0**, the default value will be used. | | coordType | string | No | Coordinate system type. Available types can be obtained by **getSupportedCoordTypes**. The default type is **wgs84**. | | success | Function | No | Called when the operation is successful. | | fail | Function | No | Called when the operation fails. | @@ -75,12 +77,15 @@ export default { ``` -## geolocation.getLocationType +## geolocation.getLocationType(deprecated) getLocationType(Object): void Obtains the supported location types. +> **NOTE** +> This API is deprecated since API version 9. + **System capability**: SystemCapability.Location.Location.Lite **Parameters** @@ -115,12 +120,15 @@ export default { ``` -## geolocation.subscribe +## geolocation.subscribe(deprecated) subscribe(Object): void Listens to the geographical location. If this method is called multiple times, the last call takes effect. +> **NOTE** +> This API is deprecated since API version 9. You are advised to use [geoLocationManager.on('locationChange')](js-apis-geoLocationManager.md#geolocationmanageronlocationchange). + **System capability**: SystemCapability.Location.Location.Lite **Parameters** @@ -167,12 +175,15 @@ export default { ``` -## geolocation.unsubscribe +## geolocation.unsubscribe(deprecated) unsubscribe(): void Cancels listening to the geographical location. +> **NOTE** +> This API is deprecated since API version 9. You are advised to use [geoLocationManager.off('locationChange')](js-apis-geoLocationManager.md#geolocationmanagerofflocationchange). + **System capability**: SystemCapability.Location.Location.Lite **Example** @@ -186,12 +197,15 @@ export default { ``` -## geolocation.getSupportedCoordTypes +## geolocation.getSupportedCoordTypes(deprecated) getSupportedCoordTypes(): Array<string> Obtains coordinate system types supported by the device. +> **NOTE** +> This API is deprecated since API version 9. + **System capability**: SystemCapability.Location.Location.Lite **Return Value** @@ -208,4 +222,4 @@ export default { var types = geolocation.getSupportedCoordTypes(); }, } -``` \ No newline at end of file +``` -- GitLab