Overview
This tutorial shows you how to customize the way users interact with your map. Learn to control whether your users can zoom and pan the map, and also whether the user's page scrolling actions take priority over the map's zooming and panning.
Demo: Preventing map pan and zoom on page scroll
When a user scrolls a page that contains a map, the scrolling action can unintentionally cause the map to zoom. The demo below allows the page to scroll normally, without affecting the map. Users can zoom the map by clicking the zoom controls. They can also zoom and pan by using two-finger movements on the map for touchscreen devices.
See the code below for this map.
function initMap() {
var locationRio = {lat: -22.915, lng: -43.197};
var map = new google.maps.Map(document.getElementById('map'), {
zoom: 13,
center: locationRio,
gestureHandling: 'cooperative'
});
var marker = new google.maps.Marker({
position: locationRio,
map: map,
title: 'Hello World!'
});
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
* element that contains the map. */
#map {
height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
height: 100%;
margin: 0;
padding: 0;
}
<!-- Replace the value of the key parameter with your own API key. --> <script async defer src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap"> </script>
Try it yourself
You can experiment with this code in JSFiddle by clicking the <> icon in the
top-right corner of the code window.
<!DOCTYPE html>
<html>
<head>
<style>
/* Always set the map height explicitly to define the size of the div
* element that contains the map. */
#map {
height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
height: 100%;
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<div id="map"></div>
<script>
function initMap() {
var locationRio = {lat: -22.915, lng: -43.197};
var map = new google.maps.Map(document.getElementById('map'), {
zoom: 13,
center: locationRio,
gestureHandling: 'cooperative'
});
var marker = new google.maps.Marker({
position: locationRio,
map: map,
title: 'Hello World!'
});
}
</script>
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>
</body>
</html>
Understand the code
The code above sets up a basic map, which may be similar to how you've created maps when
getting started with the Maps JavaScript API.
Copy the code above into a new index.html file, and open this file in a browser to
load the Maps JavaScript API, and put a map on a web page.
Click YOUR_API_KEY in the code sample, or follow the instructions to
get an API key. Replace
YOUR_API_KEY with your application's API key.
The code within the first script tags above is the starting point that runs the program by
creating an initMap function that initializes the map object. The code also sets a
specific latitude, longitude and zoom level.
function initMap() {
var locationRio = {lat: -22.915, lng: -43.197};
var map = new google.maps.Map(document.getElementById('map'), {
zoom: 13,
center: locationRio,
gestureHandling: 'cooperative'
});
The code above does the following:
- Sets the
gestureHandlingproperty tocooperativeto prevent one-finger movements from panning the map on touchscreen and mobile devices. The map pans only when users use two-finger movements.
Note: The gestureHandling property is set to
cooperative by default on pages that are scrollable. This means that the map
does not change when the user scrolls the page on touchscreen or mobile applications. Read
more about gesture handling below.
Demo: Disabling zoom and pan interactions
The example below disables zoom and pan on the map for desktop, touchscreen, and mobile devices.
Get the code
In your index.html file, replace the JavaScript code for the map
variable with the code below.
function initMap() {
var locationRio = {lat: -22.915, lng: -43.197};
var map = new google.maps.Map(document.getElementById('map'), {
zoom: 13,
center: locationRio,
gestureHandling: 'none',
zoomControl: false
});
Save and open the index.html file in a web browser to display a map that disables
zooming and panning.
Understand the code
The above JavaScript code does the following:
- Sets the
gestureHandlingproperty tononeto disable zooming by pinching the map on touchscreen and mobile devices. - Sets the
zoomControlproperty to false to remove the Zoom control buttons on the map.
Note: You can also disable zoom by setting the minZoom and maxZoom to
the same value. This also disables scroll on the map.
Demo: Enabling zoom and pan interaction
The example below demonstrates a map that users can zoom and pan on desktop, touchscreen, and mobile devices using the scroll wheel on a mouse, the zoom controls, a trackpad/mouse, or a touchscreen. This demo does not prevent the map from panning or zooming on page scroll.
Get the code
In your index.html file, replace the JavaScript code for the map
variable with the code below.
function initMap() {
var locationRio = {lat: -22.915, lng: -43.197};
var map = new google.maps.Map(document.getElementById('map'), {
zoom: 13,
center: locationRio,
gestureHandling: 'greedy'
});
Save and open the index.html file in a web browser to display a map that enables zoom
and pan interaction.
Understand the code
The code above sets the gestureHandling property to
greedy for touchscreen and mobile devices, to allow users to pan the map (up or down,
left or right) when the user swipes (drags on) the screen. In other words, both a one-finger swipe
and two-finger swipe can cause the map to pan.
Understand the terminology
This section defines terminology that's relevant to this tutorial, and various actions that users perform to interact with a map.
- Zoom: The action that changes the scale of the map.
- For desktop web apps:
- Click the + or - buttons on the Zoom control.
- Double click using your mouse or trackpad.
- Scroll using your mouse or pinch using your trackpad.
- For mobile web apps:
- You can also pinch the screen to zoom in and out.
- Double-tap the screen to zoom in.
- Pan/Drag: The action of dragging a map while keeping it at the same scale. Another common term for the pan action is drag.
- For desktop web apps:
- Click and hold your mouse or trackpad, then drag the maps by moving your mouse or finger. Release to stop panning.
- Use your arrow keys: up for north, right for east, down for south and left for west.
- For mobile web apps:
- Use two fingers to move the map. Note: You can use one finger to pan/drag the map,
if the
gestureHandlingproperty is set togreedy. drag: Repeatedly fired while the user drags the map.dragstart: Fired when the user starts dragging the map.dragend: Fired when the user stops dragging the map.- Page scroll: The action of moving the displayed web page up, down, or across on a desktop or mobile screen.
- For desktop/non-touchscreen devices:
- Use your mouse or trackpad to move the scroll bar on the webpage.
- Roll the mouse scroll wheel forwards or backwards to scroll the webpage.
- Move your fingers up or down on the trackpad to scroll the webpage.
- Use the mouse scroll wheel to move the webpage up or down.
- For mobile web apps:
- Move your finger up or down on the screen on touchscreen devices to scroll the page.
- Map controls: Elements on the user interface that allow user interaction with the map, like the zoom buttons or street view pegman. Learn more about controls in the developer guides.
- The zoom control: This control displays
+ and - buttons for changing the zoom level of the map.
This control appears by default at the bottom right corner of the map.
See the image of the zoom control in this section.
gestureHandling: A setting within the Maps JavaScript API that allows developers to control how the API handles gestures on the map. For mobile web in particular, users may swipe the touchscreen, intending to scroll the page, but change the scale of the map instead. Developers can optimize this user experience by using thegestureHandlingoption in the MapOptions object. The available values forgestureHandlingare below:greedy: The map always pans (up or down, left or right) when the user swipes (drags on) the screen. In other words, both a one-finger swipe and a two-finger swipe cause the map to pan.cooperative: The user must swipe with one finger to scroll the page and two fingers to pan the map. If the user swipes the map with one finger, an overlay appears on the map, with a prompt telling the user to use two fingers to move the map. On desktop applications, users can zoom or pan the map by scrolling while pressing a modifier key (the ctrl or ⌘ key).none: This option disables panning and pinching on the map for mobile devices, and dragging of the map on desktop devices.auto(default): Depending on whether the page is scrollable, the Maps JavaScript API sets thegestureHandlingproperty to eithercooperativeorgreedyas below:- Set to
cooperativeif the page body is bigger than the map window, or if the Maps JavaScript API cannot determine the page size (for example, if it's in an iframe). - Set to
greedy, if the page body is not bigger than the map window and it's unlikely that the user needs to scroll.
The fullscreen control is visible by default on mobile devices, so users can easily enlarge the map. When the map is in fullscreen mode, users can pan the map using one or two fingers. Note: iOS doesn't support the fullscreen feature. The fullscreen control is therefore not visible on iOS devices.
- Set to
The following restrictions and limitations apply to the behavior made available in the
gestureHandlingoption:Touch-sensitive devices only: The
gestureHandlingoptions apply only if the user is viewing the page on a device that supports a touch interface.Note: An exception to this limitation is when viewing maps that have
gestureHandlingset tononeon desktop devices. Thenoneoption disables panning and pinching on the map for mobile devices, and dragging of the map on desktop devices.- Touch events only: The
gestureHandlingoptions do not apply to mouse or pen events. - Not for signed-in maps: The
gestureHandlingoptions do not apply to maps with sign-in enabled.
Note: The signed-in feature is deprecated, and no longer supported in versions 3.28 and higher of the Maps JavaScript API. - Not for Street View: The
gestureHandlingoptions do not apply to the Street View service.
The Maps JavaScript API fires the following events, among others, when the user pans/drags the map:
See the guide to events and the reference for more information.
Yardım mı gerekiyor?