Leaflet参考书API-Reference-0.7.7

--- layout: v2 title: Documentation bodyclass: api-page ---

API Reference

This reference reflects Leaflet 0.7.x. Check this list if you are using a different version of Leaflet.

Map

• Usage example
• Creation
• Options
• Events

Map Methods

• Modifying map state
• Getting map state
• Layers and controls
• Conversion methods
• Other methods

Map Misc

• Properties
• Panes

UI Layers

• Marker
• Popup

Raster Layers

• TileLayer
• TileLayer.WMS
• TileLayer.Canvas
• ImageOverlay

Vector Layers

• Path
• Polyline
• MultiPolyline
• Polygon
• MultiPolygon
• Rectangle
• Circle
• CircleMarker

Other Layers

• LayerGroup
• FeatureGroup
• GeoJSON

Basic Types

• LatLng
• LatLngBounds
• Point
• Bounds
• Icon
• DivIcon

Controls

• Control
• Zoom
• Attribution
• Layers
• Scale

Events

• Event methods
• Event objects

Utility

• Class
• Browser
• Util
• Transformation
• LineUtil
• PolyUtil

DOM Utility

• DomEvent
• DomUtil
• PosAnimation
• Draggable

Interfaces

• IHandler
• ILayer
• IControl
• IProjection
• ICRS

Misc

• global switches
• noConflict
• version

Map

The central class of the API — it is used to create a map on a page and manipulate it.

Usage example

// initialize the map on the "map" div with a given center and zoom
var map = L.map('map', {
	center: [51.505, -0.09],
	zoom: 13
});

Creation

Factory	Description
L.map( <HTMLElement|String> id, <Map options> options? )	Instantiates a map object given a div element (or its id) and optionally an object literal with map options described below.

Options

Map State Options

Option	Type	Default	Description
center	LatLng	null	Initial geographical center of the map.
zoom	Number	null	Initial map zoom.
layers	ILayer[]	null	Layers that will be added to the map initially.
minZoom	Number	null	Minimum zoom level of the map. Overrides any minZoom set on map layers.
maxZoom	Number	null	Maximum zoom level of the map. This overrides any maxZoom set on map layers.
maxBounds	LatLngBounds	null	When this option is set, the map restricts the view to the given geographical bounds, bouncing the user back when they try to pan outside the view. To set the restriction dynamically, use setMaxBounds method.
crs	CRS	L.CRS. EPSG3857	Coordinate Reference System to use. Don't change this if you're not sure what it means.

Interaction Options

Option	Type	Default	Description
dragging	Boolean	true	Whether the map be draggable with mouse/touch or not.
touchZoom	Boolean	true	Whether the map can be zoomed by touch-dragging with two fingers.
scrollWheelZoom	Boolean	true	Whether the map can be zoomed by using the mouse wheel. If passed 'center', it will zoom to the center of the view regardless of where the mouse was.
doubleClickZoom	Boolean	true	Whether the map can be zoomed in by double clicking on it and zoomed out by double clicking while holding shift. If passed 'center', double-click zoom will zoom to the center of the view regardless of where the mouse was.
boxZoom	Boolean	true	Whether the map can be zoomed to a rectangular area specified by dragging the mouse while pressing shift.
tap	Boolean	true	Enables mobile hacks for supporting instant taps (fixing 200ms click delay on iOS/Android) and touch holds (fired as contextmenu events).
tapTolerance	Number	15	The max number of pixels a user can shift his finger during touch for it to be considered a valid tap.
trackResize	Boolean	true	Whether the map automatically handles browser window resize to update itself.
worldCopyJump	Boolean	false	With this option enabled, the map tracks when you pan to another "copy" of the world and seamlessly jumps to the original one so that all overlays like markers and vector layers are still visible.
closePopupOnClick	Boolean	true	Set it to false if you don't want popups to close when user clicks the map.
bounceAtZoomLimits	Boolean	true	Set it to false if you don't want the map to zoom beyond min/max zoom and then bounce back when pinch-zooming.

Keyboard Navigation Options

Option	Type	Default	Description
keyboard	Boolean	true	Makes the map focusable and allows users to navigate the map with keyboard arrows and +/- keys.
keyboardPanOffset	Number	80	Amount of pixels to pan when pressing an arrow key.
keyboardZoomOffset	Number	1	Number of zoom levels to change when pressing + or - key.

Panning Inertia Options

Option	Type	Default	Description
inertia	Boolean	true	If enabled, panning of the map will have an inertia effect where the map builds momentum while dragging and continues moving in the same direction for some time. Feels especially nice on touch devices.
inertiaDeceleration	Number	3000	The rate with which the inertial movement slows down, in pixels/second2.
inertiaMaxSpeed	Number	1500	Max speed of the inertial movement, in pixels/second.
inertiaThreshold	Number	depends	Number of milliseconds that should pass between stopping the movement and releasing the mouse or touch to prevent inertial movement. 32 for touch devices and 14 for the rest by default.

Control options

Option	Type	Default	Description
zoomControl	Boolean	true	Whether the zoom control is added to the map by default.
attributionControl	Boolean	true	Whether the attribution control is added to the map by default.

Animation options

Option	Type	Default	Description
fadeAnimation	Boolean	depends	Whether the tile fade animation is enabled. By default it's enabled in all browsers that support CSS3 Transitions except Android.
zoomAnimation	Boolean	depends	Whether the tile zoom animation is enabled. By default it's enabled in all browsers that support CSS3 Transitions except Android.
zoomAnimationThreshold	Number	4	Won't animate zoom if the zoom difference exceeds this value.
markerZoomAnimation	Boolean	depends	Whether markers animate their zoom with the zoom animation, if disabled they will disappear for the length of the animation. By default it's enabled in all browsers that support CSS3 Transitions except Android.

Events

You can subscribe to the following events using these methods.

Event	Data	Description
click	MouseEvent	Fired when the user clicks (or taps) the map.
dblclick	MouseEvent	Fired when the user double-clicks (or double-taps) the map.
mousedown	MouseEvent	Fired when the user pushes the mouse button on the map.
mouseup	MouseEvent	Fired when the user releases the mouse button on the map.
mouseover	MouseEvent	Fired when the mouse enters the map.
mouseout	MouseEvent	Fired when the mouse leaves the map.
mousemove	MouseEvent	Fired while the mouse moves over the map.
contextmenu	MouseEvent	Fired when the user pushes the right mouse button on the map, prevents default browser context menu from showing if there are listeners on this event. Also fired on mobile when the user holds a single touch for a second (also called long press).
focus	Event	Fired when the user focuses the map either by tabbing to it or clicking/panning.
blur	Event	Fired when the map loses focus.
preclick	MouseEvent	Fired before mouse click on the map (sometimes useful when you want something to happen on click before any existing click handlers start running).
load	Event	Fired when the map is initialized (when its center and zoom are set for the first time).
unload	Event	Fired when the map is destroyed with remove method.
viewreset	Event	Fired when the map needs to redraw its content (this usually happens on map zoom or load). Very useful for creating custom overlays.
movestart	Event	Fired when the view of the map starts changing (e.g. user starts dragging the map).
move	Event	Fired on any movement of the map view.
moveend	Event	Fired when the view of the map stops changing (e.g. user stopped dragging the map).
dragstart	Event	Fired when the user starts dragging the map.
drag	Event	Fired repeatedly while the user drags the map.
dragend	DragEndEvent	Fired when the user stops dragging the map.
zoomstart	Event	Fired when the map zoom is about to change (e.g. before zoom animation).
zoomend	Event	Fired when the map zoom changes.
zoomlevelschange	Event	Fired when the number of zoomlevels on the map is changed due to adding or removing a layer.
resize	ResizeEvent	Fired when the map is resized.
autopanstart	Event	Fired when the map starts autopanning when opening a popup.
layeradd	LayerEvent	Fired when a new layer is added to the map.
layerremove	LayerEvent	Fired when some layer is removed from the map.
baselayerchange	LayerEvent	Fired when the base layer is changed through the layer control.
overlayadd	LayerEvent	Fired when an overlay is selected through the layer control.
overlayremove	LayerEvent	Fired when an overlay is deselected through the layer control.
locationfound	LocationEvent	Fired when geolocation (using the locate method) went successfully.
locationerror	ErrorEvent	Fired when geolocation (using the locate method) failed.
popupopen	PopupEvent	Fired when a popup is opened (using openPopup method).
popupclose	PopupEvent	Fired when a popup is closed (using closePopup method).

Methods for Modifying Map State

Method	Returns	Description
setView( <LatLng> center, <Number> zoom?, <zoom/pan options> options? )	this	Sets the view of the map (geographical center and zoom) with the given animation options.
setZoom( <Number> zoom, <zoom options> options? )	this	Sets the zoom of the map.
zoomIn( <Number> delta?, <zoom options> options? )	this	Increases the zoom of the map by delta (1 by default).
zoomOut( <Number> delta?, <zoom options> options? )	this	Decreases the zoom of the map by delta (1 by default).
setZoomAround( <LatLng> latlng, <Number> zoom, <zoom options> options? )	this	Zooms the map while keeping a specified point on the map stationary (e.g. used internally for scroll zoom and double-click zoom).
fitBounds( <LatLngBounds> bounds, <fitBounds options> options? )	this	Sets a map view that contains the given geographical bounds with the maximum zoom level possible.
fitWorld( <fitBounds options> options? )	this	Sets a map view that mostly contains the whole world with the maximum zoom level possible.
panTo( <LatLng> latlng, <pan options> options? )	this	Pans the map to a given center. Makes an animated pan if new center is not more than one screen away from the current one.
panInsideBounds( <LatLngBounds> bounds, <pan options> options? )	this	Pans the map to the closest view that would lie inside the given bounds (if it's not already), controlling the animation using the options specific, if any.
panBy( <Point> point, <pan options> options? )	this	Pans the map by a given number of pixels (animated).
invalidateSize( <Boolean> animate )	this	Checks if the map container size changed and updates the map if so — call it after you've changed the map size dynamically, also animating pan by default.
invalidateSize( <zoom/pan options> options )	this	Checks if the map container size changed and updates the map if so — call it after you've changed the map size dynamically, also animating pan by default. If options.pan is false, panning will not occur. If options.debounceMoveend is true, it will delay moveend event so that it doesn't happen often even if the method is called many times in a row.
setMaxBounds( <LatLngBounds> bounds	this	Restricts the map view to the given bounds (see map maxBounds option).
locate( <Locate options> options? )	this	Tries to locate the user using the Geolocation API, firing a locationfound event with location data on success or a locationerror event on failure, and optionally sets the map view to the user's location with respect to detection accuracy (or to the world view if geolocation failed). See Locate options for more details.
stopLocate()	this	Stops watching location previously initiated by map.locate({watch: true}) and aborts resetting the map view if map.locate was called with {setView: true}.
remove()	this	Destroys the map and clears all related event listeners.

Methods for Getting Map State

Method	Returns	Description
getCenter()	LatLng	Returns the geographical center of the map view.
getZoom()	Number	Returns the current zoom of the map view.
getMinZoom()	Number	Returns the minimum zoom level of the map.
getMaxZoom()	Number	Returns the maximum zoom level of the map.
getBounds()	LatLngBounds	Returns the LatLngBounds of the current map view.
getBoundsZoom( <LatLngBounds> bounds, <Boolean> inside? )	Number	Returns the maximum zoom level on which the given bounds fit to the map view in its entirety. If inside (optional) is set to true, the method instead returns the minimum zoom level on which the map view fits into the given bounds in its entirety.
getSize()	Point	Returns the current size of the map container.
getPixelBounds()	Bounds	Returns the bounds of the current map view in projected pixel coordinates (sometimes useful in layer and overlay implementations).
getPixelOrigin()	Point	Returns the projected pixel coordinates of the top left point of the map layer (useful in custom layer and overlay implementations).

Methods for Layers and Controls

Method	Returns	Description
addLayer( <ILayer> layer )	this	Adds the given layer to the map.
removeLayer( <ILayer> layer )	this	Removes the given layer from the map.
hasLayer( <ILayer> layer )	Boolean	Returns true if the given layer is currently added to the map.
eachLayer( <Function> fn, <Object> context? )	this	Iterates over the layers of the map, optionally specifying context of the iterator function. map.eachLayer(function (layer) { layer.bindPopup('Hello'); });
openPopup( <Popup> popup )	this	Opens the specified popup while closing the previously opened (to make sure only one is opened at one time for usability).
openPopup( <String> html | <HTMLElement> el, <LatLng> latlng, <Popup options> options? )	this	Creates a popup with the specified options and opens it in the given point on a map.
closePopup( <Popup> popup? )	this	Closes the popup previously opened with openPopup (or the given one).
addControl( <IControl> control )	this	Adds the given control to the map.
removeControl( <IControl> control )	this	Removes the given control from the map.

Conversion Methods

Method	Returns	Description
latLngToLayerPoint( <LatLng> latlng )	Point	Returns the map layer point that corresponds to the given geographical coordinates (useful for placing overlays on the map).
layerPointToLatLng( <Point> point )	LatLng	Returns the geographical coordinates of a given map layer point.
containerPointToLayerPoint( <Point> point )	Point	Converts the point relative to the map container to a point relative to the map layer.
layerPointToContainerPoint( <Point> point )	Point	Converts the point relative to the map layer to a point relative to the map container.
latLngToContainerPoint( <LatLng> latlng )	Point	Returns the map container point that corresponds to the given geographical coordinates.
containerPointToLatLng( <Point> point )	LatLng	Returns the geographical coordinates of a given map container point.
project( <LatLng> latlng, <Number> zoom? )	Point	Projects the given geographical coordinates to absolute pixel coordinates for the given zoom level (current zoom level by default).
unproject( <Point> point, <Number> zoom? )	LatLng	Projects the given absolute pixel coordinates to geographical coordinates for the given zoom level (current zoom level by default).
mouseEventToContainerPoint( <MouseEvent> event )	Point	Returns the pixel coordinates of a mouse click (relative to the top left corner of the map) given its event object.
mouseEventToLayerPoint( <MouseEvent> event )	Point	Returns the pixel coordinates of a mouse click relative to the map layer given its event object.
mouseEventToLatLng( <MouseEvent> event )	LatLng	Returns the geographical coordinates of the point the mouse clicked on given the click's event object.

Other Methods

Method	Returns	Description
getContainer()	HTMLElement	Returns the container element of the map.
getPanes()	MapPanes	Returns an object with different map panes (to render overlays in).
whenReady( <Function> fn, <Object> context? )	this	Runs the given callback when the map gets initialized with a place and zoom, or immediately if it happened already, optionally passing a function context.

Locate options

Option	Type	Default	Description
watch	Boolean	false	If true, starts continuous watching of location changes (instead of detecting it once) using W3C watchPosition method. You can later stop watching using map.stopLocate() method.
setView	Boolean	false	If true, automatically sets the map view to the user location with respect to detection accuracy, or to world view if geolocation failed.
maxZoom	Number	Infinity	The maximum zoom for automatic view setting when using `setView` option.
timeout	Number	10000	Number of milliseconds to wait for a response from geolocation before firing a locationerror event.
maximumAge	Number	0	Maximum age of detected location. If less than this amount of milliseconds passed since last geolocation response, locate will return a cached location.
enableHighAccuracy	Boolean	false	Enables high accuracy, see description in the W3C spec.

Zoom/pan options

Option	Type	Default	Description
reset	Boolean	false	If true, the map view will be completely reset (without any animations).
pan	pan options	-	Sets the options for the panning (without the zoom change) if it occurs.
zoom	zoom options	-	Sets the options for the zoom change if it occurs.
animate	Boolean	-	An equivalent of passing animate to both zoom and pan options (see below).

Pan options

Option	Type	Default	Description
animate	Boolean	-	If true, panning will always be animated if possible. If false, it will not animate panning, either resetting the map view if panning more than a screen away, or just setting a new offset for the map pane (except for `panBy` which always does the latter).
duration	Number	0.25	Duration of animated panning.
easeLinearity	Number	0.25	The curvature factor of panning animation easing (third parameter of the Cubic Bezier curve). 1.0 means linear animation, the less the more bowed the curve.
noMoveStart	Boolean	false	If true, panning won't fire movestart event on start (used internally for panning inertia).

Zoom options

Option	Type	Default	Description
animate	Boolean	-	If not specified, zoom animation will happen if the zoom origin is inside the current view. If true, the map will attempt animating zoom disregarding where zoom origin is. Setting false will make it always reset the view completely without animation.

fitBounds options

The same as zoom/pan options and additionally:

Option	Type	Default	Description
paddingTopLeft	Point	[0, 0]	Sets the amount of padding in the top left corner of a map container that shouldn't be accounted for when setting the view to fit bounds. Useful if you have some control overlays on the map like a sidebar and you don't want them to obscure objects you're zooming to.
paddingBottomRight	Point	[0, 0]	The same for bottom right corner of the map.
padding	Point	[0, 0]	Equivalent of setting both top left and bottom right padding to the same value.
maxZoom	Number	null	The maximum possible zoom to use.

Properties

Map properties include interaction handlers that allow you to control interaction behavior in runtime, enabling or disabling certain features such as dragging or touch zoom (see IHandler methods). Example:

map.doubleClickZoom.disable();

You can also access default map controls like attribution control through map properties:

map.attributionControl.addAttribution("Earthquake data © GeoNames");

Property	Type	Description
dragging	IHandler	Map dragging handler (by both mouse and touch).
touchZoom	IHandler	Touch zoom handler.
doubleClickZoom	IHandler	Double click zoom handler.
scrollWheelZoom	IHandler	Scroll wheel zoom handler.
boxZoom	IHandler	Box (shift-drag with mouse) zoom handler.
keyboard	IHandler	Keyboard navigation handler.
tap	IHandler	Mobile touch hacks (quick tap and touch hold) handler.
zoomControl	Control.Zoom	Zoom control.
attributionControl	Control.Attribution	Attribution control.

Map Panes

An object literal (returned by map.getPanes) that contains different map panes that you can use to put your custom overlays in. The difference is mostly in zIndex order that such overlays get.

Property	Type	Description
mapPane	HTMLElement	Pane that contains all other map panes.
tilePane	HTMLElement	Pane for tile layers.
objectsPane	HTMLElement	Pane that contains all the panes except tile pane.
shadowPane	HTMLElement	Pane for overlay shadows (e.g. marker shadows).
overlayPane	HTMLElement	Pane for overlays like polylines and polygons.
markerPane	HTMLElement	Pane for marker icons.
popupPane	HTMLElement	Pane for popups.