智能客服
你问我答，随时在线为你解决问题
- 此函数必须在ArkUI页面上下文中调用。
- 探索了解鸿蒙应用和多设备开发，学习如何构建应用/元服务应用形态HarmonyOS 应用One as All，All as One
元服务秒开直达 服务随行 无处不在
游戏为游戏创意玩法带来无限可能
多设备应用开发穿戴
折叠屏手机鸿蒙电脑开发者学堂视频课程Codelabs - 开发获取官方开发工具和文档等资源，将创意转化为鸿蒙应用开发工具DevEco Studio应用开发 IDE, AI Agent 和 CLI
小艺开放平台Skill 和智能体开发平台
ArkTS
ArKUI
AppGallery ConnectDevEco Testing开发资源工具下载示例代码开发文档最佳实践 - 分发通过华为应用市场发布你的应用，多渠道触达用户应用分发应用市场纯净安全的全场景应用分发平台
游戏中心
应用审核政策服务分发小艺HarmonyOS 的超级 AI 入口
智慧助手·今天
服务分发文档内容分发主题服务
内容分发文档 - 推广与变现一站式流量增长与营销变现平台推广应用推广引擎全链路应用推广与增长服务平台
鲸鸿动能广告为企业广告主提供广告营销服务
联运服务推广文档变现鲸鸿动能流量变现使能应用展示广告，实现流量变现应用内支付变现文档 - 生态合作携手伙伴共建共享鸿蒙智能终端生态伙伴 SDK一站式获取安全可靠的鸿蒙伙伴 SDK
生态服务鸿蒙应用开发、培训和人力服务
服务商伙伴中心华为终端云服务商伙伴的统一门户
伙伴入驻指南生态市场介绍，卖家和买家服务指引
廉洁政策合作伙伴诚信廉洁政策
- 支持获取客服帮助、技术支持、活动资讯等信息智能客服24小时 AI 在线自助服务，即问即答
社区问答在官方论坛提问，与开发者互动交流
在线提单提交工单，获得技术支持
开发者活动HDD 等线下活动速览及报名入口
资讯帮助指南
您当前正在浏览HarmonyOS最新文档，覆盖已发布的所有API版本，可在API参考中筛选您使用的API版本。详细的版本配套关系请参考版本说明。
sceneMap（场景化控件）
Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+
本文导读
本模块提供地图场景化控件功能，包括地点详情展示控件、地点选取控件和区划选择控件。
起始版本： 4.1.0(11)
导入模块
- import { sceneMap } from '@kit.MapKit';
queryLocation
Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+
queryLocation(context: common.UIAbilityContext, options: LocationQueryOptions): Promise<void>
根据提供的参数拉起地点详情展示控件。使用Promise异步回调。
说明
模型约束： 此接口仅可在Stage模型下使用。
元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Map.Core
设备行为差异： 该接口在phone、tablet和PC/2in1设备上可以正常使用，在其他设备中返回801错误码。
起始版本： 4.1.0(11)
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| context | common.UIAbilityContext | 是 | UIAbility或UIExtensionAbility所对应的context。 |
| options | LocationQueryOptions | 是 | 查询地点详情参数。 |
返回值：
| 类型 | 说明 |
|---|---|
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
错误码：
以下错误码的详细介绍请参见ArkTS API错误码。
| 错误码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)+ |
示例：
- 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
Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+
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 | 是 | UIAbility或UIExtensionAbility所对应的context。 |
| options | LocationChoosingOptions | 是 | 地点选取参数。 |
返回值：
| 类型 | 说明 |
|---|---|
| Promise<LocationChoosingResult> | Promise对象，返回LocationChoosingResult。 |
错误码：
以下错误码的详细介绍请参见ArkTS API错误码。
| 错误码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)+ |
示例：
- 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
Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+
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 | 是 | UIAbility或UIExtensionAbility所对应的context。 |
| options | DistrictSelectOptions | 是 | 区划选择页面初始选项。 |
返回值：
| 类型 | 说明 |
|---|---|
| Promise<DistrictSelectResult> | Promise对象，返回DistrictSelectResult。 |
错误码：
以下错误码的详细介绍请参见ArkTS API错误码。
| 错误码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)+ |
示例：
- 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
Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+
查询地点详情的参数。
模型约束： 此接口仅可在Stage模型下使用。
系统能力： SystemCapability.Map.Core
设备行为差异： 该接口在phone、tablet和PC/2in1设备上可以正常使用，在其他设备中返回801错误码。
起始版本： 4.1.0(11)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| siteId | string | 否 | 是 | 地点详情页的地点ID，异常值返回401错误码。 siteId可通过MapEventManager中on(type: 'poiClick', callback: Callback<mapCommon.Poi>)方法获取。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| language | string | 否 | 是 | 语言，请参见地图Picker支持语言，如果未设置，默认使用系统语言。异常值按默认值处理。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| location | mapCommon.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 | 否 | 是 | 自定义主题颜色对象，默认为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(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
示例：
- let queryLocationOptions: sceneMap.LocationQueryOptions = { siteId: "922207154068557824" };
LocationChoosingOptions
Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+
地点选取的参数。
模型约束： 此接口仅可在Stage模型下使用。
系统能力： SystemCapability.Map.Core
设备行为差异： 该接口在phone、tablet和PC/2in1设备上可以正常使用，在其他设备中返回801错误码。
起始版本： 4.1.0(11)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| location | mapCommon.LatLng | 否 | 是 | 地图中心点坐标。 如果参数未传，使用设备当前位置作为中心点；如果未获取到设备当前位置，默认以故宫博物院为中心点。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| language | string | 否 | 是 | 语言，请参见地图Picker支持语言，如果未设置，默认使用系统语言。异常值按默认值处理。 元服务API： 从版本4.1.0(11)开始，该接口支持在元服务中使用。 |
| poiTypes | Array<string> | 否 | 是 | 指定需要展示的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 | 否 | 是 | 自定义主题颜色对象，默认为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(0.5, 1, 328, 36)（初始速度为0.5，质量为1，刚度为1，阻尼为1）。PC/2in1设备当前不显示转场动效，该配置不生效。 起始版本： 6.0.2(22) 元服务API： 从版本6.0.2(22)开始，该接口支持在元服务中使用。 |
示例：
- let locationChoosingOptions: sceneMap.LocationChoosingOptions = {
- location: { latitude: 39.9, longitude: 116.4 }
- };
LocationChoosingResult
Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+
地点选取的返回结果。
模型约束： 此接口仅可在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 | 否 | 否 | 选点的坐标点。 元服务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 | 否 | 是 | 选点地址的详细信息。 起始版本： 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 | 否 | 是 | 地图快照。 起始版本： 5.0.0(12) 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。 |
DistrictSelectOptions
Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+
区划选择页面初始选项。
模型约束： 此接口仅可在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支持语言，如果未设置，默认使用系统语言。异常值按默认值处理。 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。 |
| address | string | 否 | 是 | 指定地址查询。 元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。 |
| themeColor | 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(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。 |
示例：
- let districtSelectOptions: sceneMap.DistrictSelectOptions = {
- countryCode: "CN",
- language:"zh",
- address: "河南",
- maxAdminLevel: 3
- };
DistrictSelectResult
Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+
区划选择请求的结果。
模型约束： 此接口仅可在Stage模型下使用。
元服务API： 从版本5.0.0(12)开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Map.Core
设备行为差异： 该接口在phone、tablet和PC/2in1设备上可以正常使用，在其他设备中返回801错误码。
起始版本： 5.0.0(12)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| districts | Array<District> | 否 | 否 | 所选行政区划的级别信息。 |
| addressDescription | string | 否 | 是 | 返回所选行政区划的地址信息。 |
District
Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+
行政区划信息。
模型约束： 此接口仅可在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 | 否 | 是 | 区划的坐标点 |
| adminLevel | string | 否 | 是 | 区划级别，分国家、省份、城市、区/县和街道五个区划级别。 说明： 国家：COUNTRY 省份：ADMINISTRATIVE_AREA_LEVEL_1 城市：ADMINISTRATIVE_AREA_LEVEL_2 区/县：ADMINISTRATIVE_AREA_LEVEL_3 街道：ADMINISTRATIVE_AREA_LEVEL_4 |
| adminCode | string | 否 | 是 | 说明： 接口返回的行政区划码覆盖中国大陆及港澳地区，包括省份、城市、区/县、乡镇/街道等层级，文档附录中仅提供部分城市行政区划码示例。 |
| cityCode | string | 否 | 是 | 城市码。 |
| countryCode | string | 否 | 是 | 国家/地区码。 |
在 API参考 中进行搜索
请输入您想要搜索的关键词