1# @ohos.geoLocationManager (位置服务)(系统接口) 2 3位置服务提供GNSS定位、网络定位、地理编码、逆地理编码、国家码和地理围栏等基本功能。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.geoLocationManager (位置服务)](js-apis-geoLocationManager.md)。 9> 本模块能力仅支持WGS-84坐标系。 10 11## 申请权限 12 13应用在使用系统能力前，需要检查是否已经获取用户授权访问设备位置信息。如未获得授权，可以向用户申请需要的位置权限，申请方式请参考下文。 14 15系统提供的定位权限有： 16- ohos.permission.LOCATION 17 18- ohos.permission.APPROXIMATELY_LOCATION 19 20- ohos.permission.LOCATION_IN_BACKGROUND 21 22访问设备的位置信息，必须申请权限，并且获得用户授权。 23 24API9之前的版本，申请ohos.permission.LOCATION即可。 25 26API9及之后的版本，需要申请ohos.permission.APPROXIMATELY_LOCATION或者同时申请ohos.permission.APPROXIMATELY_LOCATION和ohos.permission.LOCATION；无法单独申请ohos.permission.LOCATION。 27 28| 使用的API版本 | 申请位置权限 | 申请结果 | 位置的精确度 | 29| -------- | -------- | -------- | -------- | 30| 小于9 | ohos.permission.LOCATION | 成功 | 获取到精准位置，精准度在米级别。 | 31| 大于等于9 | ohos.permission.LOCATION | 失败 | 无法获取位置。 | 32| 大于等于9 | ohos.permission.APPROXIMATELY_LOCATION | 成功 | 获取到模糊位置，精确度为5公里。 | 33| 大于等于9 | ohos.permission.APPROXIMATELY_LOCATION和ohos.permission.LOCATION | 成功 | 获取到精准位置，精准度在米级别。 | 34 35如果应用在后台运行时也需要访问设备位置，需要申请LOCATION类型的长时任务，这样应用在切入后台之后，系统可以继续上报位置信息。长时任务申请可参考[长时任务](../../task-management/continuous-task.md)。 36 37应用如需使用ohos.permission.LOCATION_IN_BACKGROUND权限，需要在设置界面由用户手动授予，具体授权方式可参考[ohos.permission.LOCATION_IN_BACKGROUND权限说明](../../security/AccessToken/permissions-for-all-user.md#ohospermissionlocation_in_background)。 38 39开发者可以在应用配置文件中声明所需要的权限，具体可参考[向用户申请授权](../../security/AccessToken/request-user-authorization.md)。 40 41 42## 导入模块 43 44```ts 45import { geoLocationManager } from '@kit.LocationKit'; 46``` 47 48## GeoAddress 49 50地理编码地址信息。 51 52**系统能力**：SystemCapability.Location.Location.Geocoder 53 54| 名称 | 类型 | 只读 | 可选 | 说明 | 55| -------- | -------- | -------- | -------- | -------- | 56| isFromMock | Boolean | 否 | 是 | true：地名信息来自于逆地理编码模拟功能。<br/>false：地名信息不是来自于逆地理编码模拟功能。<br/>**系统API**：此接口为系统接口。 | 57 58 59## Location 60 61位置信息。 62 63**系统能力**：SystemCapability.Location.Location.Core 64 65| 名称 | 类型 | 只读 | 可选 | 说明 | 66| -------- | -------- | -------- | -------- | -------- | 67| isFromMock | Boolean | 否 | 是 | true：位置信息来自于位置模拟功能。<br/>false：位置信息不是来自于位置模拟功能。<br/>**系统API**：此接口为系统接口。 | 68 69 70## ReverseGeocodingMockInfo 71 72逆地理编码模拟功能的配置信息，包含一个位置信息和一个地名信息。 73 74**系统能力**：SystemCapability.Location.Location.Core 75 76**系统API**：此接口为系统接口。 77 78| 名称 | 类型 | 只读 | 可选 | 说明 | 79| -------- | -------- | -------- | -------- | -------- | 80| location | [ReverseGeoCodeRequest](js-apis-geoLocationManager.md#reversegeocoderequest) | 否 | 否 | 表示经纬度信息。 | 81| geoAddress | [GeoAddress](#geoaddress) | 否 | 否 |表示地名信息。 | 82 83 84## LocationMockConfig 85 86位置模拟功能的配置参数，包含了模拟位置上报的时间间隔和模拟位置数组。 87 88**系统能力**：SystemCapability.Location.Location.Core 89 90**系统API**：此接口为系统接口。 91 92| 名称 | 类型 | 只读 | 可选 | 说明 | 93| -------- | -------- | -------- | -------- | -------- | 94| timeInterval | number | 否 | 否 | 表示模拟位置上报的时间间隔，单位是秒。 | 95| locations | Array<[Location](#location)> | 否 | 否 | 表示模拟位置数组。 | 96 97## LocatingRequiredDataConfig<sup>10+</sup> 98 99获取定位所需数据时的配置参数。 100 101**系统能力**：SystemCapability.Location.Location.Core 102 103**系统API**：此接口为系统接口。 104 105| 名称 | 类型 | 只读 | 可选 | 说明 | 106| -------- | -------- | -------- | -------- | -------- | 107| type | [LocatingRequiredDataType](#locatingrequireddatatype10) | 否 | 否 | 表示请求获取数据的类型。 | 108| needStartScan | boolean | 否 | 否 | true：需要发起扫描。<br/>false：不需要发起扫描。 | 109| scanInterval | number | 否 | 是 | 表示扫描的时间间隔。单位是毫秒，默认值是10000毫秒，取值范围为大于0。 | 110| scanTimeout | number | 否 | 是 | 表示单次扫描的超时时间。单位是毫秒，默认值是10000毫秒，取值范围为大于0小于600000。 | 111 112 113## LocatingRequiredData<sup>10+</sup> 114 115表示定位业务所需的数据，包含WiFi或蓝牙扫描结果，APP拿到这些数据之后可以用于网络定位等业务。 116 117**系统能力**：SystemCapability.Location.Location.Core 118 119**系统API**：此接口为系统接口。 120 121| 名称 | 类型 | 只读 | 可选 | 说明 | 122| -------- | -------- | -------- | -------- | -------- | 123| wifiData | [WifiScanInfo](#wifiscaninfo10) | 否 | 是 | 表示WiFi扫描结果。 | 124| bluetoothData | [BluetoothScanInfo](#bluetoothscaninfo10) | 否 | 是 | 表示蓝牙扫描结果。 | 125 126 127## WifiScanInfo<sup>10+</sup> 128 129WiFi扫描信息，包含扫描到的WiFi热点的ssid、bssid和rssi等信息。 130 131**系统能力**：SystemCapability.Location.Location.Core 132 133**系统API**：此接口为系统接口。 134 135| 名称 | 类型 | 只读 | 可选 | 说明 | 136| -------- | -------- | -------- | -------- | -------- | 137| ssid | string | 否 | 否 | WiFi热点的SSID，编码格式为UTF-8。 | 138| bssid | string | 否 | 否 | WiFi热点的BSSID。 | 139| rssi | number | 否 | 否 | WiFi热点的信号强度(dBm)。 | 140| frequency | number | 否 | 否 | WiFi热点的频率。 | 141| timestamp | number | 否 | 否 | 时间戳。 | 142 143 144## BluetoothScanInfo<sup>10+</sup> 145 146蓝牙扫描信息。 147 148**系统能力**：SystemCapability.Location.Location.Core 149 150**系统API**：此接口为系统接口。 151 152| 名称 | 类型 | 只读 | 可选 | 说明 | 153| -------- | -------- | -------- | -------- | -------- | 154| deviceName | string | 否 | 否 | 蓝牙设备名称。 | 155| macAddress | string | 否 | 否 | 蓝牙设备的MAC地址。 | 156| rssi | number | 否 | 否 | 蓝牙设备的信号强度(dBm)。 | 157| timestamp | number | 否 | 否 | 时间戳。 | 158 159## LocationPrivacyType 160 161定位服务隐私协议类型。 162 163**系统能力**：SystemCapability.Location.Location.Core 164 165**系统API**：此接口为系统接口。 166 167| 名称 | 值 | 说明 | 168| -------- | -------- | -------- | 169| OTHERS | 0 | 其他场景。预留字段。 | 170| STARTUP | 1 | 开机向导场景下的隐私协议。在开机时弹出协议，提醒用户阅读并选择是否授权。 | 171| CORE_LOCATION | 2 | 开启网络定位时弹出的隐私协议。 | 172 173## LocatingRequiredDataType<sup>10+</sup> 174 175定位业务所需数据的类型。 176 177**系统能力**：SystemCapability.Location.Location.Core 178 179**系统API**：此接口为系统接口。 180 181| 名称 | 值 | 说明 | 182| -------- | -------- | -------- | 183| WIFI | 1 | 表示WiFi扫描信息。 | 184| BLUETOOTH | 2 | 表示蓝牙扫描信息。 | 185 186 187## LocationIconStatus<sup>12+</sup> 188 189定位图标状态。 190 191**系统能力**：SystemCapability.Location.Location.Core 192 193**系统API**：此接口为系统接口。 194 195| 名称 | 值 | 说明 | 196| -------- | -------- | -------- | 197| LOCATING_NOT_STARTED | 0 | 表示当前无定位业务，无需显示定位图标。 | 198| LOCATING_STARTED | 1 | 表示当前在进行普通定位业务，需要显示普通定位图标。 | 199| HD_LOCATING_STARTED | 2 | 表示当前正在进行高精度定位业务，需要显示高精度定位图标。 | 200 201 202## geoLocationManager.on('locatingRequiredDataChange')<sup>10+</sup> 203 204on(type: 'locatingRequiredDataChange', config: LocatingRequiredDataConfig, callback: Callback<Array<LocatingRequiredData>>): void 205 206订阅定位业务所需数据的变化，主要包含WiFi和蓝牙扫描信息；根据入参决定是否启动WiFi和蓝牙扫描。使用callback异步回调。 207 208**需要权限**：ohos.permission.LOCATION 和 ohos.permission.APPROXIMATELY_LOCATION 209 210**系统能力**：SystemCapability.Location.Location.Core 211 212**系统API**：此接口为系统接口。 213 214**参数**： 215 216 | 参数名 | 类型 | 必填 | 说明 | 217 | -------- | -------- | -------- | -------- | 218 | type | string | 是 | 设置事件类型。type为“locatingRequiredDataChange”，表示订阅定位业务所需数据的变化。 | 219 | config | [LocatingRequiredDataConfig](#locatingrequireddataconfig10) | 是 | 表示获取定位所需数据时的配置参数。 | 220 | callback | Callback<Array<[LocatingRequiredData](#locatingrequireddata10)>> | 是 | 回调函数，返回定位业务所需数据。 | 221 222**错误码**： 223 224以下错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 225 226| 错误码ID | 错误信息 | 227| -------- | ---------------------------------------- | 228|201 | Permission verification failed. The application does not have the permission required to call the API. | 229|202 | Permission verification failed. A non-system application calls a system API. | 230|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 231|801 | Capability not supported. Failed to call ${geoLocationManager.on('locatingRequiredDataChange')} due to limited device capabilities. | 232|3301800 | Failed to start WiFi or Bluetooth scanning. | 233 234**示例** 235 236 ```ts 237 import { geoLocationManager } from '@kit.LocationKit'; 238 let callback = (code:Array<geoLocationManager.LocatingRequiredData>):void => { 239 console.info('locatingRequiredDataChange: ' + JSON.stringify(code)); 240 } 241 let config:geoLocationManager.LocatingRequiredDataConfig = {'type': 1, 'needStartScan': true, 'scanInterval': 10000}; 242 try { 243 geoLocationManager.on('locatingRequiredDataChange', config, callback); 244 } catch (err) { 245 console.error("errCode:" + err.code + ", message:" + err.message); 246 } 247 ``` 248 249 250## geoLocationManager.off('locatingRequiredDataChange')<sup>10+</sup> 251 252off(type: 'locatingRequiredDataChange', callback?: Callback<Array<LocatingRequiredData>>): void 253 254取消订阅定位业务所需数据的变化，并停止WiFi和蓝牙扫描。 255 256**需要权限**：ohos.permission.LOCATION 和 ohos.permission.APPROXIMATELY_LOCATION 257 258**系统能力**：SystemCapability.Location.Location.Core 259 260**系统API**：此接口为系统接口。 261 262**参数**： 263 264 | 参数名 | 类型 | 必填 | 说明 | 265 | -------- | -------- | -------- | -------- | 266 | type | string | 是 | 设置事件类型。type为“locatingRequiredDataChange”，表示取消订阅定位业务所需数据的变化。 | 267 | callback | Callback<Array<[LocatingRequiredData](#locatingrequireddata10)>> | 否 | 需要取消订阅的回调函数。该回调函数需要与on接口传入的回调函数保持一致。若无此参数，则取消当前类型的所有订阅。 | 268 269**错误码**： 270 271错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 272 273| 错误码ID | 错误信息 | 274| -------- | ---------------------------------------- | 275|201 | Permission verification failed. The application does not have the permission required to call the API. | 276|202 | Permission verification failed. A non-system application calls a system API. | 277|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 278|801 | Capability not supported. Failed to call ${geoLocationManager.off('locatingRequiredDataChange')} due to limited device capabilities. | 279 280**示例** 281 282 ```ts 283 import { geoLocationManager } from '@kit.LocationKit'; 284 let callback = (code:Array<geoLocationManager.LocatingRequiredData>):void => { 285 console.info('locatingRequiredDataChange: ' + JSON.stringify(code)); 286 } 287 let config:geoLocationManager.LocatingRequiredDataConfig = {'type': 1, 'needStartScan': true, 'scanInterval': 10000}; 288 try { 289 geoLocationManager.on('locatingRequiredDataChange', config, callback); 290 geoLocationManager.off('locatingRequiredDataChange', callback); 291 } catch (err) { 292 console.error("errCode:" + err.code + ", message:" + err.message); 293 } 294 ``` 295 296## geoLocationManager.enableLocation 297 298enableLocation(callback: AsyncCallback<void>): void 299 300打开位置服务，使用callback异步回调。 301 302**系统API**：此接口为系统接口。 303 304**需要权限**：ohos.permission.MANAGE_SECURE_SETTINGS 和 ohos.permission.CONTROL_LOCATION_SWITCH 305 306**系统能力**：SystemCapability.Location.Location.Core 307 308**参数**： 309 310 | 参数名 | 类型 | 必填 | 说明 | 311 | -------- | -------- | -------- | -------- | 312 | callback | AsyncCallback<void> | 是 | 回调函数，当打开位置服务成功，err为undefined，否则为错误对象。 | 313 314**错误码**： 315 316以下错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 317 318| 错误码ID | 错误信息 | 319| -------- | ---------------------------------------- | 320|201 | Permission verification failed. The application does not have the permission required to call the API. | 321|202 | Permission verification failed. A non-system application calls a system API. | 322|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 323|801 | Capability not supported. Failed to call ${geoLocationManager.enableLocation} due to limited device capabilities. | 324|3301000 | The location service is unavailable. | 325 326**示例** 327 328 ```ts 329 import { geoLocationManager } from '@kit.LocationKit'; 330 try { 331 geoLocationManager.enableLocation((err) => { 332 if (err) { 333 console.error('enableLocation: err=' + JSON.stringify(err)); 334 } 335 }); 336 } catch (err) { 337 console.error("errCode:" + err.code + ", message:" + err.message); 338 } 339 ``` 340 341 342## geoLocationManager.enableLocation 343 344enableLocation(): Promise<void> 345 346打开位置服务，使用Promise异步回调。 347 348**系统API**：此接口为系统接口。 349 350**需要权限**：ohos.permission.MANAGE_SECURE_SETTINGS 和 ohos.permission.CONTROL_LOCATION_SWITCH 351 352**系统能力**：SystemCapability.Location.Location.Core 353 354**返回值**： 355 356 | 类型 | 说明 | 357 | -------- | -------- | 358 | Promise<void> | Promise对象。无返回结果的Promise对象 | 359 360**错误码**： 361 362以下错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 363 364| 错误码ID | 错误信息 | 365| -------- | ---------------------------------------- | 366|201 | Permission verification failed. The application does not have the permission required to call the API. | 367|202 | Permission verification failed. A non-system application calls a system API. | 368|801 | Capability not supported. Failed to call ${geoLocationManager.enableLocation} due to limited device capabilities. | 369|3301000 | The location service is unavailable. | 370 371**示例** 372 373 ```ts 374 import { geoLocationManager } from '@kit.LocationKit'; 375 import { BusinessError } from '@kit.BasicServicesKit'; 376 try { 377 geoLocationManager.enableLocation().then(() => { 378 console.info('promise, enableLocation succeed'); 379 }) 380 .catch((error:BusinessError) => { 381 console.error('promise, enableLocation: error=' + JSON.stringify(error)); 382 }); 383 } catch (err) { 384 console.error("errCode:" + err.code + ", message:" + err.message); 385 } 386 ``` 387 388## geoLocationManager.disableLocation 389 390disableLocation(): void 391 392关闭位置服务。 393 394**系统API**：此接口为系统接口。 395 396**需要权限**：ohos.permission.MANAGE_SECURE_SETTINGS 和 ohos.permission.CONTROL_LOCATION_SWITCH 397 398**系统能力**：SystemCapability.Location.Location.Core 399 400**错误码**： 401 402以下错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 403 404| 错误码ID | 错误信息 | 405| -------- | ---------------------------------------- | 406|201 | Permission verification failed. The application does not have the permission required to call the API. | 407|202 | Permission verification failed. A non-system application calls a system API. | 408|801 | Capability not supported. Failed to call ${geoLocationManager.disableLocation} due to limited device capabilities. | 409|3301000 | The location service is unavailable. | 410 411**示例** 412 413 ```ts 414 import { geoLocationManager } from '@kit.LocationKit'; 415 try { 416 geoLocationManager.disableLocation(); 417 } catch (err) { 418 console.error("errCode:" + err.code + ", message:" + err.message); 419 } 420 ``` 421 422## geoLocationManager.enableLocationMock 423 424enableLocationMock(): void 425 426使能位置模拟功能。 427 428**系统能力**：SystemCapability.Location.Location.Core 429 430**系统API**：此接口为系统接口。 431 432**需要权限**: ohos.permission.MOCK_LOCATION 433 434**错误码**： 435 436以下错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 437 438| 错误码ID | 错误信息 | 439| -------- | ---------------------------------------- | 440|201 | Permission verification failed. The application does not have the permission required to call the API. | 441|202 | Permission verification failed. A non-system application calls a system API. | 442|801 | Capability not supported. Failed to call ${geoLocationManager.enableLocationMock} due to limited device capabilities. | 443|3301000 | The location service is unavailable. | 444|3301100 | The location switch is off.| 445 446**示例** 447 448 ```ts 449 import { geoLocationManager } from '@kit.LocationKit'; 450 try { 451 geoLocationManager.enableLocationMock(); 452 } catch (err) { 453 console.error("errCode:" + err.code + ", message:" + err.message); 454 } 455 ``` 456 457 458## geoLocationManager.disableLocationMock 459 460disableLocationMock(): void 461 462去使能位置模拟功能。 463 464**系统能力**：SystemCapability.Location.Location.Core 465 466**系统API**：此接口为系统接口。 467 468**需要权限**: ohos.permission.MOCK_LOCATION 469 470**错误码**： 471 472以下错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 473 474| 错误码ID | 错误信息 | 475| -------- | ---------------------------------------- | 476|201 | Permission verification failed. The application does not have the permission required to call the API. | 477|202 | Permission verification failed. A non-system application calls a system API. | 478|801 | Capability not supported. Failed to call ${geoLocationManager.disableLocationMock} due to limited device capabilities. | 479|3301000 | The location service is unavailable. | 480|3301100 | The location switch is off.| 481 482**示例** 483 484 ```ts 485 import { geoLocationManager } from '@kit.LocationKit'; 486 try { 487 geoLocationManager.disableLocationMock(); 488 } catch (err) { 489 console.error("errCode:" + err.code + ", message:" + err.message); 490 } 491 ``` 492 493 494## geoLocationManager.setMockedLocations 495 496setMockedLocations(config: LocationMockConfig): void 497 498设置模拟的位置信息，后面会以该接口中携带的时间间隔上报模拟位置。 499 500该接口需要在调用[geoLocationManager.enableLocationMock](#geolocationmanagerenablelocationmock)之后才能调用。 501 502**系统能力**：SystemCapability.Location.Location.Core 503 504**系统API**：此接口为系统接口。 505 506**需要权限**: ohos.permission.MOCK_LOCATION 507 508**参数**： 509 510 | 参数名 | 类型 | 必填 | 说明 | 511 | -------- | -------- | -------- | -------- | 512 | config | [LocationMockConfig](#locationmockconfig) | 是 | 指示位置模拟的配置参数，包含模拟位置上报的时间间隔和模拟位置数组。 | 513 514**错误码**： 515 516以下错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 517 518| 错误码ID | 错误信息 | 519| -------- | ---------------------------------------- | 520|201 | Permission verification failed. The application does not have the permission required to call the API. | 521|202 | Permission verification failed. A non-system application calls a system API. | 522|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 523|801 | Capability not supported. Failed to call ${geoLocationManager.setMockedLocations} due to limited device capabilities. | 524|3301000 | The location service is unavailable. | 525|3301100 | The location switch is off.| 526 527**示例** 528 529 ```ts 530 import { geoLocationManager } from '@kit.LocationKit'; 531 let locations:Array<geoLocationManager.Location> = [ 532 {"latitude": 30.12, "longitude": 120.11, "altitude": 123, "accuracy": 1, "speed": 5.2, "timeStamp": 16594326109, "direction": 123.11, "timeSinceBoot": 1000000000, "additionSize": 0, "isFromMock": true}, 533 {"latitude": 31.13, "longitude": 121.11, "altitude": 123, "accuracy": 2, "speed": 5.2, "timeStamp": 16594326109, "direction": 123.11, "timeSinceBoot": 2000000000, "additionSize": 0, "isFromMock": true}, 534 {"latitude": 32.14, "longitude": 122.11, "altitude": 123, "accuracy": 3, "speed": 5.2, "timeStamp": 16594326109, "direction": 123.11, "timeSinceBoot": 3000000000, "additionSize": 0, "isFromMock": true}, 535 {"latitude": 33.15, "longitude": 123.11, "altitude": 123, "accuracy": 4, "speed": 5.2, "timeStamp": 16594326109, "direction": 123.11, "timeSinceBoot": 4000000000, "additionSize": 0, "isFromMock": true}, 536 {"latitude": 34.16, "longitude": 124.11, "altitude": 123, "accuracy": 5, "speed": 5.2, "timeStamp": 16594326109, "direction": 123.11, "timeSinceBoot": 5000000000, "additionSize": 0, "isFromMock": true} 537 ]; 538 let config:geoLocationManager.LocationMockConfig = {"timeInterval": 5, "locations": locations}; 539 try { 540 geoLocationManager.enableLocationMock(); 541 geoLocationManager.setMockedLocations(config); 542 } catch (err) { 543 console.error("errCode:" + err.code + ", message:" + err.message); 544 } 545 ``` 546 547 548## geoLocationManager.enableReverseGeocodingMock 549 550enableReverseGeocodingMock(): void 551 552使能逆地理编码模拟功能。 553 554**系统能力**：SystemCapability.Location.Location.Core 555 556**系统API**：此接口为系统接口。 557 558**需要权限**: ohos.permission.MOCK_LOCATION 559 560**错误码**： 561 562以下错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 563 564| 错误码ID | 错误信息 | 565| -------- | ---------------------------------------- | 566|201 | Permission verification failed. The application does not have the permission required to call the API. | 567|202 | Permission verification failed. A non-system application calls a system API. | 568|801 | Capability not supported. Failed to call ${geoLocationManager.enableReverseGeocodingMock} due to limited device capabilities. | 569|3301000 | The location service is unavailable. | 570 571**示例** 572 573 ```ts 574 import { geoLocationManager } from '@kit.LocationKit'; 575 try { 576 geoLocationManager.enableReverseGeocodingMock(); 577 } catch (err) { 578 console.error("errCode:" + err.code + ", message:" + err.message); 579 } 580 ``` 581 582 583## geoLocationManager.disableReverseGeocodingMock 584 585disableReverseGeocodingMock(): void 586 587去使能逆地理编码模拟功能。 588 589**系统能力**：SystemCapability.Location.Location.Core 590 591**系统API**：此接口为系统接口。 592 593**需要权限**: ohos.permission.MOCK_LOCATION 594 595**错误码**： 596 597以下错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 598 599| 错误码ID | 错误信息 | 600| -------- | ---------------------------------------- | 601|201 | Permission verification failed. The application does not have the permission required to call the API. | 602|202 | Permission verification failed. A non-system application calls a system API. | 603|801 | Capability not supported. Failed to call ${geoLocationManager.disableReverseGeocodingMock} due to limited device capabilities. | 604|3301000 | The location service is unavailable. | 605 606**示例** 607 608 ```ts 609 import { geoLocationManager } from '@kit.LocationKit'; 610 try { 611 geoLocationManager.disableReverseGeocodingMock(); 612 } catch (err) { 613 console.error("errCode:" + err.code + ", message:" + err.message); 614 } 615 ``` 616 617 618## geoLocationManager.setReverseGeocodingMockInfo 619 620setReverseGeocodingMockInfo(mockInfos: Array<ReverseGeocodingMockInfo>): void 621 622设置逆地理编码模拟功能的配置信息，包含了位置和地名的对应关系，后续进行逆地理编码查询时如果位置信息位于配置信息中，就返回对应的地名。 623 624该接口需要在调用[geoLocationManager.enableReverseGeocodingMock](#geolocationmanagerenablereversegeocodingmock)之后才能调用。 625 626**系统能力**：SystemCapability.Location.Location.Core 627 628**系统API**：此接口为系统接口。 629 630**需要权限**: ohos.permission.MOCK_LOCATION 631 632**参数**： 633 634 | 参数名 | 类型 | 必填 | 说明 | 635 | -------- | -------- | -------- | -------- | 636 | mockInfos | Array<[ReverseGeocodingMockInfo](#reversegeocodingmockinfo)> | 是 | 指示逆地理编码模拟功能的配置参数数组。逆地理编码模拟功能的配置参数包含了一个位置和一个地名。 | 637 638**错误码**： 639 640以下错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 641 642| 错误码ID | 错误信息 | 643| -------- | ---------------------------------------- | 644|201 | Permission verification failed. The application does not have the permission required to call the API. | 645|202 | Permission verification failed. A non-system application calls a system API. | 646|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 647|801 | Capability not supported. Failed to call ${geoLocationManager.setReverseGeocodingMockInfo} due to limited device capabilities. | 648|3301000 | The location service is unavailable. | 649 650**示例** 651 652 ```ts 653 import { geoLocationManager } from '@kit.LocationKit'; 654 let mockInfos:Array<geoLocationManager.ReverseGeocodingMockInfo> = [ 655 {"location": {"locale": "zh", "latitude": 30.12, "longitude": 120.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 30.12, "longitude": 120.11, "isFromMock": true}}, 656 {"location": {"locale": "zh", "latitude": 31.12, "longitude": 121.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 31.12, "longitude": 121.11, "isFromMock": true}}, 657 {"location": {"locale": "zh", "latitude": 32.12, "longitude": 122.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 32.12, "longitude": 122.11, "isFromMock": true}}, 658 {"location": {"locale": "zh", "latitude": 33.12, "longitude": 123.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 33.12, "longitude": 123.11, "isFromMock": true}}, 659 {"location": {"locale": "zh", "latitude": 34.12, "longitude": 124.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 34.12, "longitude": 124.11, "isFromMock": true}}, 660 ]; 661 try { 662 geoLocationManager.enableReverseGeocodingMock(); 663 geoLocationManager.setReverseGeocodingMockInfo(mockInfos); 664 } catch (err) { 665 console.error("errCode:" + err.code + ", message:" + err.message); 666 } 667 ``` 668 669 670## geoLocationManager.isLocationPrivacyConfirmed 671 672isLocationPrivacyConfirmed(type: LocationPrivacyType): boolean 673 674查询用户是否同意定位服务隐私申明，是否同意启用定位服务。只有系统应用才能调用。 675 676**系统API**：此接口为系统接口。 677 678**系统能力**：SystemCapability.Location.Location.Core 679 680**参数**： 681 682 | 参数名 | 类型 | 必填 | 说明 | 683 | -------- | -------- | -------- | -------- | 684 | type | [LocationPrivacyType](#locationprivacytype)| 是 | 指定隐私申明场景，例如开机向导中的隐私申明、开启网络定位功能时弹出的隐私申明等。 | 685 686**返回值**： 687 688 | 类型 | 说明 | 689 | -------- | -------- | 690 | boolean | true：用户同意定位服务隐私申明。<br/>false：用户不同意定位服务隐私申明。 | 691 692**错误码**： 693 694以下错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 695 696| 错误码ID | 错误信息 | 697| -------- | ---------------------------------------- | 698|202 | Permission verification failed. A non-system application calls a system API. | 699|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 700|801 | Capability not supported. Failed to call ${geoLocationManager.isLocationPrivacyConfirmed} due to limited device capabilities. | 701|3301000 | The location service is unavailable. | 702 703**示例** 704 705 ```ts 706 import { geoLocationManager } from '@kit.LocationKit'; 707 try { 708 let isConfirmed = geoLocationManager.isLocationPrivacyConfirmed(1); 709 } catch (err) { 710 console.error("errCode:" + err.code + ", message:" + err.message); 711 } 712 ``` 713 714 715## geoLocationManager.setLocationPrivacyConfirmStatus 716 717setLocationPrivacyConfirmStatus(type: LocationPrivacyType, isConfirmed: boolean): void 718 719设置用户勾选定位服务隐私申明的状态，记录用户是否同意启用定位服务。只有系统应用才能调用。 720 721**系统API**：此接口为系统接口。 722 723**需要权限**：ohos.permission.MANAGE_SECURE_SETTINGS 724 725**系统能力**：SystemCapability.Location.Location.Core 726 727**参数**： 728 729 | 参数名 | 类型 | 必填 | 说明 | 730 | -------- | -------- | -------- | -------- | 731 | type | [LocationPrivacyType](#locationprivacytype) | 是 | 指定隐私申明场景，例如开机向导中的隐私申明、开启网络定位功能时弹出的隐私申明等。 | 732 | isConfirmed | boolean | 是 | true：用户同意定位服务隐私申明。<br/>false：用户不同意定位服务隐私申明。 | 733 734**错误码**： 735 736以下错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 737 738| 错误码ID | 错误信息 | 739| -------- | ---------------------------------------- | 740|201 | Permission verification failed. The application does not have the permission required to call the API. | 741|202 | Permission verification failed. A non-system application calls a system API. | 742|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 743|801 | Capability not supported. Failed to call ${geoLocationManager.setLocationPrivacyConfirmStatus} due to limited device capabilities. | 744|3301000 | The location service is unavailable. | 745 746**示例** 747 748 ```ts 749 import { geoLocationManager } from '@kit.LocationKit'; 750 try { 751 geoLocationManager.setLocationPrivacyConfirmStatus(1, true); 752 } catch (err) { 753 console.error("errCode:" + err.code + ", message:" + err.message); 754 } 755 ``` 756 757 758## geoLocationManager.getLocatingRequiredData<sup>10+</sup> 759 760getLocatingRequiredData(config: LocatingRequiredDataConfig): Promise<Array<LocatingRequiredData>> 761 762单次获取定位业务所需数据，包含WiFi蓝牙扫描信息，使用Promise方式异步返回结果。 763 764**需要权限**：ohos.permission.LOCATION 和 ohos.permission.APPROXIMATELY_LOCATION 765 766**系统能力**：SystemCapability.Location.Location.Core 767 768**系统API**：此接口为系统接口。 769 770**参数**： 771 772 | 参数名 | 类型 | 必填 | 说明 | 773 | -------- | -------- | -------- | -------- | 774 | config | [LocatingRequiredDataConfig](#locatingrequireddataconfig10) | 是 | 表示获取定位所需数据时的配置参数。 | 775 776**返回值**： 777 778 | 类型 | 说明 | 779 | -------- | -------- | 780 | Promise<Array<[LocatingRequiredData](#locatingrequireddata10)>> | 以Promise形式返回定位业务所需数据，包含WiFi蓝牙扫描信息。 | 781 782**错误码**： 783 784以下错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 785 786| 错误码ID | 错误信息 | 787| -------- | ---------------------------------------- | 788|201 | Permission verification failed. The application does not have the permission required to call the API. | 789|202 | Permission verification failed. A non-system application calls a system API. | 790|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 791|801 | Capability not supported. Failed to call ${geoLocationManager.getLocatingRequiredData} due to limited device capabilities. | 792|3301800 | Failed to start WiFi or Bluetooth scanning. | 793 794**示例** 795 796 ```ts 797 import { geoLocationManager } from '@kit.LocationKit'; 798 import { BusinessError } from '@kit.BasicServicesKit'; 799 let config:geoLocationManager.LocatingRequiredDataConfig = {'type': 1, 'needStartScan': true, 'scanInterval': 10000}; 800 try { 801 geoLocationManager.getLocatingRequiredData(config).then((result) => { 802 console.info('getLocatingRequiredData return: ' + JSON.stringify(result)); 803 }) 804 .catch((error:BusinessError) => { 805 console.error('promise, getLocatingRequiredData: error=' + JSON.stringify(error)); 806 }); 807 } catch (err) { 808 console.error("errCode:" + err.code + ", message:" + err.message); 809 } 810 ``` 811 812 813## geoLocationManager.on('locationIconStatusChange')<sup>12+</sup> 814 815on(type: 'locationIconStatusChange', callback: Callback<LocationIconStatus>): void 816 817订阅定位图标状态变化。使用callback异步回调。 818 819**系统能力**：SystemCapability.Location.Location.Core 820 821**系统API**：此接口为系统接口。 822 823**参数**： 824 825 | 参数名 | 类型 | 必填 | 说明 | 826 | -------- | -------- | -------- | -------- | 827 | type | string | 是 | 设置事件类型。type为“locationIconStatusChange”，表示订阅定位图标状态变化。 | 828 | callback | Callback<[LocationIconStatus](#locationiconstatus12)> | 是 | 回调函数，返回定位图标状态。 | 829 830**错误码**： 831 832以下错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 833 834| 错误码ID | 错误信息 | 835| -------- | ---------------------------------------- | 836|202 | Permission verification failed. A non-system application calls a system API. | 837|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 838|801 | Capability not supported. Failed to call ${geoLocationManager.on('locationIconStatusChange')} due to limited device capabilities. | 839|3301000 | The location service is unavailable. | 840 841**示例** 842 843 ```ts 844 import { geoLocationManager } from '@kit.LocationKit'; 845 let callback = (code: geoLocationManager.LocationIconStatus):void => { 846 console.info('LocationIconStatus: ' + JSON.stringify(code)); 847 } 848 try { 849 geoLocationManager.on('locationIconStatusChange', callback); 850 } catch (err) { 851 console.error("errCode:" + err.code + ", message:" + err.message); 852 } 853 ``` 854 855 856## geoLocationManager.off('locationIconStatusChange')<sup>12+</sup> 857 858off(type: 'locationIconStatusChange', callback?: Callback<LocationIconStatus>): void 859 860取消订阅定位图标状态的变化。 861 862**系统能力**：SystemCapability.Location.Location.Core 863 864**系统API**：此接口为系统接口。 865 866**参数**： 867 868 | 参数名 | 类型 | 必填 | 说明 | 869 | -------- | -------- | -------- | -------- | 870 | type | string | 是 | 设置事件类型。type为“locationIconStatusChange”，表示取消订阅定位图标状态变化。 | 871 | callback | Callback<[LocationIconStatus](#locationiconstatus12)> | 否 | 需要取消订阅的回调函数。该回调函数需要与on接口传入的回调函数保持一致。若无此参数，则取消当前类型的所有订阅。 | 872 873**错误码**： 874 875错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 876 877| 错误码ID | 错误信息 | 878| -------- | ---------------------------------------- | 879|202 | Permission verification failed. A non-system application calls a system API. | 880|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 881|801 | Capability not supported. Failed to call ${geoLocationManager.off('locationIconStatusChange')} due to limited device capabilities. | 882|3301000 | The location service is unavailable. | 883 884**示例** 885 886 ```ts 887 import { geoLocationManager } from '@kit.LocationKit'; 888 let callback = (code: geoLocationManager.LocationIconStatus):void => { 889 console.info('LocationIconStatus: ' + JSON.stringify(code)); 890 } 891 try { 892 geoLocationManager.on('locationIconStatusChange', callback); 893 geoLocationManager.off('locationIconStatusChange', callback); 894 } catch (err) { 895 console.error("errCode:" + err.code + ", message:" + err.message); 896 } 897 ``` 898 899 900## geoLocationManager.getLocationIconStatus<sup>12+</sup> 901 902getLocationIconStatus(): LocationIconStatus 903 904获取当前的定位图标状态。 905 906**系统能力**：SystemCapability.Location.Location.Core 907 908**系统API**：此接口为系统接口。 909 910**返回值**： 911 912 | 类型 | 说明 | 913 | -------- | -------- | 914 | [LocationIconStatus](#locationiconstatus12) | 返回定位图标状态。 | 915 916**错误码**： 917 918以下错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 919 920| 错误码ID | 错误信息 | 921| -------- | ---------------------------------------- | 922|202 | Permission verification failed. A non-system application calls a system API. | 923|801 | Capability not supported. Failed to call ${geoLocationManager.getLocationIconStatus} due to limited device capabilities. | 924|3301000 | The location service is unavailable. | 925 926**示例** 927 928 ```ts 929 import { geoLocationManager } from '@kit.LocationKit'; 930 try { 931 let iconStatus = geoLocationManager.getLocationIconStatus(); 932 } catch (err) { 933 console.error("errCode:" + err.code + ", message:" + err.message); 934 } 935 ``` 936 937 938## geoLocationManager.enableLocationByUserId<sup>18+</sup> 939 940enableLocationByUserId(userId: number): Promise<void> 941 942打开指定系统账号的定位开关，使用Promise异步回调。 943 944**系统API**：此接口为系统接口。 945 946**需要权限**：ohos.permission.MANAGE_SECURE_SETTINGS 和 ohos.permission.CONTROL_LOCATION_SWITCH 947 948**系统能力**：SystemCapability.Location.Location.Core 949 950**参数**： 951 952 | 参数名 | 类型 | 必填 | 说明 | 953 | -------- | -------- | -------- | -------- | 954 | userId | number | 是 | 系统账号ID，获取系统账号ID可参考[查询所有已创建的系统账号](../../basic-services/account/manage-os-account.md#查询所有已创建的系统账号)| 955 956**返回值**： 957 958 | 类型 | 说明 | 959 | -------- | -------- | 960 | Promise<void> | Promise对象。无返回结果的Promise对象 | 961 962**错误码**： 963 964以下错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 965 966| 错误码ID | 错误信息 | 967| -------- | ---------------------------------------- | 968|201 | Permission verification failed. The application does not have the permission required to call the API. | 969|202 | Permission verification failed. A non-system application calls a system API. | 970|801 | Capability not supported. Failed to call ${geoLocationManager.enableLocationByUserId} due to limited device capabilities. | 971|3301000 | The location service is unavailable. | 972 973**示例** 974 975 ```ts 976 import { geoLocationManager } from '@kit.LocationKit'; 977 import { BusinessError } from '@kit.BasicServicesKit'; 978 try { 979 // 打开指定系统账号的位置开关，如：处于ID为101的账号下，可以打开ID为100的账号的位置开关 980 let userId:number = 100; 981 geoLocationManager.enableLocationByUserId(userId).then(() => { 982 console.info('promise, enableLocationByUserId succeed'); 983 }) 984 .catch((error:BusinessError) => { 985 console.error('promise, enableLocationByUserId: error=' + JSON.stringify(error)); 986 }); 987 } catch (err) { 988 console.error("errCode:" + err.code + ", message:" + err.message); 989 } 990 ``` 991 992 993## geoLocationManager.disableLocationByUserId<sup>18+</sup> 994 995disableLocationByUserId(userId: number): void 996 997关闭指定系统账号的定位开关。 998 999**系统API**：此接口为系统接口。 1000 1001**需要权限**：ohos.permission.MANAGE_SECURE_SETTINGS 和 ohos.permission.CONTROL_LOCATION_SWITCH 1002 1003**系统能力**：SystemCapability.Location.Location.Core 1004 1005**参数**： 1006 1007 | 参数名 | 类型 | 必填 | 说明 | 1008 | -------- | -------- | -------- | -------- | 1009 | userId | number | 是 | 系统账号ID，获取系统账号ID可参考[查询所有已创建的系统账号](../../basic-services/account/manage-os-account.md#查询所有已创建的系统账号)| 1010 1011**错误码**： 1012 1013以下错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 1014 1015| 错误码ID | 错误信息 | 1016| -------- | ---------------------------------------- | 1017|201 | Permission verification failed. The application does not have the permission required to call the API. | 1018|202 | Permission verification failed. A non-system application calls a system API. | 1019|801 | Capability not supported. Failed to call ${geoLocationManager.disableLocationByUserId} due to limited device capabilities. | 1020|3301000 | The location service is unavailable. | 1021 1022**示例** 1023 1024 ```ts 1025 import { geoLocationManager } from '@kit.LocationKit'; 1026 try { 1027 // 关闭指定系统账号的位置开关，如：处于ID为101的账号下，可以关闭ID为100的账号的位置开关 1028 let userId:number = 100; 1029 geoLocationManager.disableLocationByUserId(userId); 1030 } catch (err) { 1031 console.error("errCode:" + err.code + ", message:" + err.message); 1032 } 1033 ``` 1034 1035 1036## geoLocationManager.isLocationEnabledByUserId<sup>18+</sup> 1037 1038isLocationEnabledByUserId(userId: number): boolean 1039 1040判断指定系统账号的位置开关是否开启。 1041 1042**系统API**：此接口为系统接口。 1043 1044**系统能力**：SystemCapability.Location.Location.Core 1045 1046**参数**： 1047 1048 | 参数名 | 类型 | 必填 | 说明 | 1049 | -------- | -------- | -------- | -------- | 1050 | userId | number | 是 | 系统账号ID，获取系统账号ID可参考 [查询所有已创建的系统账号](../../basic-services/account/manage-os-account.md#查询所有已创建的系统账号)| 1051 1052**返回值**： 1053 1054 | 类型 | 说明 | 1055 | -------- | -------- | 1056 | boolean | true：位置信息开关已开启。<br/>false：位置信息开关已关闭。 | 1057 1058**错误码**： 1059 1060以下错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 1061 1062| 错误码ID | 错误信息 | 1063| -------- | ---------------------------------------- | 1064|202 | Permission verification failed. A non-system application calls a system API. | 1065|801 | Capability not supported. Failed to call ${geoLocationManager.isLocationEnabled} due to limited device capabilities. | 1066|3301000 | The location service is unavailable. | 1067 1068**示例** 1069 1070 ```ts 1071 import { geoLocationManager } from '@kit.LocationKit'; 1072 try { 1073 // 查询指定系统账号的位置开关状态，如：处于ID为101的账号下，可以查询ID为100的账号的位置开关状态 1074 let userId:number = 100; 1075 let locationEnabled = geoLocationManager.isLocationEnabledByUserId(userId); 1076 } catch (err) { 1077 console.error("errCode:" + err.code + ", message:" + err.message); 1078 } 1079 ``` 1080 1081 1082## geoLocationManager.setLocationSwitchIgnored<sup>18+</sup> 1083 1084setLocationSwitchIgnored(isIgnored: boolean): void 1085 1086设置应用获取位置信息是否受位置开关控制。 1087 1088设置为true后，允许应用在位置开关关闭的场景获取到位置信息，有效时间为从调用接口成功开始的两分钟。 1089 1090**系统API**：此接口为系统接口。 1091 1092**需要权限**：ohos.permission.LOCATION_SWITCH_IGNORED 1093 1094**系统能力**：SystemCapability.Location.Location.Core 1095 1096**参数**： 1097 1098 | 参数名 | 类型 | 必填 | 说明 | 1099 | -------- | -------- | -------- | -------- | 1100 | isIgnored | boolean | 是 | true：需要在位置开关关闭的场景下获取位置信息。有效时间为从调用接口成功开始的两分钟。<br/>false：不需要在位置开关关闭的场景下获取位置信息。| 1101 1102**错误码**： 1103 1104以下错误码的详细介绍请参见[位置服务子系统错误码](errorcode-geoLocationManager.md)。 1105 1106| 错误码ID | 错误信息 | 1107| -------- | ---------------------------------------- | 1108|201 | Permission verification failed. The application does not have the permission required to call the API. | 1109|202 | Permission verification failed. A non-system application calls a system API. | 1110|801 | Capability not supported. Failed to call ${geoLocationManager.disableLocationByUserId} due to limited device capabilities. | 1111|3301000 | The location service is unavailable. | 1112 1113**示例** 1114 1115 ```ts 1116 import { geoLocationManager } from '@kit.LocationKit'; 1117 try { 1118 let isIgnored:boolean = true; 1119 geoLocationManager.setLocationSwitchIgnored(isIgnored); 1120 } catch (err) { 1121 console.error("errCode:" + err.code + ", message:" + err.message); 1122 } 1123 ```