/SimpleMap-wx

为微信小程序提供的一个基于Canvas的自定义地图控件,实现了瓦片地图、自定义标记图层和多种交互部件。

Primary LanguageJavaScriptMIT LicenseMIT

SimpleMap-WX

为微信小程序提供的一个基于Canvas的自定义地图控件,实现了瓦片地图、自定义标记图层和多种交互部件。


仓库根目录是一个小程序 Demo 项目,可以直接使用微信开发者工具打开进行预览,预览时需勾上“不校验合法域名”。


SimpleMap 组件实际使用案例:

微信小程序“小恐龙课程表” —— 校园地图功能

无法加载动图?点击这里
演示动图


详细文档

查看详细文档

简单使用

1. 可以选择 clone 或下载此仓库到本地。

2. 将 simplemap 目录复制到你的项目根目录下(不必须,可以放到任意位置,但要注意引入模块时的路径)。

3. 编辑要使用 SimpleMap 地图的页面 wxml 布局文件,添加以下代码。

<import src="/simplemap/simplemap.wxml"/>

<template is="SimpleMap" data="{{...demo_map}}"/>
  • demo_map 为地图的唯一名称,可以更改为自己想要的名称。

  • SimpleMap 组件默认会占满整个页面,且置于所有组件的最顶层。

  • 如需指定 SimpleMap 组件的大小和位置,只需将 SimpleMap 模板包含在 id 和地图名称相同的父元素内,并对父元素进行定位即可,例如:

<view id="demo_map" style="width: 300px; height: 200px;"> 
	<template is="SimpleMap" data="{{...demo_map}}"/>
</view>

4. 编辑页面的 js 文件,在代码顶部引入 SimpleMap 和其他相关类。

// 需改为在项目中的实际路径(相对路径)
const SimpleMap = require("../../simplemap/simplemap").SimpleMap // SimpleMap 核心类
const Layer = require("../../simplemap/layers/Layer") // 图层模块包
const Widget = require("../../simplemap/widgets/Widget") // UI 部件模块包

5. 分别在 onLoad、onShow、onHide 和 onUnload 回调函数中添加代码,对 SimpleMap 进行初始化、开始绘制、暂停绘制和结束绘制的操作。

onMapReady: function(res){
	// res.map 准备好的 SimpleMap 对象
	// res.width 确定后的 SimpleMap 组件宽度
	// res.height 确定后的 SimpleMap 组件高度
}
onLoad: function (options) {
	const mapOptions = {
		minZoom: 0.6, // 最小缩放倍数
		maxZoom: 3, // 最大缩放倍数
		slide: true // 开启惯性滑动
	}
	const map = new SimpleMap(this, "demo_map", mapOptions)
	// 设置地图 canvas 准备完毕的回调
	map.setOnReadyCallback(this.onMapReady)
	this.map = map
},
onShow: function(){
	// 在页面显示时调用show方法,开始绘制地图。
	this.map.show()
},
onHide: function () {
	// 在页面显示时调用hide方法,暂停绘制地图以节省资源。
	this.map.hide()
},
onUnload: function () {
	// 在页面被回收时调用stop方法,彻底结束掉地图绘制。
	this.map.stop()
}

6. (推荐)在 readyCallback 回调函数中设置地图图层。

onMapReady: function(res){
	const map = res.map
	const TILE_URL = "https://www.dennic365.com/static/cqcet/"
	// 配置瓦片图图层
	const mapLayer = new Layer.TileMapLayer(map, 1000, 1000)
	mapLayer.addTileLevel(1.4, TILE_URL + "cqcet-s-{column}-{row}.jpg", 1001, 1438, 500, 500)
	mapLayer.addTileLevel(2.4, TILE_URL + "cqcet-m-{column}-{row}.jpg", 2669, 3835, 800, 800)
	mapLayer.addTileLevel(2.8, TILE_URL + "cqcet-l-{column}-{row}.jpg", 5000, 7185, 800, 800)
	// 将图层设为底图
	map.setMap(mapLayer)
}

7. 向地图组件中添加 Mark 标记图层。

// 实例化一个新的 Mark 标签,传入标签在地图中的坐标
const mark = new Layer.MarkLayer(map, null, 100, 150)
// 设置可见标记的缩放范围
mark.setVisibleZoom(1, 1.8)
// 设置标记文字标签
mark.setTag("一个标记")
// 设置标记文字颜色
mark.setTextColor("#363636")
// 设置标记文字位置
mark.setTagPosition("bottom")
// 设置标记点击回调
mark.setClickCallback(e => {
	wx.showToast({
		title: "点击标记"
	})
})
// 设置标记长按回调
mark.setLongTapCallback(e => {
	wx.showToast({
		title: "长按标记"
	})
})
// 将标记图层添加到地图组件中
map.addLayer(mark)

8. 向地图组件中添加 UI 按钮部件。

// 实例化一个新的按钮部件,传入按钮位置和按钮文字。
const btnZoomIn = new Widget.ImageButton(map, 50, 100, "放大")
// 设置按钮的点击回调
btnZoomIn.setClickCallback(widget => {
	map.setZoom(map.getZoom() * 1.5)
})
// 将按钮部件添加到地图组件中
map.addWidget(btnZoomIn)

类目录结构

  • SimpleMap
  • Layer
    • MapLayer -- 单一图片地图图层
    • TileMapLayer -- 瓦片地图图层
    • MarkLayer -- 标记图层
    • MarkGroupLayer -- 标记组图层
  • Widget
    • Button -- 按钮组件
    • ImageButton -- 图标按钮组件
    • ButtonGroup -- 按钮组组件
    • Text -- 文字组件
    • Image -- 图片组件
  • Utils
    • Convert -- 单位转换和测量工具
    • Math -- 数学计算工具
    • Region -- 区块工具
    • Matrix -- 矩阵工具
    • Slider -- 惯性滑动工具
    • Touch -- 触摸管理工具
    • Renderer -- 渲染工具
    • Downloader -- 文件下载和缓存工具
    • Tile -- 瓦片图管理工具

部分类构造方法说明

详细的类方法说明文档正在编辑中......

SimpleMap(page, name, options, readyCallback)

SimpleMap 组件的核心类

构造函数参数说明:
参数 类型 必须 说明
page Object 传入当前的页面对象
name String 地图的唯一名称,与 wxml 中一致
options Object 地图配置参数
readyCallback Function 监听地图准备完毕回调函数
options 参数说明:
参数 类型 默认值 说明
minZoom Number 0.6 最小缩放倍数
maxZoom Number 2 最大缩放倍数
slide Boolean true 是否开启惯性滑动
readyCallback 返回参数说明:
参数 类型 说明
map Object 准备完毕的 SimpleMap 对象
width Number 确定后的 SimpleMap 组件宽度
height Number 确定后的 SimpleMap 组件高度

Layer.MapLayer(map, path, width, height)

单一图片地图图层

构造函数参数说明:
参数 类型 必须 说明
map Object SimpleMap 地图组件对象
path String 图片资源路径(本地文件路径或网络图片URL)
width Number 地图图层宽度
height Number 地图图层高度

Layer.TileMapLayer(map, width, height)

瓦片地图图层

构造函数参数说明:
参数 类型 必须 说明
map Object SimpleMap 地图组件对象
width Number 地图图层宽度
height Number 地图图层高度

Layer.MarkLayer(map, path, x, y, width, height)

地图标记图层

构造函数参数说明:
参数 类型 必须 说明
map Object SimpleMap 地图组件对象
path String 标记图片资源路径(本地文件路径或网络图片URL)(若该参数为 null,默认将绘制一个纽扣图标)
x Number 标记坐标 X
y Number 标记坐标 Y
width Number 标记图标宽度
height Number 标记图标高度

Widget.Button(map, x, y, text, textSize, padding)

普通按钮部件

构造函数参数说明:
参数 类型 必须 默认值 说明
map Object SimpleMap 地图组件对象
x Number 部件坐标 X
y Number 部件坐标 Y
text String 按钮文字
textSize Number 14px 字体大小
padding Number 24rpx 文字周围填充尺寸

Widget.ImageButton(map, x, y, path, width, height, padding)

图标按钮部件

构造函数参数说明:
参数 类型 必须 默认值 说明
map Object SimpleMap 地图组件对象
x Number 部件坐标 X
y Number 部件坐标 Y
path String 图片资源路径(本地文件路径或网络图片URL)
width Number 图标宽度
height Number 图标高度
padding Number 24rpx 图标周围填充尺寸