mirror of
https://gitee.com/openharmony/base_location
synced 2024-11-23 06:50:03 +00:00
bugfix:change readmewq!
Signed-off-by: liu-binjun <liubinjun@huawei.com>
This commit is contained in:
liu-binjun
parent
d79d6942e0
commit
f2cb8f8624
284
README.en.md
284
README.en.md
@ -46,18 +46,13 @@ Location awareness helps determine where a mobile device locates. The system ide
|
||||
## Directory Structure<a name="section161941989596"></a>
|
||||
|
||||
```
|
||||
/base/location # Source code
|
||||
├── etc # Code for the service startup configuration
|
||||
├── interfaces # APIs
|
||||
├── profile # Code for service declaration
|
||||
├── location_common # Common code
|
||||
├── location_locator # Location service management code
|
||||
├── location_gnss # GNSS positioning service code
|
||||
├── location_network # Network positioning service code
|
||||
├── location_passive # Passive positioning service code
|
||||
├── location_geocode # Geocoding service code
|
||||
├── test # Test code
|
||||
├── utils # Common utility code
|
||||
/base/location # Source code directory structure：
|
||||
├── figures # Store the architecture diagram in readme
|
||||
├── frameworks # Location framework code
|
||||
├── interfaces # External interface
|
||||
├── sa_profile # SA's profile
|
||||
├── services # Directory of SA codes for location services
|
||||
├── test # Test Code Directory
|
||||
```
|
||||
|
||||
## Constraints<a name="section119744591305"></a>
|
||||
@ -70,273 +65,12 @@ Location awareness helps determine where a mobile device locates. The system ide
|
||||
|
||||
### Available APIs<a name="section1551164914237"></a>
|
||||
|
||||
1. The following table describes APIs available for obtaining device location information.
|
||||
|
||||
**Table 1** APIs for obtaining device location information
|
||||
|
||||
| Interface Name | function description |
|
||||
| -------- | -------- |
|
||||
| on(type: 'locationChange', request: LocationRequest, callback: Callback<Location>) : void | Enable location change subscription and initiate a location request. |
|
||||
| off(type: 'locationChange', callback?: Callback<Location>) : void | Disable the location change subscription and delete the corresponding location request. |
|
||||
| on(type: 'locationServiceState', callback: Callback<boolean>) : void | The subscription location service status changes. |
|
||||
| off(type: 'locationServiceState', callback: Callback<boolean>) : void | Unsubscribe from location service status changes. |
|
||||
| on(type: 'cachedGnssLocationsReporting', request: CachedGnssLocationsRequest, callback: Callback<Array<Location>>) : void; | Subscribe to cache GNSS location reporting. |
|
||||
| off(type: 'cachedGnssLocationsReporting', callback?: Callback<Array<Location>>) : void; | Unsubscribe from cached GNSS location reporting. |
|
||||
| on(type: 'gnssStatusChange', callback: Callback<SatelliteStatusInfo>) : void; | Subscribe to satellite status update events. |
|
||||
| off(type: 'gnssStatusChange', callback?: Callback<SatelliteStatusInfo>) : void; | Unsubscribe from satellite status update events. |
|
||||
| on(type: 'nmeaMessageChange', callback: Callback<string>) : void; | Subscribe to GNSS NMEA information change reporting. |
|
||||
| off(type: 'nmeaMessageChange', callback?: Callback<string>) : void; | Unsubscribe to GNSS NMEA information change reporting. |
|
||||
| on(type: 'fenceStatusChange', request: GeofenceRequest, want: WantAgent) : void; | Add a fence and subscribe to the event reporting of the fence. |
|
||||
| off(type: 'fenceStatusChange', request: GeofenceRequest, want: WantAgent) : void; | Delete the fence and unsubscribe from the fence event. |
|
||||
| getCurrentLocation(request: CurrentLocationRequest, callback: AsyncCallback<Location>) : void | Obtain the current location and use the callback callback to return the result asynchronously. |
|
||||
| getCurrentLocation(request?: CurrentLocationRequest) : Promise<Location> | Obtains the current location and returns the result asynchronously in Promise mode. |
|
||||
| getLastLocation(callback: AsyncCallback<Location>) : void | Obtain the last location and use the callback callback to return the result asynchronously. |
|
||||
| getLastLocation() : Promise<Location> | Obtains the last location and returns the result asynchronously in Promise mode. |
|
||||
| isLocationEnabled(callback: AsyncCallback<boolean>) : void | Check whether the location service is enabled and callback is used to return the result asynchronously. |
|
||||
| isLocationEnabled() : Promise<boolean> | Check whether the location service is enabled and return the result asynchronously in Promise mode. |
|
||||
| requestEnableLocation(callback: AsyncCallback<boolean>) : void | Request to enable the location service and use the callback callback to return the result asynchronously. |
|
||||
| requestEnableLocation() : Promise<boolean> | Request to enable the location service and return the result asynchronously in Promise mode. |
|
||||
| enableLocation(callback: AsyncCallback<boolean>) : void | Enable the location service and use the callback callback to return the result asynchronously. |
|
||||
| enableLocation() : Promise<boolean> | Start the location service and return the result asynchronously in Promise mode. |
|
||||
| disableLocation(callback: AsyncCallback<boolean>) : void | Disable the location service and use the callback callback to return the result asynchronously. |
|
||||
| disableLocation() : Promise<boolean> | Stop the location service and return the result asynchronously in Promise mode. |
|
||||
| getCachedGnssLocationsSize(callback: AsyncCallback<number>) : void; | Obtains the number of cached GNSS locations and uses the callback callback to return the result asynchronously. |
|
||||
| getCachedGnssLocationsSize() : Promise<number>; | Obtains the number of cached GNSS locations and returns the result asynchronously in Promise mode. |
|
||||
| flushCachedGnssLocations(callback: AsyncCallback<boolean>) : void; | Obtains all GNSS cache locations, clears the GNSS cache queue, and invokes callback to return results asynchronously. |
|
||||
| flushCachedGnssLocations() : Promise<boolean>; | Obtains all GNSS cache locations, clears the GNSS cache queue, and returns results asynchronously in Promise mode. |
|
||||
| sendCommand(command: LocationCommand, callback: AsyncCallback<boolean>) : void; | Send an extended command to the location service subsystem and use the callback callback to return the result asynchronously. |
|
||||
| sendCommand(command: LocationCommand) : Promise<boolean>; | Sends extended commands to the location service subsystem and returns results asynchronously in Promise mode. |
|
||||
| isLocationPrivacyConfirmed(type : LocationPrivacyType, callback: AsyncCallback<boolean>) : void; | This interface is used to query whether a user agrees with the privacy statement of the LCS service. The callback callback interface is used to return the result asynchronously. |
|
||||
| isLocationPrivacyConfirmed(type : LocationPrivacyType,) : Promise<boolean>; | This interface is used to query whether a user agrees with the privacy statement of the LCS service. The result is returned asynchronously in Promise mode. |
|
||||
| setLocationPrivacyConfirmStatus(type : LocationPrivacyType, isConfirmed : boolean, callback: AsyncCallback<boolean>) : void; | Set and record whether the user agrees to the privacy statement of the LCS service and use the callback callback to return the result asynchronously. |
|
||||
| setLocationPrivacyConfirmStatus(type : LocationPrivacyType, isConfirmed : boolean) : Promise<boolean>; | Set and record whether the user agrees to the privacy statement of the LCS. The result is returned asynchronously in Promise mode. |
|
||||
https://gitee.com/openharmony/interface_sdk-js/blob/master/api/@ohos.geolocation.d.ts
|
||||
|
||||
|
||||
### Usage Guidelines<a name="section129654513264"></a>
|
||||
|
||||
**Obtaining the device location information:**
|
||||
|
||||
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.
|
||||
|
||||
The system provides the following location permissions:
|
||||
|
||||
- ohos.permission.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 when running on the background, it must be allowed to run on the background in the configuration file and also granted the **ohos.permission.LOCATION\_IN\_BACKGROUND** permission. In this way, the system continues to report device location information even when your application moves to the background.
|
||||
|
||||
To allow your application to access device location information, you can declare the required permissions in the **config.json** file of your application. The sample code is as follows:
|
||||
|
||||
```
|
||||
{
|
||||
"reqPermissions": [{
|
||||
"name": "ohos.permission.LOCATION",
|
||||
"reason": "$string:reason_description",
|
||||
"usedScene": {
|
||||
"ability": ["com.myapplication.LocationAbility"],
|
||||
"when": "inuse"
|
||||
}, {
|
||||
...
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
2. Import the geolocation module. All function APIs related to basic location capabilities are provided through this module.
|
||||
|
||||
```
|
||||
import geolocation from '@ohos.geolocation';
|
||||
```
|
||||
|
||||
3. Instantiates the LocationRequest object to notify the system of the type of location service to be provided to the application and the frequency of reporting location results.
|
||||
|
||||
**Method 1:**
|
||||
|
||||
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.
|
||||
|
||||
**Table 2** Common use cases of the location function
|
||||
|
||||
<a name="table1758483964015"></a>
|
||||
<table><thead align="left"><tr id="row458433920403"><th class="cellrowborder" valign="top" width="14.92850714928507%" id="mcps1.2.4.1.1"><p id="p12584143911402"><a name="p12584143911402"></a><a name="p12584143911402"></a>Use Case</p>
|
||||
</th>
|
||||
<th class="cellrowborder" valign="top" width="25.16748325167483%" id="mcps1.2.4.1.2"><p id="p125842039174016"><a name="p125842039174016"></a><a name="p125842039174016"></a>Constant</p>
|
||||
</th>
|
||||
<th class="cellrowborder" valign="top" width="59.904009599040094%" id="mcps1.2.4.1.3"><p id="p10585139134010"><a name="p10585139134010"></a><a name="p10585139134010"></a>Description</p>
|
||||
</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody><tr id="row858573914011"><td class="cellrowborder" valign="top" width="14.92850714928507%" headers="mcps1.2.4.1.1 "><p id="p258518398406"><a name="p258518398406"></a><a name="p258518398406"></a>Navigation</p>
|
||||
</td>
|
||||
<td class="cellrowborder" valign="top" width="25.16748325167483%" headers="mcps1.2.4.1.2 "><p id="p1758513915403"><a name="p1758513915403"></a><a name="p1758513915403"></a>SCENE_NAVIGATION</p>
|
||||
</td>
|
||||
<td class="cellrowborder" valign="top" width="59.904009599040094%" headers="mcps1.2.4.1.3 "><p id="p4585183934017"><a name="p4585183934017"></a><a name="p4585183934017"></a>Applicable when your application needs to obtain the real-time location of a mobile device outdoors, such as navigation for driving or walking. In this scenario, the GNSS positioning technology is mainly used to ensure the location accuracy. However, due to its limitations, the technology may be unable to provide the location service when navigation is just started or when the user moves into a shielded environment such as indoors or a garage. To resolve this issue, the system uses the network positioning technology as an alternative to provide the location service for your application until the GNSS can provide stable location results. This helps achieve a smooth navigation experience for users.</p>
|
||||
<p id="p12585039174017"><a name="p12585039174017"></a><a name="p12585039174017"></a>By default, the system reports location results at a minimal interval of 1s. To adopt this use case, you must declare the <strong id="b975004216292"><a name="b975004216292"></a><a name="b975004216292"></a>ohos.permission.LOCATION</strong> permission and obtain user authorization.</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="row1458543934016"><td class="cellrowborder" valign="top" width="14.92850714928507%" headers="mcps1.2.4.1.1 "><p id="p258523944018"><a name="p258523944018"></a><a name="p258523944018"></a>Trajectory tracking</p>
|
||||
</td>
|
||||
<td class="cellrowborder" valign="top" width="25.16748325167483%" headers="mcps1.2.4.1.2 "><p id="p9585133904019"><a name="p9585133904019"></a><a name="p9585133904019"></a>SCENE_TRAJECTORY_TRACKING</p>
|
||||
</td>
|
||||
<td class="cellrowborder" valign="top" width="59.904009599040094%" headers="mcps1.2.4.1.3 "><p id="p1358553984019"><a name="p1358553984019"></a><a name="p1358553984019"></a>Applicable when your application needs to record user trajectories, for example, the track recording function of sports applications. In this scenario, the GNSS positioning technology is mainly used to ensure the location accuracy.</p>
|
||||
<p id="p9585153917401"><a name="p9585153917401"></a><a name="p9585153917401"></a>By default, the system reports location results at a minimal interval of 1s. To adopt this use case, you must declare the <strong id="b18532492293"><a name="b18532492293"></a><a name="b18532492293"></a>ohos.permission.LOCATION</strong> permission and obtain user authorization.</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="row258503916400"><td class="cellrowborder" valign="top" width="14.92850714928507%" headers="mcps1.2.4.1.1 "><p id="p1658513396408"><a name="p1658513396408"></a><a name="p1658513396408"></a>Ride hailing</p>
|
||||
</td>
|
||||
<td class="cellrowborder" valign="top" width="25.16748325167483%" headers="mcps1.2.4.1.2 "><p id="p6585639124019"><a name="p6585639124019"></a><a name="p6585639124019"></a>SCENE_CAR_HAILING</p>
|
||||
</td>
|
||||
<td class="cellrowborder" valign="top" width="59.904009599040094%" headers="mcps1.2.4.1.3 "><p id="p125857398404"><a name="p125857398404"></a><a name="p125857398404"></a>Applicable when your application needs to obtain the current location of a user who is hailing a taxi.</p>
|
||||
<p id="p1158563974014"><a name="p1158563974014"></a><a name="p1158563974014"></a>By default, the system reports location results at a minimal interval of 1s. To adopt this use case, you must declare the <strong id="b91255452918"><a name="b91255452918"></a><a name="b91255452918"></a>ohos.permission.LOCATION</strong> permission and obtain user authorization.</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="row19585839134012"><td class="cellrowborder" valign="top" width="14.92850714928507%" headers="mcps1.2.4.1.1 "><p id="p558583924020"><a name="p558583924020"></a><a name="p558583924020"></a>Life service</p>
|
||||
</td>
|
||||
<td class="cellrowborder" valign="top" width="25.16748325167483%" headers="mcps1.2.4.1.2 "><p id="p18585143914013"><a name="p18585143914013"></a><a name="p18585143914013"></a>SCENE_DAILY_LIFE_SERVICE</p>
|
||||
</td>
|
||||
<td class="cellrowborder" valign="top" width="59.904009599040094%" headers="mcps1.2.4.1.3 "><p id="p1585193994013"><a name="p1585193994013"></a><a name="p1585193994013"></a>Applicable when your application only needs the approximate user location for recommendations and push notifications in scenarios such as when the user is browsing news, shopping online, and ordering food.</p>
|
||||
<p id="p9585183984012"><a name="p9585183984012"></a><a name="p9585183984012"></a>By default, the system reports location results at a minimal interval of 1s. To adopt this use case, you must declare the <strong id="b310562153012"><a name="b310562153012"></a><a name="b310562153012"></a>ohos.permission.LOCATION</strong> permission and obtain user authorization.</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="row16585153914013"><td class="cellrowborder" valign="top" width="14.92850714928507%" headers="mcps1.2.4.1.1 "><p id="p358533911403"><a name="p358533911403"></a><a name="p358533911403"></a>Power efficiency</p>
|
||||
</td>
|
||||
<td class="cellrowborder" valign="top" width="25.16748325167483%" headers="mcps1.2.4.1.2 "><p id="p12585153974020"><a name="p12585153974020"></a><a name="p12585153974020"></a>SCENE_NO_POWER</p>
|
||||
</td>
|
||||
<td class="cellrowborder" valign="top" width="59.904009599040094%" headers="mcps1.2.4.1.3 "><p id="p75851391407"><a name="p75851391407"></a><a name="p75851391407"></a>Applicable when your application does not proactively start the location service for a higher battery efficiency. When responding to another application requesting the same location service, the system marks a copy of the location result to your application. In this way, your application will not consume extra power for obtaining the user location.</p>
|
||||
<p id="p258533913402"><a name="p258533913402"></a><a name="p258533913402"></a>By default, the system reports location results at a minimal interval of 1s. To adopt this use case, you must declare the <strong id="b169496663012"><a name="b169496663012"></a><a name="b169496663012"></a>ohos.permission.LOCATION</strong> permission and obtain user authorization.</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
The following example instantiates the **RequestParam** object for navigation:
|
||||
|
||||
```
|
||||
RequestParam requestParam = new RequestParam(RequestParam.SCENE_NAVIGATION);
|
||||
```
|
||||
|
||||
**Method 2:**
|
||||
|
||||
If the predefined use cases do not meet your needs, you can also use the basic location priority policies provided by the system.
|
||||
|
||||
```
|
||||
export enum LocationRequestPriority {
|
||||
UNSET = 0x200,
|
||||
ACCURACY,
|
||||
LOW_POWER,
|
||||
FIRST_FIX,
|
||||
}
|
||||
```
|
||||
|
||||
**Table 4** Location priority policies
|
||||
|
||||
<a name="table1276019614412"></a>
|
||||
<table><thead align="left"><tr id="row07609619412"><th class="cellrowborder" valign="top" width="29.592959295929592%" id="mcps1.2.4.1.1"><p id="p176096144113"><a name="p176096144113"></a><a name="p176096144113"></a>Policy</p>
|
||||
</th>
|
||||
<th class="cellrowborder" valign="top" width="27.082708270827084%" id="mcps1.2.4.1.2"><p id="p8760368415"><a name="p8760368415"></a><a name="p8760368415"></a>Constant</p>
|
||||
</th>
|
||||
<th class="cellrowborder" valign="top" width="43.32433243324332%" id="mcps1.2.4.1.3"><p id="p127601064415"><a name="p127601064415"></a><a name="p127601064415"></a>Description</p>
|
||||
</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody><tr id="row67609613412"><td class="cellrowborder" valign="top" width="29.592959295929592%" headers="mcps1.2.4.1.1 "><p id="p207608664111"><a name="p207608664111"></a><a name="p207608664111"></a>Location accuracy priority</p>
|
||||
</td>
|
||||
<td class="cellrowborder" valign="top" width="27.082708270827084%" headers="mcps1.2.4.1.2 "><p id="p976017620419"><a name="p976017620419"></a><a name="p976017620419"></a>PRIORITY_ACCURACY</p>
|
||||
</td>
|
||||
<td class="cellrowborder" valign="top" width="43.32433243324332%" headers="mcps1.2.4.1.3 "><p id="p1976017624110"><a name="p1976017624110"></a><a name="p1976017624110"></a>This policy mainly uses the GNSS positioning technology. In an open area, the technology can achieve the meter-level location accuracy, depending on the hardware performance of the device. However, in a shielded environment, the location accuracy may significantly decrease.</p>
|
||||
<p id="p1076036154113"><a name="p1076036154113"></a><a name="p1076036154113"></a>To use this policy, you must declare the <strong id="b1768101919305"><a name="b1768101919305"></a><a name="b1768101919305"></a>ohos.permission.LOCATION</strong> permission and obtain user authorization.</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="row1676014604116"><td class="cellrowborder" valign="top" width="29.592959295929592%" headers="mcps1.2.4.1.1 "><p id="p576056104110"><a name="p576056104110"></a><a name="p576056104110"></a>Fast location priority</p>
|
||||
</td>
|
||||
<td class="cellrowborder" valign="top" width="27.082708270827084%" headers="mcps1.2.4.1.2 "><p id="p14760965417"><a name="p14760965417"></a><a name="p14760965417"></a>PRIORITY_FIRST_FIX</p>
|
||||
</td>
|
||||
<td class="cellrowborder" valign="top" width="43.32433243324332%" headers="mcps1.2.4.1.3 "><p id="p1760106164114"><a name="p1760106164114"></a><a name="p1760106164114"></a>This policy uses the GNSS positioning, base station positioning, WLAN positioning, and Bluetooth positioning technologies simultaneously to obtain the device location in both the indoor and outdoor scenarios. When all positioning technologies provide a location result, the system provides the most accurate location result for your application. This policy can lead to significant hardware resource consumption and power consumption.</p>
|
||||
<p id="p10760965410"><a name="p10760965410"></a><a name="p10760965410"></a>To use this policy, you must declare the <strong id="b1154417237307"><a name="b1154417237307"></a><a name="b1154417237307"></a>ohos.permission.LOCATION</strong> permission and obtain user authorization.</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="row276017654111"><td class="cellrowborder" valign="top" width="29.592959295929592%" headers="mcps1.2.4.1.1 "><p id="p1376019674118"><a name="p1376019674118"></a><a name="p1376019674118"></a>Power efficiency priority</p>
|
||||
</td>
|
||||
<td class="cellrowborder" valign="top" width="27.082708270827084%" headers="mcps1.2.4.1.2 "><p id="p16760156124114"><a name="p16760156124114"></a><a name="p16760156124114"></a>PRIORITY_LOW_POWER</p>
|
||||
</td>
|
||||
<td class="cellrowborder" valign="top" width="43.32433243324332%" headers="mcps1.2.4.1.3 "><p id="p1776096124115"><a name="p1776096124115"></a><a name="p1776096124115"></a>This policy mainly uses the base station positioning, WLAN positioning, and Bluetooth positioning technologies to obtain device location in both indoor and outdoor scenarios. The location accuracy depends on the distribution of surrounding base stations, visible WLANs, and Bluetooth devices and therefore may fluctuate greatly. This policy is recommended and can reduce power consumption when your application does not require high location accuracy or when base stations, visible WLANs, and Bluetooth devices are densely distributed.</p>
|
||||
<p id="p6760196144113"><a name="p6760196144113"></a><a name="p6760196144113"></a>To use this policy, you must declare at least the <strong id="b644522883019"><a name="b644522883019"></a><a name="b644522883019"></a>ohos.permission.LOCATION</strong> permission and obtain user authorization.</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
The positioning accuracy priority policy is used as an example. The instantiation method is as follows:
|
||||
|
||||
```
|
||||
var requestInfo = {'priority': 0x201, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0};
|
||||
```
|
||||
|
||||
4. Instantiate the Callback object, which is used to provide the system with a location report method.
|
||||
The application needs to implement the callback interface defined by the system and instantiate the interface. The system reports the real-time location result of a device to the application through this interface. An application can complete its own business logic in the implementation of the interface.
|
||||
|
||||
```
|
||||
var locationChange = (location) => {
|
||||
console.log('locationChanger: data: ' + JSON.stringify(location));
|
||||
};
|
||||
```
|
||||
|
||||
5. Start device location.
|
||||
|
||||
```
|
||||
geolocation.on('locationChange', requestInfo, locationChange);
|
||||
```
|
||||
|
||||
6. \(Optional\) Stop device location.
|
||||
|
||||
```
|
||||
geolocation.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((data) => {
|
||||
console.log('getLastLocation: data: ' + JSON.stringify(data));
|
||||
});
|
||||
```
|
||||
|
||||
To call this method, your application needs to request the **ohos.permission.LOCATION** permission from the user.
|
||||
|
||||
|
||||
**Converting the coordinates and geocoding information:**
|
||||
|
||||
1. Import the geolocation module. All functional APIs related to the (inverse) geocoding conversion capability are provided through this module.
|
||||
|
||||
```
|
||||
import geolocation from '@ohos.geolocation';
|
||||
```
|
||||
|
||||
You can use **GeoConvert\(Locale locale\)** to create a **GeoConvert** instance based on specified parameters, such as the language and region.
|
||||
|
||||
2. Obtain the conversion result.
|
||||
- Convert coordinates to location information.
|
||||
|
||||
```
|
||||
var reverseGeocodeRequest = {"latitude": 31.12, "longitude": 121.11, "maxItems": 1};
|
||||
geolocation.getAddressesFromLocation(reverseGeocodeRequest, (data) => {
|
||||
console.log('getAddressesFromLocation: ' + JSON.stringify(data));
|
||||
});
|
||||
```
|
||||
|
||||
Your application can obtain the **GeoAddress** list that matches the specified coordinates and then read location information from it. For details, see the _API Reference_.
|
||||
|
||||
- Convert location information to coordinates.
|
||||
|
||||
```
|
||||
var geocodeRequest = {"description": "上海市浦东新区xx路xx号", "maxItems": 1};
|
||||
geolocation.getAddressesFromLocationName(geocodeRequest, (data) => {
|
||||
console.log('getAddressesFromLocationName: ' + JSON.stringify(data));
|
||||
});
|
||||
```
|
||||
|
||||
Your application can obtain the **GeoAddress** list that matches the specified location information and read coordinates from it. For details, see the _API Reference_.
|
||||
https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-geolocation.md
|
||||
|
||||
|
||||
## Repositories Involved<a name="section1371113476307"></a>
|
||||
|
||||
224
README.md
224
README.md
@ -47,17 +47,12 @@
|
||||
|
||||
```
|
||||
/base/location # 源代码目录结构：
|
||||
├── etc # 服务启动配置代码目录
|
||||
├── interfaces # 接口相关代码目录
|
||||
├── profile # 服务声明代码目录
|
||||
├── location_common # 公共代码目录
|
||||
├── location_locator # 定位服务管理代码目录
|
||||
├── location_gnss # gnss定位服务代码目录
|
||||
├── location_network # 网络定位服务代码目录
|
||||
├── location_passive # 被动定位服务代码目录
|
||||
├── location_geocode # 地理编码服务代码目录
|
||||
├── figures # 存放readme中的架构图
|
||||
├── frameworks # 框架代码
|
||||
├── interfaces # 对外接口
|
||||
├── sa_profile # SA的配置文件
|
||||
├── services # 定位服务各个SA代码目录
|
||||
├── test # 测试代码目录
|
||||
├── utils # 公共工具代码目录
|
||||
```
|
||||
|
||||
## 约束<a name="section119744591305"></a>
|
||||
@ -70,217 +65,16 @@
|
||||
|
||||
### 接口说明<a name="section1551164914237"></a>
|
||||
|
||||
1.获取设备的位置信息，所使用的接口说明如下。
|
||||
见如下文档：
|
||||
https://gitee.com/openharmony/interface_sdk-js/blob/master/api/@ohos.geolocation.d.ts
|
||||
|
||||
**表 1** 获取位置信息API功能介绍
|
||||
| 接口名 | 功能描述 |
|
||||
| -------- | -------- |
|
||||
| on(type: 'locationChange', request: LocationRequest, callback: Callback<Location>) : void | 开启位置变化订阅，并发起定位请求。 |
|
||||
| off(type: 'locationChange', callback?: Callback<Location>) : void | 关闭位置变化订阅，并删除对应的定位请求。 |
|
||||
| on(type: 'locationServiceState', callback: Callback<boolean>) : void | 订阅位置服务状态变化。 |
|
||||
| off(type: 'locationServiceState', callback: Callback<boolean>) : void | 取消订阅位置服务状态变化。 |
|
||||
| on(type: 'cachedGnssLocationsReporting', request: CachedGnssLocationsRequest, callback: Callback<Array<Location>>) : void; | 订阅缓存GNSS位置上报。 |
|
||||
| off(type: 'cachedGnssLocationsReporting', callback?: Callback<Array<Location>>) : void; | 取消订阅缓存GNSS位置上报。 |
|
||||
| on(type: 'gnssStatusChange', callback: Callback<SatelliteStatusInfo>) : void; | 订阅卫星状态信息更新事件。 |
|
||||
| off(type: 'gnssStatusChange', callback?: Callback<SatelliteStatusInfo>) : void; | 取消订阅卫星状态信息更新事件。 |
|
||||
| on(type: 'nmeaMessageChange', callback: Callback<string>) : void; | 订阅GNSS NMEA信息变更上报。 |
|
||||
| off(type: 'nmeaMessageChange', callback?: Callback<string>) : void; | 取消订阅GNSS NMEA信息变更上报。 |
|
||||
| on(type: 'fenceStatusChange', request: GeofenceRequest, want: WantAgent) : void; | 添加围栏，并订阅该围栏事件上报。 |
|
||||
| off(type: 'fenceStatusChange', request: GeofenceRequest, want: WantAgent) : void; | 删除围栏，并取消订阅该围栏事件。 |
|
||||
| getCurrentLocation(request: CurrentLocationRequest, callback: AsyncCallback<Location>) : void | 获取当前位置，使用callback回调异步返回结果。 |
|
||||
| getCurrentLocation(request?: CurrentLocationRequest) : Promise<Location> | 获取当前位置，使用Promise方式异步返回结果。 |
|
||||
| getLastLocation(callback: AsyncCallback<Location>) : void | 获取上一次位置，使用callback回调异步返回结果。 |
|
||||
| getLastLocation() : Promise<Location> | 获取上一次位置，使用Promise方式异步返回结果。 |
|
||||
| isLocationEnabled(callback: AsyncCallback<boolean>) : void | 判断位置服务是否已经打开，使用callback回调异步返回结果。 |
|
||||
| isLocationEnabled() : Promise<boolean> | 判断位置服务是否已经开启，使用Promise方式异步返回结果。 |
|
||||
| requestEnableLocation(callback: AsyncCallback<boolean>) : void | 请求打开位置服务，使用callback回调异步返回结果。 |
|
||||
| requestEnableLocation() : Promise<boolean> | 请求打开位置服务，使用Promise方式异步返回结果。 |
|
||||
| enableLocation(callback: AsyncCallback<boolean>) : void | 打开位置服务，使用callback回调异步返回结果。 |
|
||||
| enableLocation() : Promise<boolean> | 打开位置服务，使用Promise方式异步返回结果。 |
|
||||
| disableLocation(callback: AsyncCallback<boolean>) : void | 关闭位置服务，使用callback回调异步返回结果。 |
|
||||
| disableLocation() : Promise<boolean> | 关闭位置服务，使用Promise方式异步返回结果。 |
|
||||
| getCachedGnssLocationsSize(callback: AsyncCallback<number>) : void; | 获取缓存GNSS位置的个数，使用callback回调异步返回结果。 |
|
||||
| getCachedGnssLocationsSize() : Promise<number>; | 获取缓存GNSS位置的个数，使用Promise方式异步返回结果。 |
|
||||
| flushCachedGnssLocations(callback: AsyncCallback<boolean>) : void; | 获取所有的GNSS缓存位置，并清空GNSS缓存队列，使用callback回调异步返回结果。 |
|
||||
| flushCachedGnssLocations() : Promise<boolean>; | 获取所有的GNSS缓存位置，并清空GNSS缓存队列，使用Promise方式异步返回结果。 |
|
||||
| sendCommand(command: LocationCommand, callback: AsyncCallback<boolean>) : void; | 给位置服务子系统发送扩展命令，使用callback回调异步返回结果。 |
|
||||
| sendCommand(command: LocationCommand) : Promise<boolean>; | 给位置服务子系统发送扩展命令，使用Promise方式异步返回结果。 |
|
||||
| isLocationPrivacyConfirmed(type : LocationPrivacyType, callback: AsyncCallback<boolean>) : void; | 查询用户是否同意定位服务的隐私申明，使用callback回调异步返回结果。 |
|
||||
| isLocationPrivacyConfirmed(type : LocationPrivacyType,) : Promise<boolean>; | 查询用户是否同意定位服务的隐私申明，使用Promise方式异步返回结果。 |
|
||||
| setLocationPrivacyConfirmStatus(type : LocationPrivacyType, isConfirmed : boolean, callback: AsyncCallback<boolean>) : void; | 设置并记录用户是否同意定位服务的隐私申明，使用callback回调异步返回结果。 |
|
||||
| setLocationPrivacyConfirmStatus(type : LocationPrivacyType, isConfirmed : boolean) : Promise<boolean>; | 设置并记录用户是否同意定位服务的隐私申明，使用Promise方式异步返回结果。 |
|
||||
|
||||
|
||||
### 使用说明<a name="section129654513264"></a>
|
||||
|
||||
**获取设备位置信息开发步骤如下：**
|
||||
见如下文档：
|
||||
https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-geolocation.md
|
||||
|
||||
1. 应用在使用系统能力前，需要检查是否已经获取用户授权访问设备位置信息。如未获得授权，可以向用户申请需要的位置权限，申请方式请参考。
|
||||
系统提供的定位权限有：
|
||||
- ohos.permission.LOCATION
|
||||
|
||||
- ohos.permission.LOCATION_IN_BACKGROUND
|
||||
|
||||
访问设备的位置信息，必须申请ohos.permission.LOCATION权限，并且获得用户授权。
|
||||
|
||||
如果应用在后台运行时也需要访问设备位置，除了需要将应用声明为允许后台运行外，还必须申请ohos.permission.LOCATION_IN_BACKGROUND权限，这样应用在切入后台之后，系统可以继续上报位置信息。
|
||||
|
||||
开发者可以在应用config.json文件中声明所需要的权限，示例代码如下：
|
||||
|
||||
|
||||
```
|
||||
{
|
||||
"module": {
|
||||
"reqPermissions": [{
|
||||
"name": "ohos.permission.LOCATION",
|
||||
"reason": "$string:reason_description",
|
||||
"usedScene": {
|
||||
"ability": ["com.myapplication.LocationAbility"],
|
||||
"when": "inuse"
|
||||
}, {
|
||||
...
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. 导入geolocation模块，所有与基础定位能力相关的功能API，都是通过该模块提供的。
|
||||
|
||||
```
|
||||
import geolocation from '@ohos.geolocation';
|
||||
```
|
||||
|
||||
3. 实例化LocationRequest对象，用于告知系统该向应用提供何种类型的位置服务，以及位置结果上报的频率。
|
||||
|
||||
**方式一：**
|
||||
|
||||
为了面向开发者提供贴近其使用场景的API使用方式，系统定义了几种常见的位置能力使用场景，并针对使用场景做了适当的优化处理，应用可以直接匹配使用，简化开发复杂度。系统当前支持场景如下表所示。
|
||||
|
||||
|
||||
```
|
||||
export enum LocationRequestScenario {
|
||||
UNSET = 0x300,
|
||||
NAVIGATION,
|
||||
TRAJECTORY_TRACKING,
|
||||
CAR_HAILING,
|
||||
DAILY_LIFE_SERVICE,
|
||||
NO_POWER,
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
**表2** 定位场景类型说明
|
||||
|
||||
| 场景名称 | 常量定义 | 说明 |
|
||||
| -------- | -------- | -------- |
|
||||
| 导航场景 | NAVIGATION | 适用于在户外定位设备实时位置的场景，如车载、步行导航。在此场景下，为保证系统提供位置结果精度最优，主要使用GNSS定位技术提供定位服务，结合场景特点，在导航启动之初，用户很可能在室内、车库等遮蔽环境，GNSS技术很难提供位置服务。为解决此问题，我们会在GNSS提供稳定位置结果之前，使用系统网络定位技术，向应用提供位置服务，以在导航初始阶段提升用户体验。<br/>此场景默认以最小1秒间隔上报定位结果，使用此场景的应用必须申请ohos.permission.LOCATION权限，同时获得用户授权。 |
|
||||
| 轨迹跟踪场景 | TRAJECTORY_TRACKING | 适用于记录用户位置轨迹的场景，如运动类应用记录轨迹功能。主要使用GNSS定位技术提供定位服务。<br/>此场景默认以最小1秒间隔上报定位结果，并且应用必须申请ohos.permission.LOCATION权限，同时获得用户授权。 |
|
||||
| 出行约车场景 | CAR_HAILING | 适用于用户出行打车时定位当前位置的场景，如网约车类应用。<br/>此场景默认以最小1秒间隔上报定位结果，并且应用必须申请ohos.permission.LOCATION权限，同时获得用户授权。 |
|
||||
| 生活服务场景 | DAILY_LIFE_SERVICE | 生活服务场景，适用于不需要定位用户精确位置的使用场景，如新闻资讯、网购、点餐类应用，做推荐、推送时定位用户大致位置即可。<br/>此场景默认以最小1秒间隔上报定位结果，并且应用至少申请ohos.permission.LOCATION权限，同时获得用户授权。 |
|
||||
| 无功耗场景 | NO_POWER | 无功耗场景，适用于不需要主动启动定位业务。系统在响应其他应用启动定位业务并上报位置结果时，会同时向请求此场景的应用程序上报定位结果，当前的应用程序不产生定位功耗。<br/>此场景默认以最小1秒间隔上报定位结果，并且应用需要申请ohos.permission.LOCATION权限，同时获得用户授权。 |
|
||||
|
||||
以导航场景为例，实例化方式如下：
|
||||
|
||||
```
|
||||
var requestInfo = {'scenario': 0x301, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0};
|
||||
```
|
||||
|
||||
**方式二：**
|
||||
|
||||
如果定义的现有场景类型不能满足所需的开发场景，系统提供了基本的定位优先级策略类型。
|
||||
|
||||
|
||||
```
|
||||
export enum LocationRequestPriority {
|
||||
UNSET = 0x200,
|
||||
ACCURACY,
|
||||
LOW_POWER,
|
||||
FIRST_FIX,
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
**表3** 定位优先级策略类型说明：
|
||||
|
||||
| 策略类型 | 常量定义 | 说明 |
|
||||
| -------- | -------- | -------- |
|
||||
| 定位精度优先策略 | ACCURACY | 定位精度优先策略主要以GNSS定位技术为主，在开阔场景下可以提供米级的定位精度，具体性能指标依赖用户设备的定位硬件能力，但在室内等强遮蔽定位场景下，无法提供准确的位置服务。<br/>应用必须申请ohos.permission.LOCATION权限，同时获得用户授权。 |
|
||||
| 快速定位优先策略 | FIRST_FIX | 快速定位优先策略会同时使用GNSS定位、基站定位和WLAN、蓝牙定位技术，以便室内和户外场景下，通过此策略都可以获得位置结果，当各种定位技术都有提供位置结果时，系统会选择其中精度较好的结果返回给应用。因为对各种定位技术同时使用，对设备的硬件资源消耗较大，功耗也较大。<br/>应用必须申请ohos.permission.LOCATION权限，同时获得用户授权。 |
|
||||
| 低功耗定位优先策略 | LOW_POWER | 低功耗定位优先策略主要使用基站定位和WLAN、蓝牙定位技术，也可以同时提供室内和户外场景下的位置服务，因为其依赖周边基站、可见WLAN、蓝牙设备的分布情况，定位结果的精度波动范围较大，如果对定位结果精度要求不高，或者使用场景多在有基站、可见WLAN、蓝牙设备高密度分布的情况下，推荐使用，可以有效节省设备功耗。<br/>应用至少申请ohos.permission.LOCATION权限，同时获得用户授权。 |
|
||||
|
||||
以定位精度优先策略为例，实例化方式如下：
|
||||
|
||||
```
|
||||
var requestInfo = {'priority': 0x201, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0};
|
||||
```
|
||||
|
||||
4. 实例化Callback对象，用于向系统提供位置上报的途径。应用需要自行实现系统定义好的回调接口，并将其实例化。系统在定位成功确定设备的实时位置结果时，会通过该接口上报给应用。应用程序可以在接口的实现中完成自己的业务逻辑。
|
||||
|
||||
```
|
||||
var locationChange = (location) => {
|
||||
console.log('locationChanger: data: ' + JSON.stringify(location));
|
||||
};
|
||||
```
|
||||
|
||||
5. 启动定位。
|
||||
|
||||
```
|
||||
geolocation.on('locationChange', requestInfo, locationChange);
|
||||
```
|
||||
|
||||
6. （可选）结束定位。
|
||||
|
||||
```
|
||||
geolocation.off('locationChange', locationChange);
|
||||
```
|
||||
|
||||
如果应用使用场景不需要实时的设备位置，可以获取系统缓存的最近一次历史定位结果。
|
||||
|
||||
```
|
||||
geolocation.getLastLocation((data) => {
|
||||
console.log('getLastLocation: data: ' + JSON.stringify(data));
|
||||
});
|
||||
```
|
||||
|
||||
此接口的使用需要应用向用户申请ohos.permission.LOCATION权限。
|
||||
|
||||
|
||||
|
||||
**进行坐标和地理编码信息的相互转化开发步骤如下：**
|
||||
|
||||
> **说明：**
|
||||
> GeoConvert需要访问后端服务，请确保设备联网，以进行信息获取。
|
||||
|
||||
1. 导入geolocation模块，所有与（逆）地理编码转化能力相关的功能API，都是通过该模块提供的。
|
||||
|
||||
```
|
||||
import geolocation from '@ohos.geolocation';
|
||||
```
|
||||
|
||||
2. 获取转化结果。
|
||||
- 调用getAddressesFromLocation，坐标转化地理位置信息。
|
||||
|
||||
```
|
||||
var reverseGeocodeRequest = {"latitude": 31.12, "longitude": 121.11, "maxItems": 1};
|
||||
geolocation.getAddressesFromLocation(reverseGeocodeRequest, (data) => {
|
||||
console.log('getAddressesFromLocation: ' + JSON.stringify(data));
|
||||
});
|
||||
```
|
||||
|
||||
参考接口API说明，应用可以获得与此坐标匹配的GeoAddress列表，应用可以根据实际使用需求，读取相应的参数数据。
|
||||
- 调用getAddressesFromLocationName位置描述转化坐标。
|
||||
|
||||
```
|
||||
var geocodeRequest = {"description": "上海市浦东新区xx路xx号", "maxItems": 1};
|
||||
geolocation.getAddressesFromLocationName(geocodeRequest, (data) => {
|
||||
console.log('getAddressesFromLocationName: ' + JSON.stringify(data));
|
||||
});
|
||||
```
|
||||
|
||||
参考接口API说明，应用可以获得与位置描述相匹配的GeoAddress列表，其中包含对应的坐标数据，请参考API使用。
|
||||
|
||||
如果需要查询的位置描述可能出现多地重名的请求，可以设置GeoCodeRequest，通过设置一个经纬度范围，以高效地获取期望的准确结果。
|
||||
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user