简介面向C# WinForm开发者的离线地图集成例程聚焦无外网环境下的地图展示与交互适合需要在局域网、内网部署或现场离线演示的中高级开发人员快速上手。工程基于GMap.NET搭建可直接打开解决方案编译运行源码包含7个C#文件窗体逻辑、程序入口、自定义经纬度类另有GMap.NET运行时所需的dll、项目配置、资源文件及可执行程序压缩包共41个文件、约38.7MB。例程覆盖离线瓦片加载、MapProvider与GMapControl属性设置、Marker标记绘制、多边形/圆形等图层对象、鼠标点击与移动事件处理以及经纬度实时显示等完整流程配套清晰的Winform项目结构便于对照学习后迁移到实际业务中。已有2363人学习下载对想掌握Winform离线地图开发、又缺少完整可运行示例的开发者有较高参考价值。 做上位机和桌面工具这些年地图这块的需求一直没断过。前阵子接了个物流调度项目现场没有外网业务车辆位置要显示在Winform界面里客户要求地图必须能离线加载。调研了一圈最后选了GMap.NET——一个开源的Windows桌面地图控件。正好也把折腾过程整理成例程估计不少同学会遇到同样的问题。这篇文章直接说怎么用C# Winform把离线地图跑起来从选型、瓦片数据准备、代码实现到打包部署把关键坑都过一遍。1. 为什么Windows桌面端做离线地图我选了GMap.NET1.1 桌面端离线地图的选型思路提到离线地图很多人第一反应是WebGIS那套Cesium、Leaflet、OpenLayers但放在Winform项目里还要嵌浏览器加载又重又麻烦。反过来看桌面原生方案除了GMap.NET之外还有SharpMap、MapWinGIS这些可SharpMap偏GIS分析MapWinGIS配置复杂GMap.NET最贴合轻量显示场景。它天生就是给.NET桌面应用用的一个控件拖上去就能显示地图支持打点、画线、多边形对做上位机定位、车队管理、设备监控这种项目刚好够用。我在选型时最看重三点一是控件和Winform的耦合度最好拖过来就能用二是离线方案是否成熟能不能让我自己控制缓存数据三是社区资源多不多遇到问题能不能找到参考。GMap.NET三点都满足而且MIT协议开源商用也没问题。如果你只是想在Winform里显示一张静态图片那确实没必要用它但只要你需要缩放、拖拽、动态打点用GMap.NET比自己去拼瓦片省太多事。1.2 GMap.NET的核心能力与限制GMap.NET是一个开源地图控件库支持Winform和WPF核心是提供了一套统一的地图Provider机制理论上可以对接Google、Bing、OpenStreetMap等在线底图也允许你切换到本地缓存模式。注意它本身不生产地图瓦片所有离线数据都是提前下载好或者导入好的缓存图片。也就是说GMap.NET扮演的角色是“看图引擎”数据源得你自己准备。它的限制也很明显它不是GIS引擎不能做复杂空间分析和坐标变换瓦片格式基本是PNG/JPG图片如果需要卫图加路网叠加得自己准备瓦片源。还有一点官方维护节奏不算快NuGet上版本分支比较多这点我会在下一节细说。选它之前把这些预期摆正后面就不会踩到“它怎么不加载shp”这种坑。总体而言对Windows桌面端的地图展示和点位管理GMap.NET是性价比很高的选择。2. 环境准备从NuGet到第一个能跑的地图控件2.1 项目配置与NuGet包安装先说项目环境。我这边用Visual Studio 2019创建的是.NET Framework 4.6.1的Winform项目。新项目也可以选.NET 5或6但做上位机的话我依然建议用Framework兼容性和第三方组件支持都更省心。项目建好后在NuGet里搜索GMap.NET通常会出现GMap.NET.Core和GMap.NET.WinForms两个包两个都要装。可以用包管理器控制台执行Install-Package GMap.NET.Core Install-Package GMap.NET.WinForms装完之后工具箱里会出现GMapControl控件直接拖到窗体上即可。如果你不想拖控件也可以代码创建GMapControl gMapControl new GMapControl(); gMapControl.Dock DockStyle.Fill; this.Controls.Add(gMapControl);这里要提醒一句版本问题。GMap.NET官方2.0之后维护没那么积极社区有分支比如GMap.NET.WinForms.NETCore不同分支命名空间和缓存结构有差异。我用的是经典2.0版代码命名空间是GMap.NET和GMap.NET.WindowsForms如果你用了新版或旧版using那里记得对应替换。这个看起来不起眼实际能节省一晚上排查时间。2.2 最小可用代码显示一张离线地图先把控件跑起来不急着谈数据。把GMapControl拖到窗体上命名成gMapControl然后在窗体Load事件里写基础配置private void Form1_Load(object sender, EventArgs e) { GMaps.Instance.Mode AccessMode.CacheOnly; // 只读缓存不联网 gMapControl.MapProvider GMapProviders.OpenStreetMap; gMapControl.DragButton MouseButtons.Left; gMapControl.MinZoom 3; gMapControl.MaxZoom 18; gMapControl.Zoom 12; gMapControl.Position new PointLatLng(31.2304, 121.4737); // 上海人民广场 gMapControl.ShowCenter false; }注意AccessMode.CacheOnly这个枚举它决定了GMap.NET不会走网络加载图片。这一步不设置等你把程序拿到没网的机器上地图控件会一直转圈或者灰屏。这段代码运行后如果界面是空白不用急因为本机还没有任何缓存瓦片。下面要解决的就是瓦片数据从哪来。3. 离线地图数据从哪来瓦片缓存原理与制作流程3.1 瓦片金字塔和坐标系离线地图背后的逻辑是瓦片金字塔地图被切成一张张固定大小的正方形图片通常是256x256像素。根据不同缩放级别Zoom整个地图被分成不同数量的瓦片。比如Zoom0时全世界可能只有少量瓦片Zoom1时变成4张Zoom12时一张城市地图就要几十万张。GMap.NET读取离线地图实际上就是按当前地图位置和缩放级别去本地缓存目录里找对应编号的瓦片图片。这个编号规则由Web墨卡托投影坐标换算而来。简单理解就是经纬度坐标经过投影变成平面坐标再按缩放级别切分成行列号。我们不需要自己算这套公式但理解它有助于准备数据。因为离线瓦片不是“一整张地图图片”而是一堆按行列号和缩放级别组织的文件。如果你要覆盖某个区域高层级和低层级的数量差异巨大所以下载前一定要规划好缩放级别范围。3.2 如何生成离线地图包先网络后离线是最省事的做法在没有网络限制的电脑上用GMap.NET的缓存功能把目标区域需要的瓦片遍历下载一遍形成本地DB文件或瓦片目录。具体做法是先把AccessMode设为ServerAndCache再使用GMap.NET Demo里的TilePrefetcher组件指定左上角、右下角坐标再指定最小和最大缩放级别它会自动把区域内的瓦片全部下载到缓存。这类工具在GMap.NET源码包里都有示例直接拖到你的工程里就能用。如果不追求用代码也可以先用桌面小工具下载瓦片。常见的有Mobile Atlas Creator、GMapCatcher下载时选择目标区域和缩放级别导成GMap.NET能识别的gmdb格式。这里有个细节不同工具导出的目录结构可能不一样GMap.NET最常见的离线缓存有两种一种是把瓦片存到单一DB文件里底层是SQLite适合分发管理另一种是存成文件夹方式目录结构类似z/x/y.png。如果手里是文件夹瓦片可以通过GMap.NET的缓存接口导入整理进DB如果手里直接是DB文件把它放到程序指定缓存目录就行。3.3 把离线包接到GMap.NET中在代码里指定缓存路径我一般会放在程序运行目录下的MapCache文件夹string cacheDir Path.Combine(Application.StartupPath, MapCache); if (!Directory.Exists(cacheDir)) Directory.CreateDirectory(cacheDir); GMaps.Instance.CacheLocation cacheDir;如果用的是默认SQLite缓存GMap.NET会在CacheLocation下自动创建对应Provider名称的DB文件。比如MapProvider是OpenStreetMap文件名大概率是OpenStreetMap.db。把下载好的同名DB文件放进去再将AccessMode设为CacheOnlyGMap.NET就会只读这个DB里的瓦片不再碰网络。这里要提醒一句CacheLocation路径不要放在Program Files这种需要管理员权限的目录下否则程序运行时会写不进去缓存索引地图加载慢还容易报错。另外不同Provider的DB文件不要混用。你把OpenStreetMap下载的缓存放到GoogleMap Provider下它找不到对应文件地图一样是灰的。统一Provider或者在上线前确认好程序里写死的Provider名称这点很重要。4. 核心功能实现点位标记、轨迹绘制和视野控制4.1 添加自定义Marker和Tooltip离线地图基础显示没问题后最常用的就是打点。比如在上位机里展示设备位置先用一个Overlay管理MarkerGMapOverlay markerOverlay new GMapOverlay(markers); gMapControl.Overlays.Add(markerOverlay);然后添加Markerprivate void AddMarker(PointLatLng pos, string title) { var marker new GMarkerGoogle(pos, GMarkerGoogleType.red_dot); marker.ToolTip new GMap.NET.WindowsForms.Markers.GMapToolTip(marker); marker.ToolTipText title; gMapControl.Overlays[0].Markers.Add(marker); }注意Marker坐标用的是PointLatLng纬度在前经度在后跟平时写经纬度字符串的顺序容易搞反。我一开始就把经度填到第一个参数导致点位跑到非洲去了。如果你需要自定义图标把GMarkerGoogleType换成自定义Bitmap即可比如传一个资源图片进去。自定义图片最好提前处理好锚点不然Marker会和坐标点错开半张图。4.2 绘制轨迹和GPS回放轨迹回放是物流、巡检类项目的刚需。GMap.NET里画线非常轻量初始化一个GMapRoute把轨迹点Add进去然后加到OverlayGMapOverlay routeOverlay new GMapOverlay(routes); gMapControl.Overlays.Add(routeOverlay); GMapRoute route new GMapRoute(route); foreach (PointLatLng point in trackPoints) { route.Points.Add(point); } route.Stroke new Pen(Color.Blue, 3); routeOverlay.Routes.Add(route);如果需要GPS实时回放上位机的串口或网口线程拿到数据后记得用Invoke回到UI线程再更新地图。直接在线程里改gMapControl.Position会抛跨线程异常而且就算不抛也会造成界面卡顿this.Invoke(new Action(() { gMapControl.Position lastPoint; AddMarker(lastPoint, 当前位置); }));用Timer每隔一秒更新一次效果会很自然。Marker也不用每次都重新Add可以维护一个队列保留最近N个点防止Marker过多影响性能。4.3 自适应缩放与居中显示有时候界面打开时如果直接给一个固定Position和Zoom地图往往不在想看的位置。更稳妥的做法是先计算所有点位的边界再让地图自动缩放。GMap.NET有现成的方法GMap.NET.RectLatLng rect new GMap.NET.RectLatLng( topLeft, bottomRight); gMapControl.Zoom gMapControl.GetMaxZoomToFitRect(rect); gMapControl.Zoom Math.Min(gMapControl.Zoom 1, gMapControl.MaxZoom); gMapControl.Position rect.LocationMiddle;这里的rect需要用两个对角坐标构造。我习惯在定位、画轨迹之后都调用一次确保用户打开窗口第一眼就能看到全部点位。要注意GetMaxZoomToFitRect返回的是能容纳整个区域的缩放级别但可能会略小所以通常手动加1级再用Math.Min限制在MaxZoom以内。5. 踩坑实录地图黑屏、缓存失效和缩放卡顿5.1 地图一直显示灰色或黑色最典型的问题就是地图控件灰屏。原因基本就几个一是AccessMode没有设成CacheOnly程序在无网环境下一去访问网络等待超时后界面就灰了二是缓存路径里根本没有对应Provider的瓦片三是Provider名称对不上。比如你用OpenStreetMap下载的缓存代码里却用GoogleMap作为Provider那GMap.NET会根据GoogleMap的命名去找另一个DB文件找不到自然白屏。解决办法是统一Provider或者直接把DB文件重命名成目标Provider对应的文件名。出现黑屏时先用最简单的场景验证断网状态下程序启动后立刻设置一个已知有缓存的坐标和缩放级别。如果还是黑就去MapCache目录里看文件大小是否为0或者用SQLite工具打开DB文件确认里面是不是有瓦片数据。这个方法能快速定位是“数据问题”还是“配置问题”。5.2 缓存目录读写权限和文件锁GMap.NET的SQLite缓存会在运行时给DB文件加锁如果程序异常退出下次启动可能提示数据库被占用或损坏。遇到这种情况可以把MapCache目录先备份再删掉损坏的DB文件重新放一个。如果同一时间多个窗体都创建了GMapControl不要在多个实例里分别去初始化GMaps.Instance单例模式下重复初始化容易出问题。还有一个容易被忽略的点调试运行时如果你在代码里改了缓存路径但上一次运行的进程还没结束文件一直被旧进程锁着新进程访问时就会失败。我建议调试时先打开任务管理器确认没有残留进程再修改缓存目录。另外杀毒软件有时会把DB文件当未知文件扫描导致首次加载慢可以提前将MapCache目录加入信任列表。5.3 高DPI与界面缩放“笔记本分辨率低”“Winform界面的高宽比过高”这些高频问题在地图控件上同样存在。GMap.NET在高DPI显示器上有时会鼠标偏移或地图模糊解决办法是在Program.cs里启用DPI感知[STAThread] static void Main() { SetProcessDpiAwarenessContext((int)DpiAwarenessContext.PER_MONITOR_AWARE_V2); Application.EnableVisualStyles(); Application.SetCompatibleTextRenderingDefault(false); Application.Run(new Form1()); }如果还不行就把窗体的AutoScaleMode改成Dpi并在设计器里关闭地图控件的AutoSize。我的经验是地图控件所在的窗体尽量不要用复杂布局尤其是Dock和Anchor混用否则缩放时Overlay里的Marker坐标会错位。地图这种控件越简单越稳定。5.4 若干性能优化技巧如果一个Overlay里塞了上千个Marker拖动地图就会卡。我实际优化过三层第一层把不可见区域的Marker临时隐藏只保留视野范围内的第二层不用GMarkerGoogle的默认ToolTip和Label改成自绘纹理减少GDI重绘第三层处理鼠标拖动事件时把地图更新频率节流到100ms一次。对于离线缓存不要一口气把高缩放级别全部下载到本地业务上用到哪一级就下哪一级不然DB文件能到几个GB软件启动扫描索引都要半天。性能优化最忌讳无脑做。先看是CPU高还是内存高CPU高多半是重绘问题内存高可能是加载了大图或过多Marker。GMapControl自带一些属性比如gMapControl.Manager.Mode和gMapControl.CacheLocation项目上线前最好做一次压力测试用1000个点位拖拽看是否流畅再针对性地优化。6. 部署与安装包让离线地图跟着程序走6.1 制作winform安装包时的关键点项目做完要发布Winform制作安装包一般用Visual Studio自带的InstallShield Limited Edition或者用WiX、Inno Setup。我推荐Inno Setup轻量、脚本可控、适合上位机快速打包。打包时要注意GMap.NET的GMap.NET.Core.dll、GMap.NET.WinForms.dll以及使用到的SQLite相关DLL都要一起打包。另外如果有Native依赖比如SQLite的x86/x64混合模式还要注意目标平台是AnyCPU还是x64别在32位机器上装64位数据库组件。Inno Setup脚本里最关键的一段是确保MapCache目录连同DB文件一起被安装并且可写[Files] Source: Release\MapCache\*; DestDir: {app}\MapCache; Flags: recursesubdirs createallsubdirs [Run] Filename: {app}\MyApp.exe; WorkingDir: {app}; Flags: nowait postinstall别直接安装到Program Files还不给写权限地图缓存需要写临时文件。要么安装时选择所有用户要么把MapCache放在用户目录或程序安装目录之外。6.2 发布版同时携带离线地图数据离线包分发还有一种常见做法不打进安装包而是首次启动时从服务器或U盘下载、拷贝。这样升级地图不用重装程序。实现上就是设置一个“初始化地图数据”按钮把压缩包解压到MapCache目录后再初始化GMapControl。这时要注意解压前先释放GMaps.Instance的缓存连接解压后再重新设置CacheLocation不然DB文件被占用会解压失败。如果需要从压缩包内读取文件数量做进度提示可用SharpCompress或System.IO.Compression遍历ZipEntry然后按文件个数显示进度。这个思路在离线地图数据包比较大时尤其有用用户体验会好很多。解压完成后还应做一次完整性校验比如检查目标DB文件是否存在、大小是否一致避免因为文件缺失导致现场地图变成灰屏。最后再说一个容易被忽略的点地图瓦片虽然叫离线但它的坐标系、Provider、DB文件版本都是有讲究的。我在项目里吃过一次亏开发环境用GMap.NET 2.0生成缓存现场机器上换了一个社区分支版本结果DB文件读不出来最后只能统一版本重新生成缓存。所以如果你准备长期维护这套东西建议把GMap.NET的DLL版本、瓦片生成工具、离线包文件名全部钉死在一个清单里升级任何一环都要重新验证。别让地图成为整个系统里那个“一碰就碎”的角落。本文还有配套的精品资源点击获取
C# Winform离线地图开发：GMap.NET从瓦片缓存到部署实战
简介面向C# WinForm开发者的离线地图集成例程聚焦无外网环境下的地图展示与交互适合需要在局域网、内网部署或现场离线演示的中高级开发人员快速上手。工程基于GMap.NET搭建可直接打开解决方案编译运行源码包含7个C#文件窗体逻辑、程序入口、自定义经纬度类另有GMap.NET运行时所需的dll、项目配置、资源文件及可执行程序压缩包共41个文件、约38.7MB。例程覆盖离线瓦片加载、MapProvider与GMapControl属性设置、Marker标记绘制、多边形/圆形等图层对象、鼠标点击与移动事件处理以及经纬度实时显示等完整流程配套清晰的Winform项目结构便于对照学习后迁移到实际业务中。已有2363人学习下载对想掌握Winform离线地图开发、又缺少完整可运行示例的开发者有较高参考价值。 做上位机和桌面工具这些年地图这块的需求一直没断过。前阵子接了个物流调度项目现场没有外网业务车辆位置要显示在Winform界面里客户要求地图必须能离线加载。调研了一圈最后选了GMap.NET——一个开源的Windows桌面地图控件。正好也把折腾过程整理成例程估计不少同学会遇到同样的问题。这篇文章直接说怎么用C# Winform把离线地图跑起来从选型、瓦片数据准备、代码实现到打包部署把关键坑都过一遍。1. 为什么Windows桌面端做离线地图我选了GMap.NET1.1 桌面端离线地图的选型思路提到离线地图很多人第一反应是WebGIS那套Cesium、Leaflet、OpenLayers但放在Winform项目里还要嵌浏览器加载又重又麻烦。反过来看桌面原生方案除了GMap.NET之外还有SharpMap、MapWinGIS这些可SharpMap偏GIS分析MapWinGIS配置复杂GMap.NET最贴合轻量显示场景。它天生就是给.NET桌面应用用的一个控件拖上去就能显示地图支持打点、画线、多边形对做上位机定位、车队管理、设备监控这种项目刚好够用。我在选型时最看重三点一是控件和Winform的耦合度最好拖过来就能用二是离线方案是否成熟能不能让我自己控制缓存数据三是社区资源多不多遇到问题能不能找到参考。GMap.NET三点都满足而且MIT协议开源商用也没问题。如果你只是想在Winform里显示一张静态图片那确实没必要用它但只要你需要缩放、拖拽、动态打点用GMap.NET比自己去拼瓦片省太多事。1.2 GMap.NET的核心能力与限制GMap.NET是一个开源地图控件库支持Winform和WPF核心是提供了一套统一的地图Provider机制理论上可以对接Google、Bing、OpenStreetMap等在线底图也允许你切换到本地缓存模式。注意它本身不生产地图瓦片所有离线数据都是提前下载好或者导入好的缓存图片。也就是说GMap.NET扮演的角色是“看图引擎”数据源得你自己准备。它的限制也很明显它不是GIS引擎不能做复杂空间分析和坐标变换瓦片格式基本是PNG/JPG图片如果需要卫图加路网叠加得自己准备瓦片源。还有一点官方维护节奏不算快NuGet上版本分支比较多这点我会在下一节细说。选它之前把这些预期摆正后面就不会踩到“它怎么不加载shp”这种坑。总体而言对Windows桌面端的地图展示和点位管理GMap.NET是性价比很高的选择。2. 环境准备从NuGet到第一个能跑的地图控件2.1 项目配置与NuGet包安装先说项目环境。我这边用Visual Studio 2019创建的是.NET Framework 4.6.1的Winform项目。新项目也可以选.NET 5或6但做上位机的话我依然建议用Framework兼容性和第三方组件支持都更省心。项目建好后在NuGet里搜索GMap.NET通常会出现GMap.NET.Core和GMap.NET.WinForms两个包两个都要装。可以用包管理器控制台执行Install-Package GMap.NET.Core Install-Package GMap.NET.WinForms装完之后工具箱里会出现GMapControl控件直接拖到窗体上即可。如果你不想拖控件也可以代码创建GMapControl gMapControl new GMapControl(); gMapControl.Dock DockStyle.Fill; this.Controls.Add(gMapControl);这里要提醒一句版本问题。GMap.NET官方2.0之后维护没那么积极社区有分支比如GMap.NET.WinForms.NETCore不同分支命名空间和缓存结构有差异。我用的是经典2.0版代码命名空间是GMap.NET和GMap.NET.WindowsForms如果你用了新版或旧版using那里记得对应替换。这个看起来不起眼实际能节省一晚上排查时间。2.2 最小可用代码显示一张离线地图先把控件跑起来不急着谈数据。把GMapControl拖到窗体上命名成gMapControl然后在窗体Load事件里写基础配置private void Form1_Load(object sender, EventArgs e) { GMaps.Instance.Mode AccessMode.CacheOnly; // 只读缓存不联网 gMapControl.MapProvider GMapProviders.OpenStreetMap; gMapControl.DragButton MouseButtons.Left; gMapControl.MinZoom 3; gMapControl.MaxZoom 18; gMapControl.Zoom 12; gMapControl.Position new PointLatLng(31.2304, 121.4737); // 上海人民广场 gMapControl.ShowCenter false; }注意AccessMode.CacheOnly这个枚举它决定了GMap.NET不会走网络加载图片。这一步不设置等你把程序拿到没网的机器上地图控件会一直转圈或者灰屏。这段代码运行后如果界面是空白不用急因为本机还没有任何缓存瓦片。下面要解决的就是瓦片数据从哪来。3. 离线地图数据从哪来瓦片缓存原理与制作流程3.1 瓦片金字塔和坐标系离线地图背后的逻辑是瓦片金字塔地图被切成一张张固定大小的正方形图片通常是256x256像素。根据不同缩放级别Zoom整个地图被分成不同数量的瓦片。比如Zoom0时全世界可能只有少量瓦片Zoom1时变成4张Zoom12时一张城市地图就要几十万张。GMap.NET读取离线地图实际上就是按当前地图位置和缩放级别去本地缓存目录里找对应编号的瓦片图片。这个编号规则由Web墨卡托投影坐标换算而来。简单理解就是经纬度坐标经过投影变成平面坐标再按缩放级别切分成行列号。我们不需要自己算这套公式但理解它有助于准备数据。因为离线瓦片不是“一整张地图图片”而是一堆按行列号和缩放级别组织的文件。如果你要覆盖某个区域高层级和低层级的数量差异巨大所以下载前一定要规划好缩放级别范围。3.2 如何生成离线地图包先网络后离线是最省事的做法在没有网络限制的电脑上用GMap.NET的缓存功能把目标区域需要的瓦片遍历下载一遍形成本地DB文件或瓦片目录。具体做法是先把AccessMode设为ServerAndCache再使用GMap.NET Demo里的TilePrefetcher组件指定左上角、右下角坐标再指定最小和最大缩放级别它会自动把区域内的瓦片全部下载到缓存。这类工具在GMap.NET源码包里都有示例直接拖到你的工程里就能用。如果不追求用代码也可以先用桌面小工具下载瓦片。常见的有Mobile Atlas Creator、GMapCatcher下载时选择目标区域和缩放级别导成GMap.NET能识别的gmdb格式。这里有个细节不同工具导出的目录结构可能不一样GMap.NET最常见的离线缓存有两种一种是把瓦片存到单一DB文件里底层是SQLite适合分发管理另一种是存成文件夹方式目录结构类似z/x/y.png。如果手里是文件夹瓦片可以通过GMap.NET的缓存接口导入整理进DB如果手里直接是DB文件把它放到程序指定缓存目录就行。3.3 把离线包接到GMap.NET中在代码里指定缓存路径我一般会放在程序运行目录下的MapCache文件夹string cacheDir Path.Combine(Application.StartupPath, MapCache); if (!Directory.Exists(cacheDir)) Directory.CreateDirectory(cacheDir); GMaps.Instance.CacheLocation cacheDir;如果用的是默认SQLite缓存GMap.NET会在CacheLocation下自动创建对应Provider名称的DB文件。比如MapProvider是OpenStreetMap文件名大概率是OpenStreetMap.db。把下载好的同名DB文件放进去再将AccessMode设为CacheOnlyGMap.NET就会只读这个DB里的瓦片不再碰网络。这里要提醒一句CacheLocation路径不要放在Program Files这种需要管理员权限的目录下否则程序运行时会写不进去缓存索引地图加载慢还容易报错。另外不同Provider的DB文件不要混用。你把OpenStreetMap下载的缓存放到GoogleMap Provider下它找不到对应文件地图一样是灰的。统一Provider或者在上线前确认好程序里写死的Provider名称这点很重要。4. 核心功能实现点位标记、轨迹绘制和视野控制4.1 添加自定义Marker和Tooltip离线地图基础显示没问题后最常用的就是打点。比如在上位机里展示设备位置先用一个Overlay管理MarkerGMapOverlay markerOverlay new GMapOverlay(markers); gMapControl.Overlays.Add(markerOverlay);然后添加Markerprivate void AddMarker(PointLatLng pos, string title) { var marker new GMarkerGoogle(pos, GMarkerGoogleType.red_dot); marker.ToolTip new GMap.NET.WindowsForms.Markers.GMapToolTip(marker); marker.ToolTipText title; gMapControl.Overlays[0].Markers.Add(marker); }注意Marker坐标用的是PointLatLng纬度在前经度在后跟平时写经纬度字符串的顺序容易搞反。我一开始就把经度填到第一个参数导致点位跑到非洲去了。如果你需要自定义图标把GMarkerGoogleType换成自定义Bitmap即可比如传一个资源图片进去。自定义图片最好提前处理好锚点不然Marker会和坐标点错开半张图。4.2 绘制轨迹和GPS回放轨迹回放是物流、巡检类项目的刚需。GMap.NET里画线非常轻量初始化一个GMapRoute把轨迹点Add进去然后加到OverlayGMapOverlay routeOverlay new GMapOverlay(routes); gMapControl.Overlays.Add(routeOverlay); GMapRoute route new GMapRoute(route); foreach (PointLatLng point in trackPoints) { route.Points.Add(point); } route.Stroke new Pen(Color.Blue, 3); routeOverlay.Routes.Add(route);如果需要GPS实时回放上位机的串口或网口线程拿到数据后记得用Invoke回到UI线程再更新地图。直接在线程里改gMapControl.Position会抛跨线程异常而且就算不抛也会造成界面卡顿this.Invoke(new Action(() { gMapControl.Position lastPoint; AddMarker(lastPoint, 当前位置); }));用Timer每隔一秒更新一次效果会很自然。Marker也不用每次都重新Add可以维护一个队列保留最近N个点防止Marker过多影响性能。4.3 自适应缩放与居中显示有时候界面打开时如果直接给一个固定Position和Zoom地图往往不在想看的位置。更稳妥的做法是先计算所有点位的边界再让地图自动缩放。GMap.NET有现成的方法GMap.NET.RectLatLng rect new GMap.NET.RectLatLng( topLeft, bottomRight); gMapControl.Zoom gMapControl.GetMaxZoomToFitRect(rect); gMapControl.Zoom Math.Min(gMapControl.Zoom 1, gMapControl.MaxZoom); gMapControl.Position rect.LocationMiddle;这里的rect需要用两个对角坐标构造。我习惯在定位、画轨迹之后都调用一次确保用户打开窗口第一眼就能看到全部点位。要注意GetMaxZoomToFitRect返回的是能容纳整个区域的缩放级别但可能会略小所以通常手动加1级再用Math.Min限制在MaxZoom以内。5. 踩坑实录地图黑屏、缓存失效和缩放卡顿5.1 地图一直显示灰色或黑色最典型的问题就是地图控件灰屏。原因基本就几个一是AccessMode没有设成CacheOnly程序在无网环境下一去访问网络等待超时后界面就灰了二是缓存路径里根本没有对应Provider的瓦片三是Provider名称对不上。比如你用OpenStreetMap下载的缓存代码里却用GoogleMap作为Provider那GMap.NET会根据GoogleMap的命名去找另一个DB文件找不到自然白屏。解决办法是统一Provider或者直接把DB文件重命名成目标Provider对应的文件名。出现黑屏时先用最简单的场景验证断网状态下程序启动后立刻设置一个已知有缓存的坐标和缩放级别。如果还是黑就去MapCache目录里看文件大小是否为0或者用SQLite工具打开DB文件确认里面是不是有瓦片数据。这个方法能快速定位是“数据问题”还是“配置问题”。5.2 缓存目录读写权限和文件锁GMap.NET的SQLite缓存会在运行时给DB文件加锁如果程序异常退出下次启动可能提示数据库被占用或损坏。遇到这种情况可以把MapCache目录先备份再删掉损坏的DB文件重新放一个。如果同一时间多个窗体都创建了GMapControl不要在多个实例里分别去初始化GMaps.Instance单例模式下重复初始化容易出问题。还有一个容易被忽略的点调试运行时如果你在代码里改了缓存路径但上一次运行的进程还没结束文件一直被旧进程锁着新进程访问时就会失败。我建议调试时先打开任务管理器确认没有残留进程再修改缓存目录。另外杀毒软件有时会把DB文件当未知文件扫描导致首次加载慢可以提前将MapCache目录加入信任列表。5.3 高DPI与界面缩放“笔记本分辨率低”“Winform界面的高宽比过高”这些高频问题在地图控件上同样存在。GMap.NET在高DPI显示器上有时会鼠标偏移或地图模糊解决办法是在Program.cs里启用DPI感知[STAThread] static void Main() { SetProcessDpiAwarenessContext((int)DpiAwarenessContext.PER_MONITOR_AWARE_V2); Application.EnableVisualStyles(); Application.SetCompatibleTextRenderingDefault(false); Application.Run(new Form1()); }如果还不行就把窗体的AutoScaleMode改成Dpi并在设计器里关闭地图控件的AutoSize。我的经验是地图控件所在的窗体尽量不要用复杂布局尤其是Dock和Anchor混用否则缩放时Overlay里的Marker坐标会错位。地图这种控件越简单越稳定。5.4 若干性能优化技巧如果一个Overlay里塞了上千个Marker拖动地图就会卡。我实际优化过三层第一层把不可见区域的Marker临时隐藏只保留视野范围内的第二层不用GMarkerGoogle的默认ToolTip和Label改成自绘纹理减少GDI重绘第三层处理鼠标拖动事件时把地图更新频率节流到100ms一次。对于离线缓存不要一口气把高缩放级别全部下载到本地业务上用到哪一级就下哪一级不然DB文件能到几个GB软件启动扫描索引都要半天。性能优化最忌讳无脑做。先看是CPU高还是内存高CPU高多半是重绘问题内存高可能是加载了大图或过多Marker。GMapControl自带一些属性比如gMapControl.Manager.Mode和gMapControl.CacheLocation项目上线前最好做一次压力测试用1000个点位拖拽看是否流畅再针对性地优化。6. 部署与安装包让离线地图跟着程序走6.1 制作winform安装包时的关键点项目做完要发布Winform制作安装包一般用Visual Studio自带的InstallShield Limited Edition或者用WiX、Inno Setup。我推荐Inno Setup轻量、脚本可控、适合上位机快速打包。打包时要注意GMap.NET的GMap.NET.Core.dll、GMap.NET.WinForms.dll以及使用到的SQLite相关DLL都要一起打包。另外如果有Native依赖比如SQLite的x86/x64混合模式还要注意目标平台是AnyCPU还是x64别在32位机器上装64位数据库组件。Inno Setup脚本里最关键的一段是确保MapCache目录连同DB文件一起被安装并且可写[Files] Source: Release\MapCache\*; DestDir: {app}\MapCache; Flags: recursesubdirs createallsubdirs [Run] Filename: {app}\MyApp.exe; WorkingDir: {app}; Flags: nowait postinstall别直接安装到Program Files还不给写权限地图缓存需要写临时文件。要么安装时选择所有用户要么把MapCache放在用户目录或程序安装目录之外。6.2 发布版同时携带离线地图数据离线包分发还有一种常见做法不打进安装包而是首次启动时从服务器或U盘下载、拷贝。这样升级地图不用重装程序。实现上就是设置一个“初始化地图数据”按钮把压缩包解压到MapCache目录后再初始化GMapControl。这时要注意解压前先释放GMaps.Instance的缓存连接解压后再重新设置CacheLocation不然DB文件被占用会解压失败。如果需要从压缩包内读取文件数量做进度提示可用SharpCompress或System.IO.Compression遍历ZipEntry然后按文件个数显示进度。这个思路在离线地图数据包比较大时尤其有用用户体验会好很多。解压完成后还应做一次完整性校验比如检查目标DB文件是否存在、大小是否一致避免因为文件缺失导致现场地图变成灰屏。最后再说一个容易被忽略的点地图瓦片虽然叫离线但它的坐标系、Provider、DB文件版本都是有讲究的。我在项目里吃过一次亏开发环境用GMap.NET 2.0生成缓存现场机器上换了一个社区分支版本结果DB文件读不出来最后只能统一版本重新生成缓存。所以如果你准备长期维护这套东西建议把GMap.NET的DLL版本、瓦片生成工具、离线包文件名全部钉死在一个清单里升级任何一环都要重新验证。别让地图成为整个系统里那个“一碰就碎”的角落。本文还有配套的精品资源点击获取
