uni-leaflet 官方文档

uni-leaflet 跨端、高性能的 Uni-App (Vue 3 TypeScript) 地图组件。在H5 端与App 端 (APP-PLUS)自动加载成熟强大的Leaflet.js生态App 端基于renderjs独立视图层驱动与手势防抖锁在微信小程序端自动无缝切换为纯原生Canvas 2D瓦片与矢量渲染引擎。一套代码三端极致体验完整使用文档与进阶教程请访问uni-leaflet 官方文档✨ 核心特性一套代码跨端自适应H5 端采用标准 Leaflet.js DOM 渲染支持完整 GIS 坐标变换与图层生态。App 端 (iOS / Android)采用 Leaflet.js Uni-Apprenderjs架构配合手势互斥锁Anti-Feedback Loop与图层增量 Diff 缓存彻底杜绝手势抖动与白屏闪烁体验媲美原生。微信小程序端采用底层 Canvas 2D 高性能离屏/视口瓦片调度支持 DPR 高分屏自适应内置 Canvas 原生矢量缩放控件零 DOM 遮挡。丰富多样的图标样式支持 (Marker Icons)Emoji 字符图标免网络请求轻量生动如️,,☕。PNG / JPG / 本地图片 / 网络 URL支持本地/static/icons/xxx.png相对路径、网络图片或 Base64 Data URI。SVG 矢量文件支持引用.svg静态文件无损缩放高分屏超清晰。SVG 内联代码支持直接传入svg.../svgXML 字符串支持动态渐变Gradient、自定义矢量图案与阴影。默认矢量 Pin内置优雅水滴 Pin支持自定义主题填充色 (color)。️多源底图即开即用高德地图 (AutoNavi)道路矢量、卫星影像、路网注记免 Token 极速加载。天地图 (Tianditu)矢量/影像/地形底图 透明地名道路注记图层叠加WMTS 标准。OpenStreetMap / CartoDB浅色/深色极简底图。多图层叠加与混合渲染支持卫星影像底图 透明地名道路注记图层叠加如天地图img_w cia_w、高德style6 style8。完整矢量要素与 Label 气泡标注点与图标 (Markers)支持自定义尺寸size、精准锚点anchor与永久/动态悬浮 Label。折线路线 (Polylines)支持实线、虚线 (dashArray)、颜色、线宽及中点 Label 标注。多边形区域 (Polygons)支持半透明填充、边框色及几何质心居中 Label 标注。辐射圆形 (Circles)基于米制半径换算像素支持居中 Label 标注。全手势与交互体验单指拖拽平移、双指多点缩放Pinch Zoom、双击居中放大、平滑动画平移 (panTo)。PC 端 / 开发者工具鼠标滚轮精准缩放以鼠标光标为锚点Pivot Point并自动阻止外层页面联动滚动。⚡动态响应式驱动深度响应 Vue 3 响应式数据变化支持接口异步请求后直接更新、追加或清空标注要素。️TypeScript 严格类型支持内置完整的类型声明定义。 平台支持平台渲染引擎底层机制状态H5 (Web / Mobile Browser)Leaflet.js标准 DOM / SVG / Canvas✅ 完美支持App (iOS / Android)Leaflet.jsrenderjs独立 Webview 视图层 手势防抖锁✅ 完美支持微信小程序 (MP-WEIXIN)Canvas 2D Engine原生 Canvas 2D 视口瓦片调度✅ 完美支持 安装# npmnpminstalluni-leaflet leaflet# pnpmpnpmadduni-leaflet leaflet# yarnyarnadduni-leaflet leaflet 快速上手1. 基础用法 (单文件组件内局部引入)template view classmap-container UniLeafletMap v-model:centercenter v-model:zoomzoom :tile-urltileUrl :subdomainssubdomains height600rpx clickonMapClick / /view /template script setup langts import { ref } from vue; import { UniLeafletMap } from uni-leaflet; import type { LatLngTuple } from uni-leaflet; const center refLatLngTuple([39.9042, 116.4074]); // 北京 const zoom ref(13); // 高德地图道路矢量切片免 Token极速加载 const tileUrl ref(https://wprd0{s}.is.autonavi.com/appmaptile?x{x}y{y}z{z}langzh_cnsize1scl1style7); const subdomains ref([1, 2, 3, 4]); function onMapClick(e: any) { console.log(点击坐标:, e.latLng); } /script style scoped .map-container { width: 100%; height: 600rpx; } /style2. 全局注册 (main.ts)import{createSSRApp}fromvue;importAppfrom./App.vue;importUniLeafletfromuni-leaflet;exportfunctioncreateApp(){constappcreateSSRApp(App);app.use(UniLeaflet);// 全局注册 UniLeafletMap 组件return{app};}3. 多图层叠加 (例如天地图卫星影像 文字地名注记)template UniLeafletMap :center[39.9163, 116.3972] :zoom13 :layerslayers height100vh / /template script setup langts import { ref } from vue; import { UniLeafletMap } from uni-leaflet; import type { TileLayerConfig } from uni-leaflet; const myTiandituToken YOUR_TIANDITU_TOKEN; const layers refTileLayerConfig[]([ // 1. 底层天地图卫星影像底图 (img_w) { id: img, url: https://t{s}.tianditu.gov.cn/img_w/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERimgSTYLEdefaultTILEMATRIXSETwFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tk${myTiandituToken}, subdomains: [0, 1, 2, 3, 4, 5, 6, 7], }, // 2. 顶层天地图文字地名注记 (cia_w - 透明 PNG) { id: cia, url: https://t{s}.tianditu.gov.cn/cia_w/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERciaSTYLEdefaultTILEMATRIXSETwFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tk${myTiandituToken}, subdomains: [0, 1, 2, 3, 4, 5, 6, 7], zIndex: 10, }, ]); /script4. 点图标 (Emoji / PNG / SVG 文件 / SVG 内联代码) 及矢量要素template UniLeafletMap refmapRef :center[39.9163, 116.3972] :zoom14 :markersmarkers :polylinespolylines :polygonspolygons :circlescircles overlay-clickonOverlayClick / /template script setup langts import { ref } from vue; import { UniLeafletMap } from uni-leaflet; import type { MarkerOptions, PolylineOptions, PolygonOptions, CircleOptions, OverlayClickEvent, } from uni-leaflet; // 1. 点标注 (支持 Emoji / PNG 图片 / SVG 矢量文件 / SVG 内联代码) const markers refMarkerOptions[]([ // A. Emoji 字符图标 { id: m1, latLng: [39.9163, 116.3972], title: 故宫博物院, icon: { text: ️, size: [34, 34] }, label: { text: 故宫博物院 (Emoji), offset: [0, -28] }, }, // B. PNG 图片图标 (支持 static 相对路径、网络 URL 或 Base64) { id: m2, latLng: [39.9242, 116.3995], title: 景山公园万春亭, icon: { url: /static/icons/pin-purple.png, size: [32, 40], anchor: [16, 40], // 底部尖端对齐 }, label: { text: 景山公园万春亭 (PNG), offset: [0, -32] }, }, // C. SVG 矢量文件图标 (无损缩放高分屏超清晰) { id: m3, latLng: [39.9100, 116.3910], title: 中山公园摄影打卡点, icon: { url: /static/icons/camera.svg, size: [36, 36], anchor: [18, 36], }, label: { text: 摄影打卡点 (SVG), offset: [0, -30] }, }, // D. SVG 内联代码 (直接传入 SVG 标签字符串支持动态渐变与任意矢量图形) { id: m4, latLng: [39.9045, 116.3895], title: 国家大剧院, icon: { svg: svg viewBox0 0 36 36 width36 height36 defs linearGradient idgTheater x10% y10% x2100% y2100% stop offset0% stop-color#ec4899/ stop offset100% stop-color#8b5cf6/ /linearGradient /defs circle cx18 cy18 r16 fillurl(#gTheater) stroke#ffffff stroke-width2/ text x18 y24 font-size16 text-anchormiddle fill#ffffff/text /svg, size: [36, 36], anchor: [18, 18], // 中心对齐 }, label: { text: 国家大剧院 (内联SVG), offset: [0, -26] }, }, ]); // 2. 路线折线 (带虚线与中点 Label) const polylines refPolylineOptions[]([ { id: l1, latLngs: [ [39.9295, 116.3972], [39.9163, 116.3972], [39.8985, 116.3972], ], color: #3b82f6, width: 5, label: 中轴线景观路线, }, ]); // 3. 多边形区域 (带质心 Label) const polygons refPolygonOptions[]([ { id: p1, latLngs: [ [39.9240, 116.3915], [39.9240, 116.4025], [39.9115, 116.4025], [39.9115, 116.3915], ], color: #ef4444, fillColor: rgba(239, 68, 68, 0.22), label: 故宫紫禁城核心区, }, ]); // 4. 圆形辐射范围 (米制半径) const circles refCircleOptions[]([ { id: c1, latLng: [39.9055, 116.3976], radius: 1000, // 1000 米 color: #10b981, fillColor: rgba(16, 185, 129, 0.18), label: 1km 核心辐射圈, }, ]); function onOverlayClick(e: OverlayClickEvent) { console.log(点击了要素:, e.type, e.data); } /script API 参考Props参数类型默认值说明v-model:center[number, number][39.9042, 116.4074]地图中心点经纬度[纬度, 经度]v-model:zoomnumber13地图缩放级别min-zoomnumber3最小缩放层级max-zoomnumber18最大缩放层级tile-urlstringOSM URL单图层瓦片模板地址subdomainsstring[][a, b, c]瓦片子域名轮换配置layersTileLayerConfig[]undefined多图层叠加配置数组按顺序自底向上叠加markersMarkerOptions[][]点标注数组polylinesPolylineOptions[][]折线路线数组polygonsPolygonOptions[][]多边形面数组circlesCircleOptions[][]圆形范围数组overlaysMapOverlaysundefined综合覆盖物对象widthstring100%地图宽度heightstring100%地图高度show-controlsbooleantrue是否显示右上方缩放控件按钮H5/App 为悬浮组件小程序为 Canvas 2D 顶层渲染MarkerIconOptions (图标详细配置)字段类型默认值说明textstringundefinedEmoji 字符或文字图标如️,,☕urlstringundefinedPNG / JPG / SVG 文件路径、网络 URL 或 Base64 Data URI如/static/icons/pin-blue.png、/static/icons/camera.svgsvgstringundefined原始 SVG XML 字符串支持动态渐变与任意矢量图形如svg viewBox0 0 36 36.../svghtmlstringundefined自定义 HTML 结构 (仅 H5 与 App renderjs 生效)colorstring#ef4444默认矢量 Pin 图钉的主题填充色size[number, number][32, 32]图标渲染尺寸[宽, 高](px)anchor[number, number]居中或底部图标锚点[x, y]。图钉尖部对齐常用[width/2, height]圆形徽章居中对齐常用[width/2, height/2]Events事件名参数说明ready(engine: IMapEngine) void地图引擎初始化完成时触发click({ latLng, point }) void点击地图空白区域时触发move({ center, zoom }) void地图平移漫游中持续触发moveend({ center, zoom }) void地图平移结束时触发zoom(zoom: number) void地图缩放中持续触发zoomend(zoom: number) void地图缩放结束时触发overlay-click(event: OverlayClickEvent) void点击任意点、线、面、圆要素时触发marker-click(marker: MarkerOptions) void点击点图标时触发polyline-click(polyline: PolylineOptions) void点击折线时触发polygon-click(polygon: PolygonOptions) void点击多边形时触发circle-click(circle: CircleOptions) void点击圆形时触发Methods (通过ref获取实例)方法名参数说明setCenter(center: LatLngTuple, animate?: boolean)设置地图中心点setZoom(zoom: number)设置缩放层级zoomIn()放大一级zoomOut()缩小一级panTo(center: LatLngTuple, duration?: number)平滑缓动平移至指定坐标setTileUrl(url: string, subdomains?: string[])切换单底图源setLayers(layers: TileLayerConfig[])动态切换多图层源setMarkers(markers: MarkerOptions[])动态更新点标注setPolylines(polylines: PolylineOptions[])动态更新折线setPolygons(polygons: PolygonOptions[])动态更新多边形setCircles(circles: CircleOptions[])动态更新圆形clearOverlays()清空所有覆盖物resize(width?: number, height?: number)重新计算视口尺寸与 DPR 适配getCenter()获取当前中心点[lat, lng]getZoom()获取当前缩放层级getNativeInstance()获取底层原生实例H5/App 为 LeafletL.map小程序为canvas节点