开发
API

map

基础库 1.63.0 开始支持本组件。

地图组件。相关 API tt.createMapContext

属性说明

属性名类型默认值必填说明最低支持版本
longitudenumber中心经度1.63.0
latitudenumber中心纬度1.63.0
scalenumber16缩放级别,取值范围为 3-191.63.0
markersMarker[]标记点1.63.0
circlesCircle[]1.63.0
show-locationbooleanfalse是否显示当前位置1.63.0
polylinePolyline[]路线数组1.71.0
include-pointsLngLat[]缩放视野以包含所有给定的坐标点;示例:[{latitude: 0, longitude: 0}]1.71.0
bindtapEventHandle点击地图时触发,e.detail = { latitude, longitude}1.71.0
bindmarkertapEventHandle点击标记点时触发,e.detail = {markerId, latitude, longitude}1.71.0
bindcallouttapEventHandle点击标记点对应的气泡时触发, e.detail = {markerId}1.71.0
bindregionchangeEventHandle视野发生变化时触发1.71.0
rotatenumber0顺时针旋转角度,范围 0 ~ 360,旋转原点为地图容器中心点2.34.0
skewnumber0倾斜角度,范围 0 ~ 40 , 关于 z 轴的倾角2.34.0
polygonsPolygon[]多边形2.34.0
show-compassbooleanfalse显示指南针2.34.0
enable-overlookingbooleanfalse开启俯视手势支持,双指上下滑调整俯仰角2.34.0
enable-rotatebooleanfalse开启旋转手势支持,双指旋转调整旋转角度2.34.0
min-scalenumber3最小缩放级别,取值范围为 3 - max-scale2.42.0
max-scalenumber19最大缩放级别,取值范围为 min-scale - 192.42.0
enable-3Dbooleanfalse是否展示 3D 楼块,该属性 IOS 不支持2.42.0
show-scalebooleanfalse是否显示比例尺2.42.0
enable-zoombooleantrue是否支持缩放2.42.0
enable-scrollbooleantrue是否支持拖动2.42.0
enable-satellitebooleanfalse是否开启卫星图2.42.0
enable-trafficbooleanfalse是否开启实时路况,在该属性为 true 时,enable- buildingenable-3D 无效2.42.0
enable-poibooleantrue是否显示地名2.42.0
enable-buildingbooleantrue是否展示建筑物2.42.0
bindlabeltapEventHandle点击 label 时触发,e.detail = {markerId}2.42.0
bindupdatedEventHandle在地图渲染更新完成时触发2.42.0
bindanchorpointtapEventHandle点击定位标时触发,e.detail = {longitude, latitude}2.42.0

Marker 类型说明

object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
idnumber标记点 id1.63.0
latitudenumber纬度1.63.0
longitudenumber经度1.63.0
titlestring标注点名,点击时显示;不传或者传空字符串,则点击无反应1.63.0
iconPathstring默认 icon图片路径1.63.0
widthnumber标注图标宽度,默认为图片实际宽度2.15.0
heightnumber标注图标高度,默认为图片实际高度2.15.0
zIndexnumbermarker 的显示层级,默认同 marker 插入顺序2.15.0
calloutCallout标记点上方的气泡窗口,支持的属性见 Callout,可识别换行符。有了 callout 将不显示 title2.15.0
alphanumber1标注的透明度,范围 0-12.34.0
anchorXnumber0.5以标注图标左上角为原点,经纬度锚点相对于标注图标的横向偏移比例,以向右为正向,取值区间为 [0, 1]2.34.0
anchorYnumber1以标注图标左上角为原点,经纬度锚点相对于标注图标的纵向偏移比例,以向下为正向,取值区间为 [0, 1]2.34.0
rotatenumber0顺时针旋转的角度,范围 0 ~ 360,默认为 02.42.0
labelLabel为标记点旁边增加标签,支持的属性见 Label2.42.0

Callout 类型说明

object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
contentstring气泡上的文本,不传或者传空字符串取当前 marker 的 title2.15.0
colorColor"#222222"气泡上文本的颜色,支持 HEX, RGBA, 颜色别名2.15.0
fontSizenumber12文字大小,单位为 px2.15.0
borderRadiusnumber12边框圆角,单位为 px2.15.0
paddingnumber0文本边缘留白,单位为 px2.15.0
displaystring"BYCLICK"'BYCLICK':点击显示; 'ALWAYS':常显2.15.0
textAlignstring"center"文本对齐方式。有效值: left, right, center2.15.0
borderWidthnumber0边框宽度2.34.0
borderColorColor"#000000"边框颜色2.34.0
bgColorColor"#ffffff"背景色2.34.0
anchorXnumber0相对于原地位置的横向偏移量,向右为正数2.34.0
anchorYnumber0相对于原地位置的纵向偏移量,向下为正数2.34.0

Label 类型说明

object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
contentstring气泡上的文本,不传或者传空字符串取当前 marker 的 title2.42.0
colorColor"#222222"气泡上文本的颜色,支持 HEX, RGBA, 颜色别名2.42.0
fontSizenumber12文字大小,单位为 px2.42.0
borderRadiusnumber0边框圆角,单位为 px2.42.0
paddingnumber0文本边缘留白,单位为 px2.42.0
textAlignstring"center"文本对齐方式。有效值: left, right, center2.42.0
borderWidthnumber0边框宽度2.42.0
borderColorColor"#000000"边框颜色2.42.0
bgColorColor"#00000000"背景色2.42.0
anchorXnumber0相对于原地位置的横向偏移量,向右为正数2.42.0
anchorYnumber0相对于原地位置的纵向偏移量,向下为正数2.42.0

Circle 类型说明

object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
latitudenumber纬度1.63.0
longitudenumber经度1.63.0
colorColor"#52afff99"边框颜色1.63.0
fillColorColor"#52afff33"填充颜色1.63.0
radiusnumber100半径,单位 “米”1.63.0
strokeWidthnumber1边框宽度1.63.0

LngLat 类型说明

object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
longitudenumber经度1.71.0
latitudenumber纬度1.71.0

Polyline 类型说明

object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
pointsLngLat[]经纬度数组1.71.0
colorColor"#000000"线的颜色1.71.0
widthnumber4线的宽度1.71.0
dottedLinebooleanfalse是否虚线1.71.0
colorListColor[]彩虹线,需指定不同分段的颜色,如 points 包含 5 个点,则 colorList 应传入 4 个颜色值;若 colorList 长度小于 points.length - 1,则剩下的分段颜色与最后一项保持一致。2.34.0
borderColorColor"#000000"线的边框颜色2.34.0
borderWidthnumber0线的边框宽度2.34.0

Polygon 类型说明

object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
pointsLngLat[]多边形顶点经纬度数组,顺时针方向2.34.0
strokeWidthnumber1描边的宽度2.34.0
strokeColorColor"#52afff99"描边的颜色2.34.0
fillColorColor"#52afff33"填充颜色2.34.0
zIndexnumber0设置多边形 Z 轴数值2.34.0

bindregionchange 返回值

属性名类型说明最低支持版本
typestring视野变化开始、结束时触发;值为 begin/end1.71.0
rotatenumber触发回调时地图的旋转角2.34.0
skewnumber触发回调时地图的倾斜角2.34.0
scalenumber触发回调时地图的缩放级别2.34.0
centerLocationLngLat触发回调时地图中心点的经纬度2.34.0
regionRegion触发回调时地图东北角和西南角的经纬度2.34.0

Region 类型说明

属性名类型说明最低支持版本
northeastLngLat东北角经纬度2.34.0
southwestLngLat西南角经纬度2.34.0

比例尺

scale34567891011
比例1000km500km200km100km50km30km20km10km5km
scale1213141516171819
比例2km1km500m200m100m50m25m10m

扫码体验

请使用字节宿主APP扫码

代码示例

开发者工具中预览

<!-- map.ttml -->
<map
  id="myMap"
  show-location
  longitude="{{longitude}}"
  latitude="{{latitude}}"
  circles="{{circles}}"
  markers="{{markers}}"
  polyline="{{polyline}}"
  scale="{{scale}}"
  rotate="{{rotate}}"
  skew="{{skew}}"
  polygons="{{polygons}}"
  show-compass
  enable-overlooking
  enable-rotate
  bindtap="mapTap"
  bindmarkertap="markerTap"
  bindcallouttap="calloutTap"
  bindregionchange="regionChange"
  style="width:100%; height: 300px;"
></map>
<view class="container">
  <view class="btn-area">
    <button bindtap="authLocation" type="primary" size="mini">申请定位权限</button>
    <button bindtap="getCenterLocation" type="primary" size="mini">获取当前地图中心位置</button>
    <button bindtap="moveToLocation" type="primary" size="mini">移动位置</button>
    <button bindtap="getScale" type="primary" size="mini">缩放级别</button>
  </view>
</view>
// map.js
Page({
  data: {
    latitude: 39.907957,
    longitude: 116.397493,
    scale: 15,
    rotate: 10,
    skew: 5,
    polygons: [
      {
        points: [
          {
            latitude: 39.915,
            longitude: 116.404,
          },
          {
            longitude: 116.405,
            latitude: 39.92,
          },
          {
            longitude: 116.423493,
            latitude: 39.907445,
          },
        ],
        strokeWidth: 3,
        strokeColor: "#224499",
        fillColor: "#22334455",
        zIndex: 0,
      },
    ],
    circles: [
      {
        latitude: 39.907957,
        longitude: 116.397493,
        radius: 400,
      },
    ],
    markers: [
      {
        id: 1,
        longitude: 116.397493,
        latitude: 39.907957,
        title: "这是地标1",
        alpha: 0.6,
        anchorX: 0.5,
        anchorY: 1,
      },
      {
        id: 2,
        longitude: 116.39394,
        latitude: 39.90503,
        callout: {
          content: "这是地标 2",
          color: "#222222",
          fontSize: 12,
          borderRadius: 12,
          padding: 4,
          display: "ALWAYS",
          textAlign: "center",
          borderWidth: 1,
          borderColor: "#222222",
          bgColor: "#ffffff",
          anchorX: 0,
          anchorY: 0,
        },
      },
      {
        id: 3,
        longitude: 116.40159,
        latitude: 39.90511,
        title: "这是地标3",
      },
    ],
    polyline: [
      {
        points: [
          {
            longitude: 116.397493,
            latitude: 39.907957,
          },
          {
            longitude: 116.39394,
            latitude: 39.90503,
          },
          {
            longitude: 116.40159,
            latitude: 39.90511,
          },
        ],
        color: "#222222",
        width: 4,
        dottedLine: false,
        colorList: ["#000022", "#220000"],
        borderColor: "#222222",
        borderWidth: 0,
      },
    ],
  },
  onReady() {
    this.mapCtx = tt.createMapContext("myMap");
  },
  markerTap(e) {
    console.log("tap marker", e);
  },
  mapTap(e) {
    console.log("tap map", e);
  },
  calloutTap(e) {
    console.log("tap callout", e);
  },
  regionChange(e) {
    console.log("region", e);
  },
  getCenterLocation() {
    this.mapCtx.getCenterLocation({
      success({ longitude, latitude }) {
        let res = `经度: ${longitude}, 纬度: ${latitude}`;
        console.log(res);
        tt.showModal({
          content: res,
          showCancel: false,
        });
      },
      fail(err) {
        console.log("获取位置失败", err);
      },
      complete(res) {
        console.log("getCenterLocation complete", res);
      },
    });
  },
  moveToLocation() {
    this.mapCtx.moveToLocation({
      success(res) {
        console.log("move success: ", res);
      },
      fail(err) {
        console.log("move err: ", err);
      },
      complete(res) {
        console.log("move complete", res);
      },
    });
  },
  // Auth
  authLocation() {
    let that = this;
    tt.authorize({
      scope: "scope.userLocation",
      success(res) {
        console.log(res, res.data);
        if (res.data["scope.userLocation"] === "ok") that.msg("您已允许授权");
      },
      fail(err) {
        console.log(err);
        if (err.data["scope.userLocation"] === "auth deny")
          that.msg("您已拒绝授权");
      },
    });
  },
  getScale() {
    let that = this;
    this.mapCtx.getScale({
      success(res) {
        console.log("getScale 成功执行了", res);
        that.msg(`当前缩放级别:${res.scale}`);
      },
      fail(err) {
        console.log("getScale失败", err);
      },
      complete(res) {
        console.log("缩放complete执行", res);
      },
    });
  },
  msg(title, duration = 1500) {
    tt.showToast({
      title,
      duration,
    });
  },
});

Bug & Tip

  • Bug:在基础库 2.42.0 版本之前(不包括 2.42.0 版本),Android 的 callout.display 不支持 ALWAYS 属性值;
  • Bug:在基础库 2.42.0 版本之前(不包括 2.42.0 版本),Android 不支持同时显示两个 callout ;
  • Bug:在基础库 2.42.0 版本之前(不包括 2.42.0 版本),Android 不支持 callout 向下偏移;
  • Tip:如果不传经纬度属性则默认为北京中心的经纬度;
  • Tip:scale 在给定 include-points 时无效;
  • Tip:Android 中地图组件宽高不能超过屏幕宽高(屏幕宽高包含导航栏);
  • Tip:如果 polyline 属性的 colorListcolor 同时存在,优先应用 colorList
点击纠错
该文档是否对你的开发有所帮助?
有帮助
没帮助
该文档是否对你的开发有所帮助?
有帮助
没帮助