# sceneMap（场景化控件）

> phone 5.0.0(12)+ | 2in1 5.0.1(13)+ | tablet 5.0.0(12)+

本模块提供地图场景化控件功能，包括地点详情展示控件、地点选取控件和区划选择控件。

**起始版本：** 4.1.0(11)

## 导入模块

```typescript
import { sceneMap } from '@kit.MapKit';
```

## queryLocation

queryLocation(context: common.UIAbilityContext, options: LocationQueryOptions): Promise<void>

根据提供的参数拉起地点详情展示控件。使用Promise异步回调。
> 说明
>
> * 此函数必须在ArkUI页面上下文中调用。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**设备行为差异：** 该接口在phone、tablet和PC/2in1设备上可以正常使用，在其他设备中返回801错误码。

**起始版本：** 4.1.0(11)

**参数：**

|**参数名**|**类型**|必填|**说明**|
|:------|:--------------------------------------------------------------------------------------------------------------------------------------|:-|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|context|common.[UIAbilityContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-inner-application-uiabilitycontext)|是|[UIAbility](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-app-ability-uiability)或[UIExtensionAbility](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-app-ability-uiextensionability)所对应的context。|
|options|[LocationQueryOptions](#locationqueryoptions)|是|查询地点详情参数。|

**返回值：**

|类型|说明|
|:------------|:-------------------------|
|Promise<void>|Promise对象。无返回结果的Promise对象。|

**错误码：**

以下错误码的详细介绍请参见[ArkTS API错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-map)。

|错误码ID|错误信息|
|:---------|:---------------------------------------------------------------------------------------------------|
|401|Invalid input parameter.|
|1002600001|System internal error.|
|1002600002|Failed to connect to the Map Kit server.|
|1002600003|App authentication failed.|
|1002600004|The Map permission is not enabled.|
|801|Capability not supported. Failed to call the API due to limited device capabilities. 适用版本：5.1.0(18)+|

**示例：**

```typescript
import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let queryLocationOptions: sceneMap.LocationQueryOptions = { siteId: "922207154068557824" };
sceneMap.queryLocation(this.getUIContext().getHostContext() as common.UIAbilityContext, queryLocationOptions)
  .then(() => {
    console.info("QueryLocation", "Succeeded in querying location.");
  })
  .catch((err: BusinessError) => {
    console.error("QueryLocation", `Failed to query Location, code: ${err.code}, message: ${err.message}`);
  });
```

## chooseLocation

chooseLocation(context: common.UIAbilityContext, options: LocationChoosingOptions): Promise<LocationChoosingResult>

根据提供的参数拉起地点选取控件。使用Promise异步回调。
> 说明
>
> * 此函数必须在ArkUI页面上下文中调用。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**设备行为差异：** 该接口在phone、tablet和PC/2in1设备上可以正常使用，在其他设备中返回801错误码。

**起始版本：** 4.1.0(11)

**参数：**

|**参数名**|**类型**|必填|**说明**|
|:------|:--------------------------------------------------------------------------------------------------------------------------------------|:-|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|context|common.[UIAbilityContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-inner-application-uiabilitycontext)|是|[UIAbility](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-app-ability-uiability)或[UIExtensionAbility](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-app-ability-uiextensionability)所对应的context。|
|options|[LocationChoosingOptions](#locationchoosingoptions)|是|地点选取参数。|

**返回值：**

|类型|说明|
|:---------------------------------------------------------|:-------------------------------------------------------------|
|Promise<[LocationChoosingResult](#locationchoosingresult)>|Promise对象，返回[LocationChoosingResult](#locationchoosingresult)。|

**错误码：**

以下错误码的详细介绍请参见[ArkTS API错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-map)。

|错误码ID|错误信息|
|:---------|:---------------------------------------------------------------------------------------------------|
|401|Invalid input parameter.|
|1002600001|System internal error.|
|1002600002|Failed to connect to the Map Kit server.|
|1002600003|App authentication failed.|
|1002600004|The Map permission is not enabled.|
|801|Capability not supported. Failed to call the API due to limited device capabilities. 适用版本：5.1.0(18)+|

**示例：**

```typescript
import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let locationChoosingOptions: sceneMap.LocationChoosingOptions = {
  location: { latitude: 39.92194051376904, longitude: 116.3971836796932 },
  searchEnabled: true,
  showNearbyPoi: true
};
sceneMap.chooseLocation(this.getUIContext().getHostContext() as common.UIAbilityContext, locationChoosingOptions)
  .then((data) => {
    console.info("ChooseLocation", "Succeeded in choosing location.");
  })
  .catch((err: BusinessError) => {
    console.error("ChooseLocation", `Failed to choose Location, code: ${err.code}, message: ${err.message}`);
  });
```

## selectDistrict

selectDistrict(context: common.Context, options: DistrictSelectOptions): Promise<DistrictSelectResult>

根据提供的参数调出区划选择页面。使用Promise异步回调。
> 说明
>
> * 此函数必须在ArkUI页面上下文中调用。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**设备行为差异：** 该接口在phone、tablet和PC/2in1设备上可以正常使用，在其他设备中返回801错误码。

**起始版本：** 5.0.0(12)

**参数：**

|**参数名**|**类型**|必填|**说明**|
|:------|:--------------------------------------------------------------------------------------------------------------------|:-|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|context|[common.Context](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-inner-application-context)|是|[UIAbility](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-app-ability-uiability)或[UIExtensionAbility](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-app-ability-uiextensionability)所对应的context。|
|options|[DistrictSelectOptions](#districtselectoptions)|是|区划选择页面初始选项。|

**返回值：**

|类型|说明|
|:-----------------------------------------------------|:---------------------------------------------------------|
|Promise<[DistrictSelectResult](#districtselectresult)>|Promise对象，返回[DistrictSelectResult](#districtselectresult)。|

**错误码：**

以下错误码的详细介绍请参见[ArkTS API错误码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-map)。

|错误码ID|错误信息|
|:---------|:---------------------------------------------------------------------------------------------------|
|401|Invalid input parameter.|
|1002600001|System internal error.|
|1002600002|Failed to connect to the Map Kit server.|
|1002600003|App authentication failed.|
|1002600004|The Map permission is not enabled.|
|1002600012|The country code is not supported.|
|801|Capability not supported. Failed to call the API due to limited device capabilities. 适用版本：5.1.0(18)+|

**示例：**

```typescript
import { BusinessError } from '@kit.BasicServicesKit';

let districtSelectOptions: sceneMap.DistrictSelectOptions = {
  countryCode: "CN"
};
sceneMap.selectDistrict(this.getUIContext().getHostContext(), districtSelectOptions).then((data) => {
  console.info("SelectDistrict", "Succeeded in selecting district.");
}).catch((err: BusinessError) => {
  console.error("SelectDistrict", `Failed to select district, code: ${err.code}, message: ${err.message}`);
});
```

## LocationQueryOptions

查询地点详情的参数。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.Map.Core

**设备行为差异：** 该接口在phone、tablet和PC/2in1设备上可以正常使用，在其他设备中返回801错误码。

**起始版本：** 4.1.0(11)

|**名称**|**类型**|只读|可选|**说明**|
|:-----------------|:-----------------------------------------------------------------------------------------------------------------|:-|:-|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|siteId|string|否|是|地点详情页的地点ID，异常值返回401错误码。 siteId可通过[MapEventManager](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-map-mapeventmanager)中[on](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-map-mapeventmanager#onpoiclick)(type: 'poiClick', callback: Callback<[mapCommon.Poi](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-common#poi)>)方法获取。 **元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。|
|language|string|否|是|语言，请参见[地图Picker支持语言](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/map-language#地图picker支持语言)，如果未设置，默认使用系统语言。异常值按默认值处理。 **元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。|
|location|[mapCommon.LatLng](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-common#latlng)|否|是|地图中心点坐标。如果没有siteId，使用location查询地点详情。 **元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。|
|name|string|否|是|地点的名称。如果没有siteId，使用name作为location的名称标注。 **元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。|
|address|string|否|是|地点的地址。如果没有siteId，使用address作为location的地址标注。 **元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。|
|showBusiness|boolean|否|是|是否显示商业信息（如打车），默认值为true。 - true：显示 - false：不显示 **元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。 **说明：** 版本4.1.0(11)~5.1.1(19)为预留字段，从版本6.0.0(20)开始使用。|
|themeColor|[CustomColors](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-theme#customcolors)|否|是|自定义主题颜色对象，默认为brand（品牌色）。 **起始版本：** 5.0.3(15) **元服务API：** 从版本5.0.3(15)开始，该接口支持在元服务中使用。|
|cancelCallback|Callback<void>|否|是|回调函数，无返回结果。地点详情控件关闭事件回调。 **起始版本：** 5.0.3(15) **元服务API：** 从版本5.0.3(15)开始，该接口支持在元服务中使用。|
|transitionDuration|number|否|是|转场动效时间，默认值：-1，单位：ms，取值范围：大于0，异常值将按照默认值-1处理，保持[interpolatingSpring](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-curve#curvesinterpolatingspring10)(0.5, 1, 328, 36)（初始速度为0.5，质量为1，刚度为1，阻尼为1）。PC/2in1设备当前不显示转场动效，该配置不生效。 **起始版本：** 6.0.2(22) **元服务API：** 从版本6.0.2(22)开始，该接口支持在元服务中使用。|

> 说明
>
> 以下两组参数，至少传入其中一组，如果都传入，以siteId为主。
>
> * siteId
>
> * location、name

**示例：**

```typescript
let queryLocationOptions: sceneMap.LocationQueryOptions = { siteId: "922207154068557824" };
```

## LocationChoosingOptions

地点选取的参数。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.Map.Core

**设备行为差异：** 该接口在phone、tablet和PC/2in1设备上可以正常使用，在其他设备中返回801错误码。

**起始版本：** 4.1.0(11)

|**名称**|**类型**|只读|可选|**说明**|
|:-----------------|:-----------------------------------------------------------------------------------------------------------------|:-|:-|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|location|[mapCommon.LatLng](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-common#latlng)|否|是|地图中心点坐标。 如果参数未传，使用设备当前位置作为中心点；如果未获取到设备当前位置，默认以故宫博物院为中心点。 **元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。|
|language|string|否|是|语言，请参见[地图Picker支持语言](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/map-language#地图picker支持语言)，如果未设置，默认使用系统语言。异常值按默认值处理。 **元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。|
|poiTypes|Array<string>|否|是|指定需要展示的POI类别。取值范围参见[HwLocationType](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-poi#hwlocationtype)。 **元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。|
|searchEnabled|boolean|否|是|是否展示搜索控件，默认值为false，异常值按默认值处理。 - true：展示 - false：不展示 **元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。|
|showNearbyPoi|boolean|否|是|是否展示附近POI，默认值为false，异常值按默认值处理。 - true：展示 - false：不展示 **元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。|
|snapshotEnabled|boolean|否|是|是否返回映射快照，默认值为false。 - true：返回 - false：不返回 **起始版本：** 5.0.0(12) **元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。|
|themeColor|[CustomColors](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-theme#customcolors)|否|是|自定义主题颜色对象，默认为brand（品牌色）。 **起始版本：** 5.0.3(15) **元服务API：** 从版本5.0.3(15)开始，该接口支持在元服务中使用。|
|cancelCallback|Callback<void>|否|是|回调函数，无返回结果。地点选取控件关闭事件回调。 **起始版本：** 5.0.3(15) **元服务API：** 从版本5.0.3(15)开始，该接口支持在元服务中使用。|
|transitionDuration|number|否|是|转场动效时间，默认值：-1，单位：ms，取值范围：大于0，异常值将按照默认值-1处理，保持[interpolatingSpring](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-curve#curvesinterpolatingspring10)(0.5, 1, 328, 36)（初始速度为0.5，质量为1，刚度为1，阻尼为1）。PC/2in1设备当前不显示转场动效，该配置不生效。 **起始版本：** 6.0.2(22) **元服务API：** 从版本6.0.2(22)开始，该接口支持在元服务中使用。|

**示例：**

```typescript
let locationChoosingOptions: sceneMap.LocationChoosingOptions = {
  location: { latitude: 39.9, longitude: 116.4 }
};
```

## LocationChoosingResult

地点选取的返回结果。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.Map.Core

**设备行为差异：** 该接口在phone、tablet和PC/2in1设备上可以正常使用，在其他设备中返回801错误码。

**起始版本：** 4.1.0(11)

|**名称**|**类型**|只读|可选|**说明**|
|:---------------|:-------------------------------------------------------------------------------------------------------------------|:-|:-|:--------------------------------------------------------------------------------------------|
|siteId|string|否|是|选点的地点ID。如果选点非POI，则不返回。 **元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。|
|location|[mapCommon.LatLng](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-common#latlng)|否|否|选点的坐标点。 **元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。|
|name|string|否|是|选点的POI名称。如果选点非POI，则返回的name值为"标记点"。 **元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。|
|address|string|否|否|选点地址。 **元服务API：** 从版本4.1.0(11)开始，该接口支持在元服务中使用。|
|addressComponent|[site.AddressComponent](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-site#addresscomponent)|否|是|选点地址的详细信息。 **起始版本：** 5.0.0(12) **元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。|
|zoom|number|否|否|选点地址的缩放层级，取值范围：[2, 20]，超出按边界值处理。 **起始版本：** 5.0.0(12) **元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。|
|snapshot|[image.PixelMap](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-image-pixelmap)|否|是|地图快照。 **起始版本：** 5.0.0(12) **元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。|

## DistrictSelectOptions

区划选择页面初始选项。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.Map.Core

**设备行为差异：** 该接口在phone、tablet和PC/2in1设备上可以正常使用，在其他设备中返回801错误码。

**起始版本：** 5.0.0(12)

|**名称**|**类型**|只读|可选|**说明**|
|:-----------------|:-----------------------------------------------------------------------------------------------------------------|:-|:-|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|countryCode|string|否|是|查询指定国家或地区的行政区划，国家或地区码必须符合ISO 3166-1 alpha-2规则。 **元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。|
|language|string|否|是|设置页面语言，请参见[地图Picker支持语言](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/map-language#地图picker支持语言)，如果未设置，默认使用系统语言。异常值按默认值处理。 **元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。|
|address|string|否|是|指定地址查询。 **元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。|
|themeColor|[CustomColors](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-theme#customcolors)|否|是|自定义主题颜色对象，默认为brand（品牌色）。 **起始版本：** 5.0.3(15) **元服务API：** 从版本5.0.3(15)开始，该接口支持在元服务中使用。|
|subWindowEnabled|boolean|否|是|是否在子窗口中显示区划选择，默认值为false。 - true：在子窗口中显示 - false：不在子窗口中显示 **起始版本：** 5.0.3(15) **元服务API：** 从版本5.0.3(15)开始，该接口支持在元服务中使用。|
|cancelCallback|Callback<void>|否|是|回调函数，无返回结果。区划选择控件关闭事件回调。 **起始版本：** 5.0.3(15) **元服务API：** 从版本5.0.3(15)开始，该接口支持在元服务中使用。|
|transitionDuration|number|否|是|转场动效时间，默认值：-1，单位：ms，取值范围：大于0，异常值将按照默认值-1处理，保持[interpolatingSpring](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-curve#curvesinterpolatingspring10)(0.5, 1, 328, 36)（初始速度为0.5，质量为1，刚度为1，阻尼为1）。当subWindowEnabled为true时该配置不生效。 **起始版本：** 6.0.2(22) **元服务API：** 从版本6.0.2(22)开始，该接口支持在元服务中使用。|
|maxAdminLevel|number|否|是|区划选择控件的最大显示层级。取值范围[1, 6]，仅支持整数，小数向下取整处理。默认值：6，异常值按默认值处理。 **起始版本：** 6.1.1(24) **元服务API：** 从版本6.1.1(24)开始，该接口支持在元服务中使用。 **说明：** 如果同时传入address和maxAdminLevel： - 当传入的address查询的结果为单一结果（无同名地区），则以address查询结果的优先，例如address为雨花台区（显示层级为4）、maxAdminLevel为2，区划选择控件的显示层级为4。 - 当传入的address查询的结果有多个结果（存在同名地区），例如address为大同（山西省大同市和黑龙江省大庆市大同区同名），优先使用maxAdminLevel。|

**示例：**

```typescript
let districtSelectOptions: sceneMap.DistrictSelectOptions = {
  countryCode: "CN",
  language:"zh",
  address: "河南",
  maxAdminLevel: 3
};
```

## DistrictSelectResult

区划选择请求的结果。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**设备行为差异：** 该接口在phone、tablet和PC/2in1设备上可以正常使用，在其他设备中返回801错误码。

**起始版本：** 5.0.0(12)

|**名称**|**类型**|只读|可选|**说明**|
|:-----------------|:---------------------------|:-|:-|:-------------|
|districts|Array<[District](#district)>|否|否|所选行政区划的级别信息。|
|addressDescription|string|否|是|返回所选行政区划的地址信息。|

## District

行政区划信息。

**模型约束：** 此接口仅可在Stage模型下使用。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.Map.Core

**设备行为差异：** 该接口在phone、tablet和PC/2in1设备上可以正常使用，在其他设备中返回801错误码。

**起始版本：** 5.0.0(12)

|**名称**|**类型**|只读|可选|**说明**|
|:----------|:------------------------------------------------------------------------------------------------------|:-|:-|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|siteId|string|否|是|区划的地点ID。|
|name|string|否|是|区划的名称。|
|location|[mapCommon.LatLng](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-common#latlng)|否|是|区划的坐标点|
|adminLevel|string|否|是|区划级别，分国家、省份、城市、区/县和街道五个区划级别。 **说明：** 国家：COUNTRY 省份：ADMINISTRATIVE_AREA_LEVEL_1 城市：ADMINISTRATIVE_AREA_LEVEL_2 区/县：ADMINISTRATIVE_AREA_LEVEL_3 街道：ADMINISTRATIVE_AREA_LEVEL_4|
|adminCode|string|否|是|[行政区划码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-citycode)。 **说明：** 接口返回的行政区划码覆盖中国大陆及港澳地区，包括省份、城市、区/县、乡镇/街道等层级，文档附录中仅提供部分城市行政区划码示例。|
|cityCode|string|否|是|[城市码](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-citycode)。|
|countryCode|string|否|是|国家/地区码。|