googleMap

来自于:开发者 立即使用

基础类

添加标注类

概述

谷歌地图简介

谷歌地图 是 Google 公司提供的电子地图服务,包括局部详细的卫星照片。该模块可以打开关闭地图视图,获取当前定位,坐标与地理位置的转换,添加标注,监听地图事件等功能。 使用此模块,手机上必须安装Google Play服务、Googel Play Store。

使用此模块之前必须先配置 config 文件,配置方法如下:

同一个 App 需要同时支持 iOS 和 Android 平台,必须单独申请各自的 apiKey,并同时配置在 config 文件中

支持 android 平台时的配置方法:

  • 配置示例:
 <meta-data
      name="com.google.android.geo.API_KEY"
      value="AIzaSyC-bJcAa1ZCr5Pudsuky16f2vk3DyRTn54" />

value是在谷歌申请的apiKey

支持 iOS 平台时的配置方法:

  • 名称:googleMap
  • 参数:ios_api_key
  • 配置示例:
  <feature name="googleMap">
    <param name="ios_api_key" value="AIzaSyAPLwmxjyqqXjJ6g_5MSra5mzKElqIUZsz" />
  </feature>

注意:请确保您的 ak 正确性,否则地图加载异常,在 ios 平台最低适配版本为 iOS 8

模块接口

open

打开谷歌地图

open({params}, callback(ret))

params

rect:

  • 类型:JSON 对象
  • 描述:(可选项)模块的位置及尺寸
  • 内部字段:
{
    x: 0,   //(可选项)数字类型;地图左上角的 x 坐标(相对于所属的 Window 或 Frame);默认:0
    y: 0,   //(可选项)数字类型;地图左上角的 y 坐标(相对于所属的 Window 或 Frame);默认:0
    w: 320, //(可选项)数字类型;地图的宽度;默认:'auto'
    h: 480  //(可选项)数字类型;地图的高度;默认:'auto'
}

center:

  • 类型:数字
  • 描述:(可选项)打开地图时设置的中心点经纬度
  • 内部字段:
{
    lon: 116.213,       //数字类型;打开地图时设置的中心点经度
    lat: 39.213         //数字类型;打开地图时设置的中心点纬度
}

zoomLevel:

  • 类型:数字
  • 描述:(可选项)设置谷歌地图缩放等级,取值范围:1-21级(Android)、getZoomExtremity接口获取(iOS)
  • 默认值:10

showUserLocation:

  • 类型:布尔
  • 描述:(可选项)是否在地图上显示用户位置(仅支持ios)
  • 默认值:true

fixedOn:

  • 类型:字符串类型
  • 描述:(可选项)模块视图添加到指定 frame 的名字(只指 frame,传 window 无效)
  • 默认:模块依附于当前 window

fixed:

  • 类型:布尔
  • 描述:(可选项)模块是否随所属 window 或 frame 滚动
  • 默认值:true(不随之滚动)

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    status: true     //布尔型;true||false
}

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.open({
    rect: {
        x: 0,
        y: 0,
        w: 320,
        h: 300
    },
    showUserLocation: true,
    zoomLevel: 11,
    center: {
        lon: 116.4021310000,
        lat: 39.9994480000
    },
    fixedOn: api.frameName,
    fixed: true
}, function(ret) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    }
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

close

关闭谷歌地图

close()

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.close();

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

show

显示谷歌地图

show()

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.show();

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

hide

隐藏谷歌地图

hide()

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.hide();

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

setType

设置地图类型

setType({params})

params

type:

  • 类型:字符串
  • 描述:指定的地图的类型
  • 默认:normal
  • 取值范围:
    • normal:典型道路地图。显示道路、人类建造的一些特征以及河流等重要的自然特征。
    • satellite:卫星照片数据。不显示道路和景观标签。
    • terrain:地形数据。 地图包含颜色、轮廓线和标签以及透视阴影。
    • hybrid:添加了道路地图的卫星照片数据。 此外,还会显示道路和景观标签。
    • none:无地图图块。 不会呈现基本地图图块。

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.setType({
    type: 'setellite'
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

setTraffic

设置地图是否显示交通路况

setTraffic({params})

params

traffic:

  • 类型:布尔
  • 描述:是否显示交通路况
  • 默认:false

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.setTraffic({
    traffic: true
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

setLocationButton

设置地图是否显示定位按钮

setLocationButton({params})

params

locationButton:

  • 类型:布尔
  • 描述:是否显示定位按钮
  • 默认:false

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.setLocationButton({
    locationButton: true
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

setCompassButton

设置地图是否显示指南针

setCompassButton({params})

params

compassButton:

  • 类型:布尔
  • 描述:是否显示指南针
  • 默认:false

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.setCompassButton({
    compassButton: true
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

setBuildings

设置地图是否显示建筑

setBuildings({params})

params

buildings:

  • 类型:布尔
  • 描述:是否显示建筑
  • 默认:false

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.setBuildings({
    buildings: true
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

setRect

重设地图的显示区域

setRect({params})

params

rect:

  • 类型:JSON 对象
  • 描述:(可选项)模块的位置及尺寸
  • 内部字段:
{
    x: 0,   //(可选项)数字类型;地图左上角的 x 坐标(相对于所属的 Window 或 Frame);默认:原值
    y: 0,   //(可选项)数字类型;地图左上角的 y 坐标(相对于所属的 Window 或 Frame);默认:原值
    w: 320, //(可选项)数字类型;地图的宽度;默认:原值
    h: 480  //(可选项)数字类型;地图的高度;默认:原值
}

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.setRect({
    rect: {
        x: 0,
        y: 0,
        w: 320,
        h: 300
    }
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

getLocation

获取当前位置信息,若要支持后台定位需配置 config.xml 文件 location 字段,无需调用 open 接口即可使用

getLocation({params}, callback(ret))

params

autoStop:

  • 类型:布尔
  • 描述:(可选项)获取到位置信息后是否自动停止定位
  • 默认值:true

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    status: true,               //布尔型;true||false
    lon: 116.213,               //数字类型;经度
    lat: 39.213,                //数字类型;纬度
    accuracy: 65,               //数字类型;本次定位的精度,仅支持 iOS 平台
    timestamp: 1396068155591,   //数字类型;时间戳
    heading:200,                //数字类型;设备方向,取值范围:0.0(正北) - 359.9 
    altitude: 200               //数字类型;当前设备所处的海拔信息
}

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.getLocation(function(ret) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    }
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

stopLocation

停止定位

stopLocation()

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.stopLocation();

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

getCoordsFromName

根据地址查找经纬度,无需调用 open 接口即可使用

注意:

在 ios 平台谷歌地图不支持地理编码,需要自己构造一个网络请求,然后自己做相应处理。谷歌的地理编码用到的是 Google Maps Geocoding API 首先需要去谷歌的开发者后台激活Google Maps Geocoding API,Key需要作为一个参数拼接到网络请求后面。 例如:https://maps.googleapis.com/maps/api/geocode/json?address= Staples Center&key=API_KEY 需要注意的是,普通用户 API 每天只能进行2500次请求,想要增加配合需要付费。

android平也支持使用以上方法进行获取

getCoordsFromName({params}, callback(ret, err))

params

city:

  • 类型:字符串
  • 描述:所要搜索的地址所在的城市,cityname(中文或中文全拼)、citycode、adcode

address:

  • 类型:字符串
  • 描述:完整的地址信息

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    status: true,        //布尔型;true||false
    lon: 116.351,        //数字类型;地址所在经度
    lat: 39.283          //数字类型;地址所在纬度
}

err:

  • 类型:JSON 对象
  • 内部字段:
{
    code: 1           //数字类型;错误码
    msg:              //字符串类型;错误描述
}

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.getCoordsFromName({
    city: '北京',
    address: '天安门'
}, function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性

Android系统

可提供的1.0.0及更高版本

getNameFromCoords

根据经纬度查找地址信息,无需调用 open 接口即可使用

getNameFromCoords({params}, callback(ret))

params

lon:

  • 类型:数字
  • 描述:经度

lat:

  • 类型:数字
  • 描述:纬度

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    status: true,              //布尔型;true||false,
    addressLines:[]           //数组类型;地址名称数组(仅支持Android)
    state: '',                 //字符串类型;省份
    city: '',                  //字符串类型;城市
    district: '',              //字符串类型;县区(仅支持ios)
    thoroughfare: '',          //字符串类型;社区
}

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.getNameFromCoords({
    lon: 116.384767,
    lat: 39.989539
}, function(ret) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    }
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

getDistance

获取地图两点之间的距离,无需调用 open 接口即可使用

getDistance({params}, callback(ret))

params

start:

  • 类型:JSON 对象
  • 描述:起点经纬度
  • 内部字段:
{
    lon: 106.486654,    //数字类型;起点的经度
    lat: 29.490295      //数字类型;起点的纬度
}

end:

  • 类型:JSON 对象
  • 描述:终点经纬度
  • 内部字段:
{
    lon: 106.581515,    //数字类型;终点的经度
    lat: 29.615467      //数字类型;终点的纬度
}

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    status: true,              //布尔型;true||false
    distance: 16670.90         //数字类型;两点之间的距离,单位:米
}

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.getDistance({
    start: {
        lon: 106.486654,
        lat: 29.490295
    },
    end: {
        lon: 106.581515,
        lat: 29.615467
    }
}, function(ret) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } 
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

showUserLocation

是否在地图上显示用户位置(仅支持ios)

showUserLocation({params})

params

isShow:

  • 类型:布尔
  • 描述:(可选项)是否显示用户位置
  • 默认值:true

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.showUserLocation({
    isShow: true
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

setCenter

根据经纬度设置谷歌地图中心点

setCenter({params})

params

coords:

  • 类型:JSON 对象
  • 描述:(可选项)中心点的经纬度
  • 内部字段:
{
    lon: 116.404,       //(可选项)数字类型;设置中心点的经度
    lat: 39.915         //(可选项)数字类型;设置中心点的纬度
}

animation:

  • 类型:布尔类型
  • 描述:(可选项)设置地图的中心点时,是否带动画效果
  • 默认:true

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.setCenter({
    coords: {
        lon: 116.404,
        lat: 39.915
    },
    animation: false
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

getCenter

获取谷歌地图中心点坐标

getCenter(callback(ret))

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    lon: 116.404,       //数字类型;地图中心点的经度
    lat: 39.915         //数字类型;地图中心点的纬度
}

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.getCenter(function(ret) {
    if (ret) {
        alert(JSON.stringify(ret));
    } 
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

getZoomExtremity

获取谷歌地图缩放最大、最小值

getZoomExtremity(callback(ret))

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    min: 0,         //数字类型;最小值
    max: 26         //数字类型;最大值
}

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.getZoomExtremity(function(ret){
    if (ret) {
        api.alert({msg:JSON.stringify(ret)});
    }
});

可用性

iOS系统

可提供的1.0.0及更高版本

setZoomLevel

设置谷歌地图缩放等级

setZoomLevel({params})

params

level:

  • 类型:数字
  • 描述:(可选项)地图比例尺级别,取值范围:1-21级(Android)、通过getZoomExtremity接口获得(iOS)
  • 默认值:10

animation:

  • 类型:布尔类型
  • 描述:(可选项)地图缩放时,是否带动画效果
  • 默认:true

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.setZoomLevel({
    level: 10,
    animation: true
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

getZoomLevel

获取地图缩放级别取值范围:1-21级(Android)、通过getZoomExtremity接口获得(iOS)

getZoomLevel(callback(ret))

callback

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    level: 11           //数字类型;地图当前缩放级别
}

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.getZoomLevel(function(ret) {
    if (ret) {
        alert(JSON.stringify(ret));
    } 
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

addEventListener

监听地图相关事件

addEventListener({params}, callback(ret))

params

name:

  • 类型:字符串
  • 描述:地图相关事件名称
  • 取值范围:
    • longPress(长按事件)
    • viewChange(视角改变事件)
    • click(单击事件)

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    status: true,           //布尔型;true||false
    lon: 116.351,           //数字类型;触发事件的地点的经度(longPress,click),地图中心的经度(viewChange,zoom)
    lat: 39.283,            //数字类型;触发事件的地点的纬度(longPress,click),地图中心的纬度(viewChange,zoom)
    zoom: 11,               //数字类型;地图缩放角度
    rotate: 30,             //数字类型;地图旋转角度,iOS平台无此参数
    overlook: 30,           //数字类型;视角倾斜度,iOS平台无此参数
}

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.addEventListener({
    name: 'longPress'
}, function(ret) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    }
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

removeEventListener

停止监听地图相关事件

removeEventListener({params})

params

name:

  • 类型:字符串
  • 描述:地图相关事件名称
  • 取值范围:
    • longPress(长按事件)
    • viewChange(视角改变事件)
    • click(单击事件)

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.removeEventListener({
    name: 'longPress'
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

addAnnotations

在地图上添加标注信息,标注大小为 icons 内第一张图片大小的二分之一。图标中轴线的下边缘点为坐标基准点

addAnnotations({params})

params

annotations:

  • 类型:数组
  • 描述:图标标注信息组成的数组
  • 内部字段:
[{
    id: 1,                     //数字类型;图标标注的唯一标识
    lon: 116.233,              //数字类型;图标标注所在位置的经度
    lat: 39.134,               //数字类型;图标标注所在位置的纬度
    icons: 'widget://',        //(可选项)数组类型;指定的标注图标路径组成的数组,若包含多张图片,则此标注显示为多图联动的 gif 动画效果,要求本地路径(fs://、widget://),若不传则显示公用的 icons 图标,(仅支持ios)
    icon: 'widget://',        //(可选项)数组类型;指定的标注图标路径,要求本地路径(fs://、widget://),若不传则显示公用的 icon 图标(仅支持android)
    draggable: true            //(可选项)布尔类型;所添加的标注是否可被拖动,若不传则以公用的 draggable 为准
}]

icons:

  • 类型:数组
  • 描述:(可选项)指定的标注图标路径组成的数组,若包含多张图片,则此标注显示为多图联动的 gif ,要求本地路径(fs://、widget://)(仅支持ios)
  • 默认值:红色大头针

icon:

  • 类型:字符串
  • 描述:(可选项)指定的标注图标路径,要求本地路径(fs://、widget://)(仅支持android)
  • 默认值:红色大头针

draggable:

  • 类型:布尔
  • 描述:(可选项)所添加的标注是否可被拖动
  • 默认值:false

timeInterval:

  • 类型:数字
  • 描述:(可选项)若添加的标注为动态图,则本参数表示动态图循环播放一次的时间,单位为秒(s),否则本参数无效(仅支持ios)
  • 默认值:3.0

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.addAnnotations({
    annotations: [{
        id: 1,
        lon: 116.297,
        lat: 40.109
    }, {
        id: 2,
        lon: 116.29,
        lat: 40.109
    }, {
        id: 3,
        lon: 116.298,
        lat: 40.11
    }],
    icons: ['widget://'],
    draggable: true,
    timeInterval: 2.0
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

addAnnotationListener

添加对地图上标注的监听

addAnnotationListener(callback(ret, err))

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    id: 10                      //数字类型;相应事件的标注的
    eventType: 'click',         //字符串类型;交互事件类型
                                //取值范围:
                                //click(用户点击标注事件)
                                //drag(用户拖动标注事件)
                                //clickBubble(用户点击气泡事件)
                                //longPressBubble(长按气泡事件)(仅支持ios)
                                //closeBubble(气泡关闭事件)(仅支持ios)
    dragState: 'starting'       //字符串类型;标注被拖动的状态,当 eventType 为 drag 时本字段有值,
                                //取值范围:
                                //starting(开始拖动)
                                //dragging (拖动中)
                                //ending (拖动结束)
}

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.addAnnotationListener(function(ret) {
    if (ret.eventType == 'drag') {
        if(ret.dragState == 'dragging') {
           console.log('JSON.stringify(ret)');
        } else if (ret.dragState == 'starting') {
           console.log('JSON.stringify(ret)');
        } else {
           api.alert({msg:JSON.stringify(ret)});
        }
    } else {
        api.alert({msg:JSON.stringify(ret)});
    }
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

getAnnotationCoords

获取指定标注的经纬度

getAnnotationCoords({params}, callback(ret))

params

id:

  • 类型:数字
  • 描述:指定的标注 id

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    lon: 116.213,      //数字类型;标注的经度
    lat: 39.213        //数字类型;标注的纬度
}

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.getAnnotationCoords({
    id: 2
}, function(ret) {
    if (ret) {
        api.alert({ msg: JSON.stringify(ret) });
    }
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

setAnnotationCoords

设置某个已添加标注的经纬度

setAnnotationCoords(callback(ret, err))

params

id:

  • 类型:数字
  • 描述:指定的标注 id

lon:

  • 类型:数字
  • 描述:设置的经度

lat:

  • 类型:数字
  • 描述:设置的纬度

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.setAnnotationCoords({
    id: 2,
    lon: 116.39,
    lat: 40.209
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

setAnnotationIcon

设置某个已添加标注的图标

setAnnotationIcon(callback(ret, err))

params

id:

  • 类型:数字
  • 描述:指定的标注 id

icon:

  • 类型:字符串
  • 描述:指定的标注图标路径,要求本地路径(fs://、widget://)

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.setAnnotationIcon({
    id: 2,
       icon : "widget://image/icon.png"
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

removeAnnotations

移除制定标注

removeAnnotations({params})

params

id:

  • 类型:数组
  • 描述:指定的标注 id 组成的数组,若不传或传空,则移除所有标注

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.removeAnnotations({
    id: [1]
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

setBubble

设置某个已添加标注的气泡(点击标注弹出的信息窗口),

注意:若不调用本接口设置气泡,或 content 参数传空,则点击标注无气泡弹出。

setBubble({params})

params

id:

  • 类型:数字
  • 描述:指定的标注 id

content:

  • 类型:JSON 对象
  • 描述:气泡内容文本
  • 内部字段:
{
    title: '',             //字符串类型;气泡的标题文本
    snippet: ''            //字符串类型;显示在标题下面的文本。 超出信息窗口宽度的字符串将自动换成多行。 特别长的消息可能会被截断。
}

示例代码

var GoogleMap = api.require('googleMap');
GoogleMap.setBubble({
    id: 2,
    content: {
       title: '点击、长按我有回调',
       snippet: '可在addAnnotationListener接口回调中监听点击、长按事件'
    }
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本