---
name: "map"
mode: "component"
versionRequirements:
  - { name: "基础库", version: "2.10.0" }
title: "map - 地图"
---

## map

> [VERSION] 基础库 >= 2.10.0

### 描述

地图组件。

### 属性

| 属性 | 类型 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `longitude` | `number` | 否 | `116.404177` | 中心经度。鸿蒙端仅初始化时生效，动态修改无效 |
| `latitude` | `number` | 否 | `39.909652` | 中心纬度。鸿蒙端仅初始化时生效，动态修改无效 |
| `scale` | `number` | 否 | `16` | 缩放级别，取值范围 4-19。鸿蒙端仅初始化时生效，动态修改无效 |
| `markers` | `any[]` | 否 | `[]` | 标记点。鸿蒙端不支持 |
| `polyline` | `any[]` | 否 | `[]` | 路线。鸿蒙端不支持 |
| `circles` | `any[]` | 否 | `[]` | 圆形区域。鸿蒙端不支持 |
| `polygons` | `any[]` | 否 | `[]` | 多边形区域。鸿蒙端不支持 |
| `disable-animation` | `boolean` | 否 | `false` | 禁用地图自带动画。仅 iOS 端支持，且仅在中心点移动时生效 |
| `disable-rotate` | `boolean` | 否 | `false` | 禁用旋转手势。鸿蒙端不支持 |
| `map-type` | `number` | 否 | - | 地图类型：-1 跟随 App 主题、0 深色、1 浅色、2 卫星图。鸿蒙端不支持 |
| `show-scale-view` | `boolean` | 否 | `false` | 是否显示比例尺控件。仅 Android 端支持，且仅初始化时生效 |
| `background-color` | `string` | 否 | `"#ffffff"` | 背景颜色，必须为十六进制格式 |
| `border-width` | `number` | 否 | `0` | 边框宽度，单位 px |
| `border-style` | `string` | 否 | `"solid"` | 边框样式，可选值：solid 实线，dashed 虚线 |
| `border-color` | `string` | 否 | `"#ffffff"` | 边框颜色，必须为十六进制格式 |
| `border-radius` | `number` | 否 | `0` | 边框圆角，单位 px |
| `border-radius-top-left` | `number` | 否 | - | 左上角圆角，单位 px |
| `border-radius-top-right` | `number` | 否 | - | 右上角圆角，单位 px |
| `border-radius-bottom-left` | `number` | 否 | - | 左下角圆角，单位 px |
| `border-radius-bottom-right` | `number` | 否 | - | 右下角圆角，单位 px |

#### 事件

| 事件名 | 类型 | 描述 |
| --- | --- | --- |
| `markertap` | `(event: MapMarkertapEvent) => void` | 点击标记点时触发 |
| `callouttap` | `(event: MapCallouttapEvent) => void` | 点击标记点对应的气泡时触发 |
| `regionchange` | `(event: MapRegionchangeEvent) => void` | 视野发生变化时触发 |
| `tap` | `(event: Object) => void` | 点击地图时触发 |
| `updated` | `(event: Object) => void` | 地图渲染更新完成时触发 |

**MapMarkertapEvent**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"markertap"` |  |
| `detail` | `MapMarkertapDetail` |  |

**MapCallouttapEvent**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"callouttap"` |  |
| `detail` | `MapCallouttapDetail` |  |

**MapRegionchangeEvent**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"regionchange"` |  |
| `detail` | `MapRegionchangeDetail` |  |

**tap 的回调参数对象**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"tap"` |  |

**updated 的回调参数对象**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"updated"` |  |

### 示例代码

#### 标记点与气泡

*index.tyml*

```xml
<map
  longitude="{{lng}}"
  latitude="{{lat}}"
  scale="{{14}}"
  markers="{{markers}}"
  class="map"
  bind:markertap="onMarkerTap"
  bind:callouttap="onCalloutTap"
/>
```

*index.tyss*

```css
.map {
  width: 100%;
  height: 500rpx;
}
```

*index.js*

```javascript
Page({
  data: {
    lng: 116.397428,
    lat: 39.90923,
    markers: [
      {
        id: 1,
        longitude: 116.397428,
        latitude: 39.90923,
        title: '天安门',
        iconPath: '/images/marker.png',
        width: 30,
        height: 30,
        callout: {
          content: '天安门广场',
          color: '#333',
          fontSize: 14,
          bgColor: '#fff',
          borderRadius: 4,
          padding: 8,
          textAlign: 'center',
        },
      },
      {
        id: 2,
        longitude: 116.407428,
        latitude: 39.91523,
        title: '故宫',
        iconPath: '/images/marker.png',
        width: 30,
        height: 30,
      },
    ],
  },
  onMarkerTap(e) {
    console.log('点击标记点:', e.detail.markerId);
  },
  onCalloutTap(e) {
    console.log('点击气泡:', e.detail.markerId);
  },
});
```

#### 路线与覆盖层

*index.tyml*

```xml
<map
  longitude="{{lng}}"
  latitude="{{lat}}"
  scale="{{13}}"
  polyline="{{polyline}}"
  circles="{{circles}}"
  polygons="{{polygons}}"
  class="map"
  bind:regionchange="onRegionChange"
/>
```

*index.tyss*

```css
.map {
  width: 100%;
  height: 500rpx;
  border-radius: 12px;
}
```

*index.js*

```javascript
Page({
  data: {
    lng: 116.407428,
    lat: 39.91523,
    polyline: [
      {
        points: [
          { latitude: 39.90923, longitude: 116.397428 },
          { latitude: 39.91523, longitude: 116.407428 },
          { latitude: 39.92023, longitude: 116.417428 },
        ],
        color: '#1890ff',
        width: 4,
        dottedLine: false,
      },
    ],
    circles: [
      {
        latitude: 39.90923,
        longitude: 116.397428,
        radius: 500,
        color: '#1890ff80',
        fillColor: '#1890ff20',
        strokeWidth: 2,
      },
    ],
    polygons: [
      {
        points: [
          { latitude: 39.91, longitude: 116.4 },
          { latitude: 39.92, longitude: 116.41 },
          { latitude: 39.91, longitude: 116.42 },
        ],
        strokeColor: '#ff4d4f',
        fillColor: '#ff4d4f20',
        strokeWidth: 2,
      },
    ],
  },
  onRegionChange(e) {
    console.log('视野变化:', e.detail.type);
  },
});
```


> Tuya MiniApp IDE 上是通过 WebView 模拟的与真机存在差异，请以真机效果为主。真机国内使用高德地图，海外使用google地图。

<DemoBlock 
  githubUrl="https://github.com/Tuya-Community/tuya-miniapp-demo/tree/master/rayMap" 
  qrCodeUrl="/images/qrCode/rayMap.png" 
  lang="zh">
</DemoBlock>


### 相关文档

- 相关 API：[ty.createMapContext](/cn/miniapp/develop/miniapp/api/media/map/createMapContext)
- 这是基于异层渲染的原生组件，请注意 [原生组件使用限制](/cn/miniapp/develop/miniapp/component/native-component/native-component)

### 常见问题

1. 地图组件的经纬度必填, 如果不填经纬度则默认值是北京的经纬度。
2. Tuya MiniApp IDE 上是通过 WebView 模拟的与真机存在差异，请以真机效果为主。
3. 相关原理请参考 [基于异层渲染的原生组件](/cn/miniapp/develop/miniapp/component/native-component/native-component)。
4. 请注意 [原生组件使用限制](/cn/miniapp/develop/miniapp/component/native-component/native-component)。