Leaflet은 지도용 JavaScript 라이브러리입니다. 홈페이지에서는 이를 "모바일 친화적인 대화형 지도를 위한 오픈 소스 JavaScript 라이브러리"라고 부릅니다.
단일 HTML 파일의 전단지 맵에는 전단지 스타일시트, 전단지 스크립트, 높이가 있는 <div>의 세 가지가 필요합니다. 몇 줄의 JavaScript를 작성한 다음 지도를 만들고 그 위에 내용을 넣으세요.
먼저 시도해 보세요. 지도를 드래그하고, 버튼으로 확대/축소하고, 아무 곳이나 클릭하여 좌표를 읽어보세요.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Leaflet map in one HTML file</title>
<!-- 1. Leaflet CSS first (pinned version) -->
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"
integrity="sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY=" crossorigin="">
<style>
body { margin: 0; font-family: system-ui, sans-serif; }
/* 2. The map div needs a height, or it is 0px tall */
#map { height: 380px; background: #eef3ea; }
</style>
</head>
<body>
<div id="map"></div>
<!-- 3. Leaflet JS after the CSS -->
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"
integrity="sha256-20nQCchB9co0qIjJZRGuk2/Z9VM+kNiyxNV1lvTlZBo=" crossorigin=""></script>
<script>
// 4. Create the map: centre [lat, lng] and zoom level
const map = L.map('map').setView([51.505, -0.09], 14);
// No tile layer here, so nothing loads from a tile server.
// A faint grid shows the map moving when you drag or zoom.
for (let i = -4; i <= 4; i++) {
L.polyline([[51.505 + i * 0.005, -0.13], [51.505 + i * 0.005, -0.05]], { color: '#c9d6c3', weight: 1 }).addTo(map);
L.polyline([[51.48, -0.09 + i * 0.008], [51.53, -0.09 + i * 0.008]], { color: '#c9d6c3', weight: 1 }).addTo(map);
}
// Shapes, each with a popup
L.circle([51.508, -0.11], { radius: 500, color: '#d33', fillOpacity: 0.25 })
.addTo(map).bindPopup('A circle with a 500 m radius');
L.polygon([[51.509, -0.08], [51.503, -0.06], [51.51, -0.047]], { color: '#2a6' })
.addTo(map).bindPopup('A polygon');
L.circleMarker([51.5, -0.09], { radius: 9, color: '#fff', weight: 2, fillColor: '#1f6feb', fillOpacity: 1 })
.addTo(map).bindPopup('<b>Hello!</b><br>Drag, zoom, or click the map.').openPopup();
// Click anywhere: show the coordinates
map.on('click', function (e) {
L.popup().setLatLng(e.latlng)
.setContent('You clicked ' + e.latlng.lat.toFixed(4) + ', ' + e.latlng.lng.toFixed(4))
.openOn(map);
});
</script>
</body>
</html>
이 예에는 의도적으로 아래에 거리 지도가 없습니다. 거리 지도는 다른 서버의 이미지 타일에서 가져오며 아래 타일 섹션에서 다룹니다.
가장 작은 작업 페이지
모든 전단지 페이지에는 다음 순서로 동일한 네 부분이 있습니다.
<head>의 전단지 CSS.- 높이가 있는 지도 div(예:
#map { height: 400px; }) - 전단지 스크립트, CSS 뒤.
L.map('map')를 호출하고 레이어를 추가하는 스크립트.
이것은 Leaflet 빠른 시작 가이드의 페이지를 하나의 파일로 묶은 것입니다. 여기에는 OpenStreetMap 타일 레이어가 포함되어 있으므로 컴퓨터에서 열어 거리 지도를 확인하세요.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"
integrity="sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY=" crossorigin="">
<style>#map { height: 400px; }</style>
</head>
<body>
<div id="map"></div>
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"
integrity="sha256-20nQCchB9co0qIjJZRGuk2/Z9VM+kNiyxNV1lvTlZBo=" crossorigin=""></script>
<script>
const map = L.map('map').setView([51.505, -0.09], 13);
L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
maxZoom: 19,
attribution: '© <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a>'
}).addTo(map);
L.marker([51.5, -0.09]).addTo(map).bindPopup('Hello world!').openPopup();
</script>
</body>
</html>
setView는 [latitude, longitude]와 확대/축소 수준으로 중심을 차지합니다. 숫자가 높을수록 더 가까이 확대됩니다.
어떤 버전과 어떤 스크립트 태그인지
Leaflet 다운로드 페이지에는 2023년 5월 18일에 출시된 Leaflet 1.9.4가 현재 안정 버전으로 나열되어 있습니다. 또한 2025년 8월 16일에 출시된 Leaflet 2.0.0-alpha.1이 시험판으로 나열되어 있습니다.
같은 페이지에는 무료 CDN unpkg, cdnjs 및 jsDelivr에서 Leaflet을 사용할 수 있다고 나와 있습니다. 위의 태그는 다운로드 페이지에서 unpkg에 대해 제공하는 태그입니다.
| 부품 | 무엇을 위한 것인가 |
|---|---|
URL의 leaflet@1.9.4 |
버전을 고정하여 파일이 변경되지 않도록 합니다. |
integrity="sha256-..." |
해시와 일치하지 않으면 브라우저가 파일을 거부합니다. |
crossorigin="" |
다른 사이트의 파일에 대한 무결성 검사에 필요합니다. |
leaflet.css |
타일, 컨트롤 및 팝업 위치 지정 |
CSS와 JS 태그를 해시와 함께 한 쌍으로 복사합니다. 해시는 하나의 정확한 파일에 속하므로 다른 모든 버전을 차단합니다.
전단지 자체는 오픈 소스입니다. GitHub 저장소에는 라이센스가 BSD-2-Clause로 나열되어 있습니다.
지도가 비어 있습니다. div에 높이를 지정하세요.
내부에 아무것도 없는 <div>의 높이는 0px입니다. Leaflet은 div의 크기에 맞게 지도를 그리기 때문에 높이가 없는 div는 아무 것도 표시하지 않으며 콘솔에도 오류가 없습니다.
아래 두 맵 모두 정확히 동일한 코드를 실행합니다. CSS만 다릅니다.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Map div with and without a height</title>
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"
integrity="sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY=" crossorigin="">
<style>
body { margin: 0; padding: 12px; font-family: system-ui, sans-serif; font-size: 14px; background: #f4f5f7; }
.cols { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; }
.col { background: #fff; border-radius: 10px; padding: 10px; box-shadow: 0 3px 10px rgba(0, 0, 0, .08); min-width: 0; }
h3 { margin: 0 0 4px; font-size: 14px; }
code { font-size: 12px; background: #eef1f5; padding: 1px 4px; border-radius: 4px; }
.map { background: #eef3ea; outline: 2px dashed #e08a2c; }
#with { height: 220px; outline-color: #2a9d55; }
.size { margin: 6px 0 0; color: #555; }
</style>
</head>
<body>
<div class="cols">
<div class="col">
<h3>No height</h3><code>#without { }</code>
<div id="without" class="map"></div>
<p class="size" id="size1"></p>
</div>
<div class="col">
<h3>Height set</h3><code>#with { height: 220px; }</code>
<div id="with" class="map"></div>
<p class="size" id="size2"></p>
</div>
</div>
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"
integrity="sha256-20nQCchB9co0qIjJZRGuk2/Z9VM+kNiyxNV1lvTlZBo=" crossorigin=""></script>
<script>
// Exactly the same code for both maps
['without', 'with'].forEach(function (id, i) {
const map = L.map(id).setView([51.505, -0.09], 13);
L.circle([51.505, -0.09], { radius: 600, color: '#1f6feb' }).addTo(map);
const h = document.getElementById(id).offsetHeight;
document.getElementById('size' + (i + 1)).textContent = 'Map div height: ' + h + 'px';
});
</script>
</body>
</html>
빠른 시작 가이드에서는 "지도 컨테이너에 정의된 높이가 있는지 확인하세요"라고 직접적으로 설명합니다. 모든 CSS 높이는 픽셀 또는 vh 단위로 작동합니다.
관련 사례: 탭 내부의 지도, 아코디언 또는 페이지가 로드될 때 숨겨지는 대화 상자. 현재 div에는 크기가 없습니다. 표시한 후 바로 map.invalidateSize()를 호출하면 Leaflet이 div를 다시 측정합니다.
타일: 거리 지도의 출처
거리 지도는 전단지의 일부가 아닙니다. L.tileLayer는 타일이라고 불리는 정사각형 이미지를 타일 서버에서 다운로드해 나란히 배치한다. 드래그하고 확대/축소하면 더 많은 항목이 요청됩니다.
Leaflet 참조에는 대부분의 타일 서버에 속성이 필요하다고 나와 있습니다. OpenStreetMap 타일 사용 정책에서는 "OpenStreetMap 라이선스 귀속을 지도에 명확하게 표시"할 것을 요구합니다. 또한 타일 서버는 기부금으로 자금을 조달하며 가용성은 "최선의 노력"이라고 말합니다.
모양이 다릅니다. L.circle, L.polygon, L.polyline 및 L.circleMarker는 페이지의 Leaflet에 의해 SVG로 그려집니다. leaflet.js가 로드되면 서버에서 아무것도 필요하지 않습니다.
기본 핀인 L.marker도 이미지입니다. 전단지는 leaflet.css 옆에 있는 images 폴더에서 marker-icon.png를 로드합니다. 두 가지 옵션에는 이미지 파일이 필요하지 않습니다.
// A round pin, size in pixels
L.circleMarker([51.5, -0.09], { radius: 8 }).addTo(map);
// Any HTML as a pin, styled with your own CSS
const icon = L.divIcon({ className: '', html: '<div class="pin">1</div>', iconSize: [26, 26] });
L.marker([51.5, -0.09], { icon: icon }).addTo(map);
평면도와 같은 도면만 있는 지도의 경우 HTML의 지도 마커는 라이브러리가 전혀 없는 버전을 표시합니다.
위도가 먼저, 경도가 두 번째
전단지는 포인트를 [lat, lng]로 사용합니다. 지도 데이터의 일반적인 파일 형식인 GeoJSON은 지도 데이터를 반대 방향으로 저장합니다. GeoJSON 사양인 RFC 7946에 따르면 처음 두 요소는 "경도와 위도... 정확히 그 순서대로"입니다.
GeoJSON을 L.geoJSON에 전달하면 Leaflet이 순서를 올바르게 읽습니다.
const data = {
type: 'Feature',
properties: { name: 'Meeting point' },
geometry: { type: 'Point', coordinates: [-0.09, 51.5] } // lng, lat
};
L.geoJSON(data).bindPopup('Meeting point').addTo(map);
GeoJSON에서 L.marker 또는 setView로 복사할 때만 숫자를 직접 교체하세요. 방문자 자신의 위치를 포인트로 변환하려면 Geolocation API를 참조하세요.
완성된 예: 타일이 없는 장소 지도
전단지는 평면 계획에서도 작동합니다. crs: L.CRS.Simple를 사용하면 Leaflet 참조에 평평한 표면 지도의 경우 "경도와 위도를 x와 y로 직접 매핑"한다고 나와 있습니다. 좌표는 도면의 일반 단위입니다.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Venue map with Leaflet</title>
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"
integrity="sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY=" crossorigin="">
<style>
body { margin: 0; font-family: system-ui, sans-serif; font-size: 14px; background: #eceef1; }
.app { display: grid; grid-template-columns: 1fr 200px; gap: 10px; padding: 10px; }
#map { height: 400px; border-radius: 10px; background: #f7f5ef; }
ul { list-style: none; margin: 0; padding: 0; }
li button {
width: 100%; text-align: left; font: inherit; margin-bottom: 6px; padding: 8px 10px;
border: 0; border-radius: 8px; background: #fff; cursor: pointer;
}
li button.on { background: #1f6feb; color: #fff; }
.pin {
width: 26px; height: 26px; border-radius: 50%; background: #1f6feb; color: #fff;
border: 2px solid #fff; box-shadow: 0 1px 4px rgba(0, 0, 0, .4);
display: grid; place-items: center; font-weight: 700; font-size: 13px; box-sizing: border-box;
}
@media (max-width: 560px) {
.app { grid-template-columns: 1fr; }
#map { height: 300px; }
ul { display: grid; grid-template-columns: 1fr 1fr; gap: 0 6px; }
}
</style>
</head>
<body>
<div class="app">
<div id="map"></div>
<ul id="list"></ul>
</div>
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"
integrity="sha256-20nQCchB9co0qIjJZRGuk2/Z9VM+kNiyxNV1lvTlZBo=" crossorigin=""></script>
<script>
// A flat plan, not the globe: CRS.Simple uses plain x/y units
const map = L.map('map', { crs: L.CRS.Simple, minZoom: -2, maxZoom: 2, zoomSnap: 0.25 });
// The floor plan is an inline SVG, 1000 x 600 units
const W = 1000, H = 600;
const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
svg.setAttribute('viewBox', '0 0 ' + W + ' ' + H);
svg.innerHTML =
'<rect x="10" y="10" width="980" height="580" rx="16" fill="#fff" stroke="#9aa3ad" stroke-width="6"/>' +
'<rect x="40" y="40" width="380" height="240" fill="#e7f0fb"/><text x="230" y="170" font-size="34" text-anchor="middle" fill="#5b6b7c">Main hall</text>' +
'<rect x="460" y="40" width="240" height="240" fill="#eaf6ee"/><text x="580" y="170" font-size="30" text-anchor="middle" fill="#5b6b7c">Room A</text>' +
'<rect x="740" y="40" width="220" height="240" fill="#eaf6ee"/><text x="850" y="170" font-size="30" text-anchor="middle" fill="#5b6b7c">Room B</text>' +
'<rect x="40" y="320" width="560" height="240" fill="#fdf1e3"/><text x="320" y="450" font-size="34" text-anchor="middle" fill="#5b6b7c">Food court</text>' +
'<rect x="640" y="320" width="320" height="240" fill="#f2eefa"/><text x="800" y="450" font-size="30" text-anchor="middle" fill="#5b6b7c">Lobby</text>';
const bounds = [[0, 0], [H, W]];
L.svgOverlay(svg, bounds).addTo(map);
map.fitBounds(bounds);
// Places in SVG coordinates. y is flipped: Leaflet counts up from the bottom
const places = [
{ name: 'Registration', x: 800, y: 500, note: 'Badges from 8:30' },
{ name: 'Keynote stage', x: 230, y: 90, note: 'Opening talk at 9:30' },
{ name: 'Workshop 1', x: 580, y: 230, note: 'Room A, 11:00' },
{ name: 'Workshop 2', x: 850, y: 230, note: 'Room B, 14:00' },
{ name: 'Coffee', x: 120, y: 380, note: 'All day' },
{ name: 'Lunch', x: 420, y: 520, note: '12:30 to 13:30' }
];
const toLatLng = function (p) { return [H - p.y, p.x]; };
const list = document.getElementById('list');
places.forEach(function (p, i) {
// divIcon: an HTML pin, no image file
const icon = L.divIcon({ className: '', html: '<div class="pin">' + (i + 1) + '</div>', iconSize: [26, 26] });
const marker = L.marker(toLatLng(p), { icon: icon, title: p.name })
.addTo(map).bindPopup('<b>' + p.name + '</b><br>' + p.note);
const btn = document.createElement('button');
btn.textContent = (i + 1) + '. ' + p.name;
btn.addEventListener('click', function () {
map.flyTo(toLatLng(p), 0.5, { duration: 0.5 });
marker.openPopup();
});
marker.on('popupopen', function () { btn.classList.add('on'); });
marker.on('popupclose', function () { btn.classList.remove('on'); });
const li = document.createElement('li');
li.appendChild(btn);
list.appendChild(li);
});
// Click empty space to read coordinates, handy when adding places
map.on('click', function (e) {
L.popup().setLatLng(e.latlng)
.setContent('x ' + Math.round(e.latlng.lng) + ', y ' + Math.round(H - e.latlng.lat))
.openOn(map);
});
</script>
</body>
</html>
복사할 가치가 있는 네 가지 세부 사항:
- **
L.svgOverlay**는 사용자가 지정한 경계 위에 인라인<svg>를 배치하므로 계획이 지도와 함께 확대/축소 및 이동됩니다. fitBounds확대하여 모든 화면 너비에서 전체 계획을 표시합니다.- y축이 반전됩니다.
CRS.Simple에서는 y가 아래쪽부터 계산되므로H - y는 SVG 좌표에서 변환됩니다. - 목록은 버튼을 사용합니다. 각각
flyTo및openPopup를 호출하므로 계획은 키보드에서도 작동합니다.
여기에 있는 모든 내용은 페이지에 그려지므로 leaflet.js 이후에는 아무것도 다운로드되지 않습니다.
작동하지 않을 때
| 당신이 보는 것 | 원인 | 수정 |
|---|---|---|
| 전혀 없음, 오류 없음 | 지도 div에 높이가 없습니다. | #map에 높이를 설정하세요 |
| 페이지 아래로 흩어져 있는 타일 | leaflet.css가 없거나 로드하지 못했습니다. |
헤드에 CSS 링크 추가 |
L is not defined |
leaflet.js 이전에 스크립트가 실행됩니다. |
Leaflet 태그 뒤에 스크립트를 넣으세요. |
Map container not found |
L.map('map')는 div가 존재하기 전에 실행됩니다. |
div 아래에 스크립트를 넣으세요. |
| 탭 또는 대화 상자 내부의 회색 지도 | 지도가 생성될 때 div가 숨겨졌습니다. | 표시한 후 map.invalidateSize()에 전화하세요. |
| 스크립트 차단됨, 무결성 오류 | 해시와 파일이 일치하지 않습니다 | 다운로드 페이지에서 두 태그를 모두 복사하세요. |
| 마커가 잘못된 위치에 착륙함 | GeoJSON 순서의 좌표 | [lat, lng] 사용 |
| 핀 대신 깨진 이미지 | 마커 이미지가 로드되지 않았습니다. | L.circleMarker 또는 L.divIcon를 사용하세요. |
페이지에 아무것도 표시되지 않고 표가 도움이 되지 않는 경우 HTML JavaScript가 작동하지 않음에서 일반적인 확인 사항을 다룹니다.
링크로 공유하세요
지도는 설명하는 것보다 보여주는 것이 더 쉽습니다. 스크린샷을 드래그하거나 확대/축소할 수 없으며 .html 첨부 파일이 휴대폰에서 일반 코드로 열릴 수 있습니다.
작업 버전을 보내려면 페이지를 NOS 문서에 붙여넣고 공유 링크 만들기를 선택하세요. 링크할 HTML이 이를 안내합니다.
페이지는 작성된 대로 렌더링되고, leaflet.js 및 leaflet.css는 unpkg에서 로드되고 코드가 실행되므로 페이지를 받는 사람들은 계정 없이도 지도를 끌어서 확대/축소하고 클릭할 수 있습니다. 나중에 코드를 변경하면 동일한 링크에 새 버전이 표시됩니다.
계획해야 할 한 가지 제한 사항: NOS 공유 페이지는 다른 사이트의 이미지를 차단하므로 타일 레이어와 기본 핀 이미지가 여기에 표시되지 않습니다.
이 페이지의 예와 같은 모양, circleMarker, divIcon 핀 및 인라인 SVG 계획이 작동합니다. 대신 사람들을 실제 거리 주소로 보내려면 지도 위치 링크를 지도 서비스로 보냅니다.