简介面向ArcGIS Engine二次开发的出图工具示例适合GIS开发者、测绘及相关专业学生解决地图布局中图名、比例尺、指北针、图例等要素的添加与成图输出问题。Demo基于ArcObjects SDK借助ITextElement、IScaleBar、ILegend等接口实现要素定制并封装了图片导出、文件保存和地图打印流程。资源包含49个文件以17个C#源码、6个资源文件与resx配置为主附带可执行的exe、项目解决方案、配置文件、PDB调试信息以及一份报告PDF压缩包仅829KB结构精简便于研读。目前已有5633人学习下载。通过源码可学习如何设置文本元素、比例尺分段、指北针方向、图例样式并掌握导出JPG、PNG、PDF及调用打印接口的细节同时参考报告中的步骤说明能减少踩坑、提升开发效率。 做ArcGIS二次开发出图这块几乎每个项目都绕不开。地图做完了领导要看、客户要交付、报告要插图总不能每次都让人打开ArcMap手动加图名、拖比例尺、调图例位置。我之前在项目里被这个反复折腾过后来干脆把整套流程封装成了一个出图工具从添加图名、比例尺、指北针、图例到导出图片、PDF甚至直接打印全部自动化处理一次配好样张之后换数据、换范围只需要点一下按钮。这篇文章就把这个工具的核心思路和实现细节完整复盘一遍里面涉及的原理和踩坑经验对用ArcEngine、ArcGIS Pro SDK做二次开发的朋友都有参考价值。1. 出图工具的定位与整体设计1.1 为什么需要专门做一个出图工具很多人觉得出图不就是“布局视图里加几个元素再导出”吗看起来简单真正落地完全不是一回事。首先ArcMap布局里的图名、比例尺、指北针、图例每个元素都有自己独立的样式配置和位置坐标手工调整一次至少三五分钟如果项目里有几十个专题图要出那工作量直接翻倍。其次地图范围一变比例尺的数值、图例的内容、图名的文字可能全要改手工操作非常容易漏改或者改错。我做这个工具的目标很明确把出图这件事从“每次手动摆弄”变成“一键生成、按需微调”。工具的运行逻辑也不复杂先把当前地图文档mxd载入读取地图范围然后按照预设的版面坐标往布局视图里添加各类制图元素最后根据用户选择的输出方式图片、PDF、打印机执行导出。这样一来制图模板的样式统一了出图效率也上来了。1.2 技术选型与整体架构这个工具我选的是C# ArcGIS Engine10.8版本环境开发原因很直接我用这个组合最熟而且AE的ArcObjects对象模型对布局和制图的支持已经很成熟。如果你用的是ArcGIS Pro那对应的是ArcGIS Pro SDKAPI风格有差异但思路上完全互通——核心都是围绕地图内容、布局页面、页面元素这三个层面来组织代码。整体架构分成四层数据准备层打开或新建mxd获取IMap对象和Layer集合。页面管理层设置页面尺寸IPageLayout、地图框位置IMapFrame、版面坐标。元素添加层负责添加图名、比例尺、指北针、图例全部走IGraphicsContainer接口。输出层封装了导出图片、导出PDF、直接打印三种出口。这样分层做的好处是改动互不干扰。比如工具刚开始只支持导出PNG后来要加PDF不需要动前面的元素添加逻辑只要扩展输出层就行。这个架构我后面维护了很长时间一直很顺手。2. 搞懂出图前必须掌握的核心对象关系2.1 布局视图里到底在操作什么做这个工具之前我建议先把ArcGIS的页面布局模型理清楚否则写代码时会很懵。在ArcMap里数据视图你看的是地图本身但切到布局视图后你看到的是一张“纸”地图只是这张纸上的一个框。这个框叫MapFrame地图框而往纸上放的所有东西——图名、比例尺、图例、指北针——全部是Element元素。这里最关键的一点这些制图元素并不是挂在“地图”上的而是挂在“页面”上的。也就是说代码里你要获取的容器是IPageLayout不是IMap。实际开发时一般是先拿到IActiveView然后通过ActiveView的FocusMap获取地图同时通过ActiveView.GraphicsContainer拿到元素容器再通过同一套对象操作布局页面。逻辑关系不弄明白后面添加元素时经常会发现元素加进去了但布局视图里看不到就是因为拿错了容器。2.2 必须熟练掌握的几个ArcObjects接口具体到代码实现以下接口出现的频率最高IActiveView不管是数据视图还是布局视图都要通过它来刷新、输出。IGraphicsContainer所有页面元素的容器AddElement和DeleteElement就靠它。IMapFrame承载地图的那个框图例、比例尺这类MapSurround最终都要挂到它身上。IMapSurroundFrame图例、比例尺等“地图附属物”的载体。IElement所有页面元素的统一父接口图名ITextElement、比例尺IScaleBar、指北针IMarkerNorthArrow都从它派生。把这几层关系理顺之后写代码就清晰了。添加任何元素本质上都是创建元素对象 → 配置元素样式和位置 → 通过IGraphicsContainer加到页面里 → 刷新视图。3. 四类制图元素的添加细节与参数设置3.1 图名创建文本元素并精确控制位置图名是最简单的一个核心是ITextElement和ITextSymbol。先创建TextElementClass再设置TextSymbol的字体、字号、颜色最后把字符串放进去。位置控制要特别注意ArcObjects里的位置参数是页面的坐标系通常以页面单位PageUnits为准默认情况下是英寸或者毫米视页面设置来定。我常用的做法是直接把图名放在页面顶部居中X坐标为页面宽度的一半Y坐标为页面高度减去一个固定上边距。这个位置信息可以通过IPageLayout的Page属性拿。之所以用代码算位置而不是写死一个值是因为不同项目的图纸尺寸不一样A4和A0的绝对坐标肯定不同动态计算才能保证通用性。字体我一般选黑体或宋体字号16到20磅具体看图纸幅面。代码片段如下ITextElement textElement new TextElementClass(); textElement.Text 土地利用现状图; ITextSymbol textSymbol new TextSymbolClass(); textSymbol.Font new StdFontClass { Name 黑体, Size 18 }; textSymbol.Color ColorHelper.CreateRgbColor(0, 0, 0); textElement.Symbol textSymbol; IElement element textElement as IElement; element.Geometry pageRectangle; // 页面对应位置的Envelope graphicsContainer.AddElement(element, 0);这里有个小坑如果设置了Geometry却没有设置对齐方式文字默认按左下角对齐。对于图名这种要居中的场景最好用IElement的属性或者给Geometry传入合适的Envelope让文字在框内居中排布控制起来更精确。3.2 比例尺既要有数值又要有“看得见的尺子”比例尺在出图里是一个比较讲究的元素因为它不仅关系到图纸的可读性还关系到数据的可信度。实现时有两种可选方案比例尺文本只在图上显示“1:50000”这类文字简单但不够直观。比例尺条绘制成一条带刻度的杆状图形专业感强也是制图规范里更推荐的方式。我这个工具实现的是比例尺条并且用的是AlternatingScaleBar交错黑白分段的样式制图里最常见。关键点是创建比例尺条后必须绑定它对应的地图——通过IScaleBar接口的Map属性赋值。这样ArcObjects才会根据当前地图的MapScale属性自动计算分段数和每段代表的实际距离。IScaleBar scaleBar new AlternatingScaleBarClass(); scaleBar.Map pMap; // 绑定地图比例尺才会自动感知比例 scaleBar.ResizeHint ResizeHintClass.NoResize; IMapSurroundFrame surroundFrame mapFrame.CreateSurroundFrame(scaleBar as IMapSurround, pageEnv);这里要提一个非常重要的经验比例尺条创建后必须从IMapFrame的CreateSurroundFrame方法生成MapSurroundFrame然后再添加到GraphicsContainer。如果你直接把ScaleBar当普通Element加进去比例尺很可能变成灰色不可交互状态或者比例数值始终是1。这个坑我第一次写的时候折腾了大半天才弄清楚。再说一下单位问题。很多人在代码里设置比例尺长度后发现显示出来的数字不对原因是地图的单位和页面单位没配对。比如数据是经纬度度页面单位是毫米那比例尺数值计算出来会非常奇怪。我的解决方法是在创建比例尺前先统一设置IMap的MapUnits并且把比例尺条上的Division、Subdivisions这些属性设置为合理的整数值比如主刻度分成4段、次刻度分成2段保证视觉美观和数值合理。3.3 指北针用样式库还是用自定义符号指北针的实现相对独立它不涉及数据计算纯粹是页面装饰元素。ArcObjects里提供了IMarkerNorthArrow接口可以通过ESRI.ArcGIS.Carto库调用内置的几种指北针样式。但实际项目里内置样式经常不满足出图规范这时候可以考虑自定义符号。我的工具里用的是内置样式加旋转角度设置。需要注意的是指北针默认朝正北0度如果地图框本身做了旋转指北针的角度也必须跟着旋转否则就会和图上地物方向对不上。这块可以通过IMapFrame的MapRotation参数来读取地图旋转角然后同步给指北针的Angle属性。IMarkerNorthArrow northArrow new MarkerNorthArrowClass(); northArrow.Angle Math.PI * pMapFrame.MapRotation / 180.0; IMapSurroundFrame nsFrame pMapFrame.CreateSurroundFrame(northArrow as IMapSurround, nEnv); graphicsContainer.AddElement(nsFrame as IElement, 0);指北针的位置我一般放在地图框右上角稍微离框边缘留一点空隙不要紧贴。这是因为很多专题图的右上角习惯放图例或者统计图指北针如果在右上角挡到内容调整起来很麻烦。我一般把位置参数抽象成配置项方便不同项目动态调整。3.4 图例动态生成与样式整理图例是所有元素里最容易出问题的一个因为它不是静态内容而是根据当前地图里的图层和符号动态生成的。图例的实现逻辑是先创建一个MapSurroundLegend对象然后遍历地图里的图层为每个可见且勾选显示图例的图层创建一个LegendItem最后把Legend挂在MapFrame上。核心难点在于图例内容的动态同步。我最初的版本只做了首次生成结果用户换了一个图层后图例没跟着变只能删除重建体验很差。后来我改成在每次出图前强制刷新图例先删除原有的图例项再遍历当前图层集合重新添加。虽然多了一步删除操作但换来的是图例内容永远和当前地图一致。ILegend legend new LegendClass(); for (int i 0; i pMap.LayerCount; i) { ILayer layer pMap.get_Layer(i); if (layer.Visible) { ILegendItem item new LegendItemClass(); item.Layer layer; item.ShowLayerName true; legend.AddItem(item); } } IMapSurroundFrame legendFrame pMapFrame.CreateSurroundFrame(legend as IMapSurround, legEnv);图例的样式设置同样不能忽略。LegendFormat里的标题文字一般是“图例”两个字、边框颜色、背景色、分段间隙都要在代码里统一预设否则默认样式会非常粗糙。我用的是标题加粗、无边框、背景白色、行距紧凑这样放在图上不抢眼又不失规范。4. 导出图片、文件与打印的实现要点4.1 导出图片分辨率、格式与透明背景图片导出是最常用的功能核心用的是IActiveView.Output方法。这个方法会按照你设置的输出分辨率Dpi和输出矩形范围把当前视图渲染成图片。实现上需要先创建ExportPicture对象设置导出格式PNG、JPG、TIFF都支持然后调用Output方法写入文件。分辨率的设置直接决定了图片清晰度。屏幕显示的话96到150 Dpi足够但如果图片要用于印刷必须设置到300 Dpi以上。要注意分辨率和图片文件大小的平衡一张A3幅面300 Dpi的PNG体积轻松超过50MB对报告插图和微信传阅都不太友好。我一般按用途分两档报告插图用200 Dpi的JPG印刷输出用300 Dpi的TIFF。IExport export new ExportPictureClass(); export.ExportFilename outputPath; export.Resolution 300; IEnvelope envelope pActiveView.Extent; pActiveView.Output(export, 300, ref envelope, null);顺带提一下透明背景。如果导出的图片要叠加到其他文档或地图服务上常常需要背景透明这个时候PNG格式是最合适的JPG不支持透明通道。如果你既要印刷级清晰度又想要透明背景PNG也能满足只是文件会更大。4.2 导出PDF矢量输出更实用相比图片PDF在很多场景下更好用因为它默认是矢量格式放大不模糊而且可以进行二次编辑。ArcObjects里导出PDF用的是ExportPDF类方法套路和ExportPicture类似。需要注意的地方是PDF导出的参数里有嵌入字体选项如果图纸里用了特殊字体而未嵌入其他机器打开PDF时可能会字体替换导致版面错乱。实际项目中我见过至少三次因为字体没嵌入而被打回来的案例所以我在工具里把字体嵌入选项设置成强制开启同时提供色域选择RGB还是CMYK。常规交付选RGB就行印刷出片才需要CMYK这个选项我也放到了配置里用的时候按需勾选。4.3 直接打印页面尺寸匹配是关键打印功能最初我没有做后来客户提出“能不能直接打”才补上的。用ArcEngine打印最简洁的方法是使用PrintDialog选择一个打印机然后通过IFormattedSnapshot和IPrintDialog接口直接输出。但有一个非常麻烦的问题——打印机纸型和地图页面尺寸不一致。举个例子如果布局页是A3横向而选中的打印机默认纸是A4直接打印会缩版比例尺、图名全部失调。解决办法是在打印前先通过IQueryPageSize接口把打印机纸张尺寸读出来修改IPageLayout的Page属性来适配纸张。或者反过来保持页面尺寸不变打印时选择“适应纸张”选项。这两种方式我都集成过最终推荐的是反向适配即页面跟随纸张变化这样打印出来的效果和屏显完全一致出图比例也不会变形。5. 常见问题与踩坑记录5.1 License初始化失败与版本不一致这个工具刚做完时我遇到的第一类报错就是License相关问题。常见的有“You are not licensed for ArcGIS for Desktop Advanced”和“Unable to initialize ArcGIS Engine”。这类问题绝大多数不是因为功能代码写错了而是License初始化代码没配对。ArcGIS的License是绑定产品等级的如果只绑定了ArcGIS Engine的Standard许可却调用了Advanced等级的接口就会报错。我的解决方法是工具启动时同时初始化Engine和Desktop的许可并且用IAoInitialize的IsProductCodeAvailable先检测当前环境支持的产品代码再决定初始化哪个等级。这样在部署到新机器时也能自动适配少一次环境排查。5.2 图例不更新或显示空白图例显示空白最常见的原因是图层被设置为“不显示图例”。ArcGIS的图层属性里有一个“Display in legend”选项如果用代码动态添加的图层没有处理这个标志即使图层可见图例也可能为空。此外图例的更新时机也很关键。如果在地图范围变化后没有刷新图例图例内容可能还停留在上一帧数据造成内容与图示不符。我在工具里加了一个强制刷新机制每次点击“出图”按钮时先触发一次图例重建再执行导出。这个方法虽然简单粗暴但比依赖ArcObjects自身的缓存机制可靠得多实测两年没再出现过图例空白问题。5.3 中文字体显示异常或导出后变成方块中文字体问题在ArcGIS出图里非常普遍。原因主要是ArcObjects默认字体不一定包含中文字形“Arial”这种字体本身就没有中文字形渲染时就会变成乱码或方块。解决方法是所有涉及文本的元素图名、比例尺文字、图例标题都显式指定中文字体比如“宋体”“微软雅黑”或者“黑体”而不是用默认字体。另外还要注意字体设置最好在文本元素创建时就指定不要创建后再改因为某些TextSymbol的字体属性在元素被添加进容器后并不会自动触发重绘必须手动刷新视图才能生效很多时候我们排查“字体明明改了但显示没变”其实就是这个原因。5.4 输出图片全白或黑块输出图片全白或者出现黑块这个问题我排查过很久最后定位到两个原因。一是导出时传入的Envelope和当前视图的Extent不一致导致输出区域错位二是显卡渲染模式问题某些低配机器上ArcEngine的渲染引擎会把符号刷成黑色块。针对第一个原因我的写法是从IActiveView的ScreenDisplay拿到当前刷新的范围直接传给Output方法保证导出区域和视图完全一致。针对第二个原因通常把ActiveView的输出模式切换为高质量渲染或者减小输出分辨率就能解决。实在不行就重启ArcMap进程这多半是AE的非托管资源没释放干净。5.5 一键出图的最终操作体验工具做完后实际使用的操作流程就变成打开mxd → 设置输出目录 → 点击“一键出图”。系统自动完成数据范围刷新、图例刷新、四类元素动态添加、比例尺数值计算、最后按预设格式导出。整个流程在10秒内完成相比原来手动操作节省的时间非常可观。我在设计时特意保留了“手动微调”的余地。自动生成的元素只是初始状态用户仍然可以在布局视图中拖动调整位置、修改文字内容。这样既保证了效率也不剥夺制图人员最后的把握权。6. 扩展思路与个人经验总结这个工具从最初第一版只能添加图名到现在完整支持四元素动态生成和三种输出方式已经稳定运行了两年多。我最深的体会是出图工具的核心竞争力不在于某个单一功能有多强而在于元素的自动化联动。比例尺、图例都必须跟着地图内容动态变化光做一次性的静态添加在实际项目里根本不够用。另外一个值得尝试的扩展方向是批量出图。目前工具一次只处理一个mxd但实际项目里经常有“一个总图加十个分幅图”的场景。如果能把图幅列表和地图文档列表做成配置循环调用出图方法就能从单张出图升级为批量出图进一步释放生产力。如果你是刚开始接触ArcGIS二次开发出图我建议不要急着抄完整代码。先手动在ArcMap里走一遍添加图名、比例尺、指北针、图例的流程理解每一步在界面上操作时ArcObjects底层发生了哪些对象创建和属性赋值。有了这个操作认知再对照代码去理解会顺畅很多排查问题也更有的放矢。本文还有配套的精品资源点击获取