vue-leaflet使用教程（一）
第一章：vue-leaflet 简介和快速开始
1.1 什么是 vue-leaflet？
vue-leaflet 是一个专为 Vue 3 设计的地图组件库，它是对 Leaflet.js 的 Vue 封装。Leaflet 是一个开源的、轻量级的 JavaScript 地图库，而 vue-leaflet 让开发者能够以 Vue 组件的方式使用 Leaflet 的功能。
主要特点：
-
✅ 完全兼容 Vue 3：使用 Composition API 和最新的 Vue 3 特性
-
✅ 支持 SSR（服务端渲染）：与 Vue 2 版本不同，这个库完全支持 SSR
-
✅ 组件化开发：所有地图功能都封装为 Vue 组件，使用简单直观
-
✅ 响应式数据绑定：支持 v-model 双向绑定，如
v-model:zoom、v-model:center -
✅ TypeScript 支持：提供完整的类型定义
-
✅ 与 Leaflet API 兼容：组件属性基本与原生 Leaflet 选项保持一致
1.2 安装
使用 npm 安装
npm install leaflet @vue-leaflet/vue-leaflet --save使用 yarn 安装
yarn add leaflet @vue-leaflet/vue-leaflet使用 pnpm 安装
pnpm add leaflet @vue-leaflet/vue-leaflet注意：vue-leaflet 依赖于 leaflet，所以需要同时安装这两个包。
1.3 快速开始
第一步：导入 CSS
在使用 vue-leaflet 之前，必须先导入 Leaflet 的 CSS 样式文件。通常在你的入口文件（如 main.js 或 main.ts）中导入：
import "leaflet/dist/leaflet.css";
//如果你使用的是vite7.0之后的版本，添加下面的代码
import * as L from 'leaflet'
window.L = L第二步：创建第一个地图
下面是一个最简单的示例，创建一个显示 OpenStreetMap 的地图：
<template><div style="height: 600px; width: 800px"><l-map ref="map" v-model:zoom="zoom" :center="center" :useGlobalLeaflet="true"><l-tile-layerurl="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"layer-type="base"name="OpenStreetMap"></l-tile-layer></l-map></div></template><script>import "leaflet/dist/leaflet.css";import { LMap, LTileLayer } from "@vue-leaflet/vue-leaflet";export default {components: {LMap,LTileLayer,},data() {return {zoom: 13,center: [47.41322, -1.219482], // [纬度, 经度]};},};</script>代码说明：
-
<l-map>：地图容器组件，是所有地图组件的根组件-
v-model:zoom：双向绑定地图缩放级别 -
:center：地图中心点坐标，格式为[纬度, 经度] -
ref="map"：用于获取地图实例的引用
-
-
<l-tile-layer>：瓦片图层组件，用于显示底图-
url：瓦片图层的 URL 模板 -
layer-type="base"：指定为基础图层 -
name：图层名称
-
-
容器样式：地图容器必须有明确的高度和宽度，否则地图无法正常显示
1.4 组件导入方式
方式一：按需导入（推荐）
import { LMap, LTileLayer, LMarker } from "@vue-leaflet/vue-leaflet";这种方式可以减小打包体积，只导入需要的组件。
方式二：全局注册
import { LMap, LTileLayer, LMarker } from "@vue-leaflet/vue-leaflet";app.component("l-map", LMap);app.component("l-tile-layer", LTileLayer);app.component("l-marker", LMarker);1.5 可用的组件列表
vue-leaflet 提供了以下组件（按功能分类）：
核心组件
- LMap：地图容器
图层组件
-
LTileLayer：瓦片图层
-
LWmsTileLayer：WMS 瓦片图层
-
LImageOverlay：图片叠加层
-
LGridLayer：网格图层
标记和图标
-
LMarker：标记点
-
LIcon：自定义图标
矢量图形
-
LCircle：圆形
-
LCircleMarker：圆形标记
-
LPolyline：折线
-
LPolygon：多边形
-
LRectangle：矩形
弹窗和提示
-
LPopup：弹窗
-
LTooltip：提示框
控件组件
-
LControlZoom：缩放控件
-
LControlScale：比例尺控件
-
LControlLayers：图层切换控件
-
LControlAttribution：版权信息控件
-
LControl：自定义控件
数据图层
-
LGeoJson：GeoJSON 数据图层
-
LFeatureGroup：要素组
-
LLayerGroup：图层组
1.6 访问 Leaflet 原生 API
有时候你可能需要直接访问 Leaflet 的原生方法。可以通过组件的 leafletObject 属性来访问：
<template><l-map ref="map" @ready="onMapReady"><!-- 地图内容 --></l-map></template><script>export default {methods: {onMapReady(map) {// map 就是 Leaflet 的原生地图实例console.log("地图已就绪", map);// 可以使用所有 Leaflet 的原生方法map.setView([51.505, -0.09], 13);},},};</script>或者使用 ref：
<template><l-map ref="mapRef"><!-- 地图内容 --></l-map></template><script>export default {mounted() {this.$nextTick(() => {// 通过 ref 访问 leafletObjectconst map = this.$refs.mapRef.leafletObject;if (map) {map.setView([51.505, -0.09], 13);}});},};</script>重要提示：leafletObject 不会立即可用，需要等待地图初始化完成。可以使用：
-
@ready事件（推荐） -
$nextTick确保 DOM 更新完成
1.7 响应式数据绑定
vue-leaflet 支持 Vue 3 的双向绑定语法，可以轻松实现响应式更新：
<template><div><l-map v-model:zoom="zoom" v-model:center="center"><l-tile-layerurl="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"></l-tile-layer></l-map><div><p>缩放级别: {{ zoom }}</p><button @click="zoom++">放大</button><button @click="zoom--">缩小</button></div></div></template><script>export default {data() {return {zoom: 13,center: [47.41322, -1.219482],};},};</script>1.8 常见问题
Q1: 地图不显示怎么办？
检查清单：
-
✅ 是否导入了
leaflet/dist/leaflet.css？ -
✅ 地图容器是否有明确的高度和宽度？
-
✅ 是否正确设置了
center和zoom属性？
Q2: 标记图标显示不正常？
这是 webpack/vite 打包时的常见问题。vue-leaflet 已经内置了修复，但如果你遇到问题，可以手动修复：
import L from "leaflet";import icon from "leaflet/dist/images/marker-icon.png";import iconShadow from "leaflet/dist/images/marker-shadow.png";let DefaultIcon = L.icon({iconUrl: icon,shadowUrl: iconShadow,});L.Marker.prototype.options.icon = DefaultIcon;Q3: 如何在 SSR 环境中使用？
vue-leaflet 支持 SSR，但需要特殊配置。详见后续章节。