#Language
Chinese
English

ZoomMarker

一款用于图片滚动放大拖动，且可以添加标记的jQuery插件

在项目中需要实现类似地图应用那样的，具有鼠标滚动缩放和拖动功能的插件效果，且可以添加具有回调功能的标记点。在网上找了一圈都没有找到合适的，所以图方便自己写了一个。
如有任何功能问题或改进意见，欢迎反馈，感谢。

Preview效果预览

点击这里查看使用ZoomMarker和EasyLoading构建的图片拖拽、缩放、标记及加载动画的示例，使用鼠标或触屏点击在图片上添加标记点，鼠标悬浮在上面查看悬浮提示窗口，使用顶部按钮实现图片切换、清空标记点和加载动画示例等。
点击这里查看带的分区域显示的例子。

Version版本

version	date	detail
0.1.9	2020.9.25	修复了消息回调接口加载marker的问题
0.1.8	2020.8.2	添加标记点移动结束回调接口
0.1.7	2020.1.2	添加重新加载标记点接口
0.1.6	2019.6.23	修正图像锁边缩放逻辑
0.1.5	2019.4.9	添加图像位置和大小重置接口
0.1.4	2019.4.1	添加图像拖动锁边功能
0.1.3	2019.4.1	修复移动端ChromeV8内核图片拖动及marker点击触发问题
0.1.2	2019.2.21	添加标记点可拖动选项
0.1.1	2019.2.21	添加缩放锁定参数
0.1.0	2019.2.13	添加Canvas绘图层接口，优化多图层环境体验
0.0.11	2019.2.7	多图层环境下，点击非当前图层时将拦截图层切换的发送消息
0.0.10	2018.11.6	解决多图像下图片和标记点的迭代顺序问题
0.0.9	2018.11.5	解决缩放图片后图片大小不一致问题
0.0.8	2018.9.25	支持同时显示多个图片控件
0.0.7	2018.9.25	添加允许和禁止图像拖动接口
0.0.6	2018.7.24	解决jQuery的context废弃undefined问题
0.0.5	2017.11.13	添加图像居中接口，修复重复初始化问题
0.0.4	2017.11.11	修正图片显示比例错误的问题
0.0.3	2017.11.8	优化接口API
0.0.2	2017.11.3	引入Hammer.js处理鼠标操作
0.0.1	2017.10.25	初始版本，基础功能

Require依赖

name	min-version	detail
jQuery	3.3.1	JavaScript的DOM操作框架
jquery.mousewheel	1.6	jQuery鼠标滚轮监听插件
Hammer.js	2.0.4	多点触控插件
EasyLoading.js	0.1.0	(可选) 加载动画库

在本例子中，还使用了自行编写的开源加载动画插件EasyLoading，该插件同样需要jQuery支持。 如果您对EasyLoading感兴趣，欢迎加星。

Usages用法

1. 快速使用

引入ZoomMarker的JavaScript和CSS文件

<link rel="stylesheet" href="css/zoom-marker.css">
<script src="js/zoom-marker.js"></script>

引入第三方依赖库

<script src="js/jquery-1.11.3.min.js"></script>
<script src="js/jquery.mousewheel.min.js"></script>
<script src="js/hammer.min.js"></script>

在示例中，使用了图像加载动画，为此您还需要引入EasyLoading插件，它也可以单独使用。如果您的项目中不需要使用加载动画，则不需要 引入该插件。

<link rel="stylesheet" href="css/easy-loading.css">
<script src="js/easy-loading.js"></script>

添加必要的html标签，注意img标签必须包含唯一的id属性

<div id="zoom-marker-div" class="zoom-marker-div">
    <img class="zoom-marker-img" id="zoom-marker-img" alt="..." name="viewArea"  draggable="false"/>
</div>

在ready()中调用初始化方法

$(document).ready(function () {
    $('#zoom-marker-img').zoomMarker({
        src: "img/mountain.jpg",
        rate: 0.2,
        width: 600,
        max: 3000,
        markers:[
            {src:"img/marker.svg", x:500, y:500}
            ]
    });
})

在上述例子中，你还需要在img/目录下添加一个名为moutain.jpg的文件用于显示图片，在img/目录下添加名为marker.svg的文件作为marker文件资源，我们已经在该工程对应目录下添加这两个文件。 现在你可以看到效果了，单击鼠标拖动图片，鼠标滚轮滚动放大缩小图片，添加的标记也会跟着移动。

2. 使用Canvas画布绘图

Canvas画布功能在图片div标签上覆盖一层Canvas绘图层，可通过该图层绘制图形。 为了使用Canvas画布功能，需要在初始化ZoomMarker对象时手动配置enable_canvas为true。

$('#zoom-marker-img').zoomMarker({
    src: "img/mountain.jpg",
    rate: 0.2,
    width: 400,
    max: 3000,
    markers:[
        {src:"img/marker.svg", x:200, y:200}
    ],
    enable_canvas: true
});

Canvas图层的大小和图片的实际像素大小相同。 如下例子在鼠标点击图像时，手动绘制一条从[100, 100]坐标出发，至点击坐标点结束的红线。

item.on("zoom_marker_mouse_click", function(event, position){
    // 画线
    const context = item.zoomMarker_Canvas();
    if(context !== null) {
        context.strokeStyle = 'red';
        context.moveTo(position.x, position.y);
        context.lineTo(100,100);
        context.stroke();
    }
});

Parameters参数

初始化时可传入以下可选参数。

param	function	default
rate	缩放速率	0.2
src	图片资源	null
width	图片加载宽度	500
min	图片最小宽度	300
max	图片最大宽度	null
markers	标记点参数数组	[]
marker_size	默认标记点尺寸	20
enable_drag	允许拖拽	true
auto_index_z	自动配置层级	true
enable_canvas	添加Canvas绘图层	false
zoom_lock	缩放锁定	false
move_limit	拖动锁边	false

rate

缺省值0.2 该浮点型参数决定了图片滚动放大时的速率，值越大图片缩放速度越快，范围{0, 1}。

src

缺省值null，不加载图片 图片加载的路径

width

用于配置图片加载后的宽度，请不要使用100%之类的相对宽度定位，会影响ZoomMarker的工作。 如果你要使图片的宽度与父节点宽度相同，可以使用jQuery的方法获取父节点宽度，或直接获取"zoom-marker-div"标签的宽度，如：

$("#zoom-marker-img").parent().width();
$("#zoom-marker-div").width();

min

限定图片缩放的最小宽度，默认最小宽度为300px。

max

限定图片缩放的最大宽度，默认不做限制。

markers

记录了标记点的参数，包含以下几个参数。

{
    src: "img/marker.png",   // (required)图片加载路径
    x: 500,                  // (required)标记点在图片中的X坐标
    y: 500,                  // (required)标记点在图片中的Y坐标
    click: function(object){
        // 点击回调方法，object为marker的jQuery对象
    }
}

marker_size

标记点尺寸只能为正方形，通过这个参数可以配置标记点的大小，你也可以在"zoomMarker_AddMarker"添加标记点方法中通过参数配置单个标记点的大小。

enable_drag

是否允许当前图像拖拽

auto_index_z

自动管理图像和标记点的层级信息，在点击和拖拽的时候自动将当前图像和标记点置顶

enable_canvas

添加Canvas绘图层，因为可能影响性能，默认关闭

zoom_lock

缩放锁定，开启则以图片中点作为缩放中点，默认关闭 关闭状态下以鼠标或双指缩放中心作为图片放大或缩小的中点

move_limit

拖动锁边，开启则只允许图片在父容器内部拖动

Methods方法

ZoomMarker的方法全都以"zoomMarker_"开头，直接在你的图片标签jQuery对象上使用jQuery插件的方法调用即可，如清空所有标记点：

    $("#viewArea").zoomMarker_CleanMarker();

name	function
zoomMarker_LoadImage(src)	加载图像
zoomMarker_Zoom(center, scale)	缩放图片
zoomMarker_Move(x, y)	移动图片
zoomMarker_AddMarker(marker)	添加标记点
zoomMarker_RemoveMarker(markerId)	删除标记点
zoomMarker_CleanMarker()	清空标记点
zoomMarker_GetPicSize()	获取记载图片尺寸
zoomMarker_EnableDrag(enable)	是否允许图像拖拽
zoomMarker_TopIndexZ()	图像和标记点置顶
zoomMarker_Canvas()	获取canvas绘图层上下文
zoomMarker_CanvasClean()	清空canvas画布
zoomMarker_ResetImage()	重置图像位置及大小
zoomMarker_ReloadMarkers()	刷新当前图像的所有标记点

zoomMarker_LoadImage(src)

用于加载图像，src传入图片URL或本地路径。

param	function
src	图像资源路径或URL

zoomMarker_Zoom(center, scale)

缩放图片。

param	function
center	缩放中心点，相对于document的绝对坐标
scale	缩放比例，浮点型，如1.5为缩放到原图的1.5倍大小

zoomMarker_Move(x, y)

移动图片位置，笛卡尔坐标系，左上角坐标为(0, 0)。

param	function
x	图片左上角的目标纵坐标
y	图片左上角的目标横坐标

zoomMarker_AddMarker(marker)

添加标记点并返回添加标记点的相关参数，marker的配置参数如下表所示。 配置中的"x"和"y"参数均为标记点在图像中的坐标位置。

param	function	detault	required
x	标记点在图像中的X坐标	null	Y
y	标记点在图像中的Y坐标	null	Y
src	标记点图标资源	null	Y
size	标记点图标尺寸	20	N
dialog	悬浮对话框	null	N
hint	标记点内部内容	null	N
click	标记点击回调	null	N
draggable	标记点可拖动开关	null	Y

(1) dialog

param	function	detault	required
value	对话框内容	""	N
style	CSS样式	{}	N
offsetX	对话框X坐标偏移	0	N
offsetY	对话框Y坐标偏移	0	N

(2) hint

param	function	detault	required
value	标记点内容	""	N
style	CSS样式	{}	N

(3) return函数返回对象

param	function
id	标记点ID
marker	标记点的jQuery对象
param	用户传入的标记点配置参数

zoomMarker_RemoveMarker(markerId)

删除标记点，传入标记点ID，ID可从"zoomMarker_AddMarker(marker)"返回结构体中的"id"项获取。

zoomMarker_CleanMarker()

清空所有标记点。

zoomMarker_GetPicSize()

获取加载图片的真实尺寸，只有当图片加载结束的时候才会返回正确的图片尺寸。

return函数返回对象

param	function
width	图片宽度
height	图片高度

zoomMarker_EnableDrag(enable)

设置是否允许图像拖动。

zoomMarker_TopIndexZ()

图像和对应的标记点有层级关系，通过这个方法将当前图像和标记点层级置顶。

zoomMarker_Canvas()

需要在初始化图像时配置enable_canvas参数为true。 获取Canvas的上下文context，通过Canvas绘图方法在图像上绘制图形。 需要注意的是，绘图坐标都是以图像的分辨率为基准。

zoomMarker_CanvasClean()

清空Canvas的绘图数据。

zoomMarker_ResetImage()

重置图像尺寸和位置，包括marker和canvas信息。

zoomMarker_ReloadMarkers()

有网友反馈在移动端加载新图片后，标记点会发生漂移，手动拖拽图片后图标位置恢复正常。
个人判断是因为不同浏览器的onload图像加载回调触发时间节点不一样导致的，因此添加这个接口，供用户手动重新加载标记点。

Event事件

通过"on"或"bind"监听ZoomMarker发送的事件。

// 监听图片资源加载结束消息，更新UI资源。
$('#zoom-marker-img').on("zoom_marker_img_loaded", function(event, size){
    console.log("image has been loaded with size: "+JSON.stringify(size));
    /** 更新UI操作 **/
    ...
});

name	function	param	detail
zoom_marker_img_load	图片开始加载	src	图片资源路径或URL
zoom_marker_img_loaded	图片已加载完成	size	图片尺寸
zoom_marker_click	标记点点击	markerObj	标记点对象
zoom_marker_mouse_click	图片点击	mouseObj	图片点击对象
zoom_marker_move_end	Marker移动结束	{x, y, markerObj}	位置及标记点组合对象

size

param	function
width	图片宽度
height	图片高度

markerObj

param	function
id	标记点ID
marker	标记点的jQuery对象
param	用户传入的标记点配置参数

mouseObj

param	function
pageX	点击位置在document中的X坐标
pageY	点击位置在document中的Y坐标
x	点击位置在图像坐标中的X坐标
y	点击位置在图像坐标中的Y坐标