迟子real1. 多行注记在GIS应用中的核心价值
在地理信息系统（GIS）领域，注记（Annotation）是地图表达中不可或缺的要素。与普通标签不同，多行注记能够实现更复杂的地物标注需求，特别是在以下场景中：
- 道路名称标注（包含主路名和辅路名）
- 建筑物复合信息标注（如"XX大厦\n建筑面积：5000㎡"）
- 行政区划多级标注（省-市-区三级名称堆叠）
- 管线设施的多属性标注（压力值/管径/材质分行显示）
传统单行注记在处理这类需求时存在明显局限：要么信息显示不全，要么需要创建多个注记要素导致管理困难。而通过几何对象集合创建多行注记，可以实现：
- 空间关系精确控制：每个文本行都能独立设置位置偏移，避免文字重叠
- 样式统一管理：所有文本行共享样式属性，修改时只需调整一次
- 要素关联性强：多行内容作为一个整体要素存在，选择、移动、编辑更便捷
实际项目中我们遇到过这样的案例：某城市规划局需要在地图上标注"历史建筑保护名录"，要求每处建筑标注包含名称、年代、保护等级三行信息。采用传统方法需要创建三个分离的文本要素，而使用几何对象集合方案后，管理效率提升了60%以上。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. ArcGIS Pro SDK开发环境准备
2.1 基础环境配置
要使用ArcGIS Pro SDK进行多行注记开发，需要确保开发环境满足以下条件：
- ArcGIS Pro版本：建议使用2.8及以上版本（本文示例基于3.0版本）
- Visual Studio：2019或2022，需安装".NET桌面开发"工作负载
- SDK安装：
bash复制# 通过Esri官网获取对应版本的SDK安装包 ArcGISProSDK_NET_30_XXXX.exe /quiet - 项目模板：使用ArcGIS Pro Add-in项目模板创建基础框架
2.2 关键程序集引用
在解决方案中需要添加以下核心引用：
xml复制<Reference Include="ArcGIS.Core"/>
<Reference Include="ArcGIS.Desktop.Framework"/>
<Reference Include="ArcGIS.Desktop.Mapping"/>
2.3 开发调试配置
在项目属性中设置调试参数：
xml复制<StartAction>Program</StartAction>
<StartProgram>C:\Program Files\ArcGIS\Pro\bin\ArcGISPro.exe</StartProgram>
<StartArguments>/config:ProProject.ppkx</StartArguments>
常见问题：如果遇到"无法加载ArcGIS.Core.dll"错误，通常是因为SDK版本与Pro版本不匹配。建议通过ArcGIS Pro内置的SDK版本检查工具确认兼容性。
3. 几何对象集合的核心数据结构
3.1 多行注记的几何构成
在ArcGIS Pro SDK中，多行注记本质上是由多个文本几何体组成的复合要素。其核心类结构如下：
mermaid复制classDiagram
class AnnotationFeature{
+Geometry Geometry
+Symbol Symbol
+IDictionary<string,object> Attributes
}
class Geometry{
<<abstract>>
}
class Multipoint{
+List<MapPoint> Points
}
AnnotationFeature "1" *-- "1" Geometry
Geometry <|-- Multipoint
实际编码时需要关注的关键对象：
-
MapPoint：定义每个文本行的基准位置
csharp复制var basePoint = MapPointBuilder.CreateMapPoint( x: 120.35, y: 30.45, spatialReference: SpatialReferences.WGS84); -
Multipoint：作为几何容器
csharp复制var multiPoint = new MultipointBuilderEx(); multiPoint.AddPoint(basePoint); multiPoint.AddPoint(basePoint.Move(0, -0.0005)); // Y轴下移 -
TextSymbol：定义文本样式
csharp复制var symbol = new TextSymbol { Text = "示例文本", FontFamily = "微软雅黑", Size = 10, Color = ColorFactory.Instance.BlueRGB };
3.2 属性字段的特殊处理
多行注记通常需要存储额外的格式信息，建议在要素类中添加以下字段：
| 字段名 | 类型 | 描述 |
|---|---|---|
| TEXT_CONTENT | String | 存储JSON格式的文本内容 |
| LINE_SPACING | Double | 行间距（地图单位） |
| ALIGNMENT | Integer | 对齐方式（0-左对齐,1-居中,2-右对齐） |
示例字段设置代码：
csharp复制var fields = new List<FieldDescription>
{
new FieldDescription("TEXT_CONTENT", FieldType.String),
new FieldDescription("LINE_SPACING", FieldType.Double),
new FieldDescription("ALIGNMENT", FieldType.Integer)
};
4. 多行注记创建实战流程
4.1 基础创建步骤
-
获取当前地图和注记图层
csharp复制var map = MapView.Active.Map; var annoLayer = map.GetLayersAsFlattenedList() .OfType<AnnotationLayer>() .FirstOrDefault(); -
构建几何集合
csharp复制var points = new List<MapPoint> { basePoint, basePoint.Move(0, -lineSpacing), basePoint.Move(0, -lineSpacing*2) }; var geometry = MultipointBuilderEx.CreateMultipoint(points); -
创建注记要素
csharp复制var featureAttributes = new Dictionary<string, object> { ["TEXT_CONTENT"] = "{\"lines\":[\"第一行\",\"第二行\",\"第三行\"]}", ["LINE_SPACING"] = 0.0002, ["ALIGNMENT"] = 1 }; var createOperation = new EditOperation(); createOperation.Create(annoLayer, geometry, featureAttributes); if (!createOperation.Execute()) { throw new Exception("创建失败: " + createOperation.ErrorMessage); }
4.2 动态位置调整算法
对于需要自动排列的多行文本，建议采用以下算法：
csharp复制public static IEnumerable<MapPoint> CalculateTextPositions(
MapPoint basePoint,
int lineCount,
double spacing,
TextAlignment alignment)
{
for (int i = 0; i < lineCount; i++)
{
double offsetX = alignment switch
{
TextAlignment.Center => -spacing * (lineCount - 1) / 2 + spacing * i,
TextAlignment.Right => -spacing * i,
_ => spacing * i
};
yield return basePoint.Move(offsetX, 0);
}
}
实测发现：当地图旋转时，固定偏移量会导致文字错位。解决方法是在计算偏移量时考虑地图的旋转角度：
csharp复制var rotation = MapView.Active.MapRotation; offsetX = offsetX * Math.Cos(rotation) - offsetY * Math.Sin(rotation); offsetY = offsetX * Math.Sin(rotation) + offsetY * Math.Cos(rotation);
5. 高级功能实现技巧
5.1 注记动态更新策略
当关联要素移动时，多行注记需要同步更新位置。推荐使用以下事件模型：
csharp复制// 注册要素移动事件
ActiveMapView.GeoViewChanged += OnMapViewChanged;
private void OnMapViewChanged(object sender, EventArgs e)
{
var movedFeatures = GetMovedFeatures(); // 自定义获取移动要素的方法
foreach (var feature in movedFeatures)
{
var annotation = GetRelatedAnnotation(feature);
UpdateAnnotationPosition(annotation, feature.Geometry);
}
}
private void UpdateAnnotationPosition(Feature annotation, Geometry newGeometry)
{
var editOperation = new EditOperation();
editOperation.Modify(annotation, newGeometry);
editOperation.Execute();
}
5.2 性能优化方案
处理大批量多行注记时，建议：
-
批量编辑模式：
csharp复制using (var bulkEditor = new BulkEditor(annoLayer)) { foreach (var feature in featuresToCreate) { bulkEditor.Add(feature); } bulkEditor.Apply(); // 单次提交所有修改 } -
空间索引优化：
sql复制-- 在Geodatabase中执行 CREATE SPATIAL INDEX ON annotation_layer(SHAPE) GRIDS = (HIGH, HIGH, HIGH, HIGH); -
显示分级策略：
csharp复制var definition = annoLayer.GetDefinition(); definition.SetDisplayScaleRanges( new DisplayScaleRange(0, 5000), // 全细节显示 new DisplayScaleRange(5001, 20000) // 简略显示 );
6. 常见问题排查指南
6.1 文本显示异常排查
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 文字重叠 | 行间距设置过小 | 检查LINE_SPACING字段值是否合理 |
| 部分文字缺失 | JSON格式错误 | 验证TEXT_CONTENT字段的JSON有效性 |
| 文字方向错误 | 地图旋转未处理 | 添加旋转角度补偿计算 |
| 样式不一致 | 符号覆盖冲突 | 检查图层默认符号与要素符号的优先级 |
6.2 几何验证流程
当注记位置异常时，建议按以下步骤验证几何数据：
-
获取要素的原始几何对象
csharp复制var geometry = feature.GetGeometry(); -
检查空间参考一致性
csharp复制if (!geometry.SpatialReference.IsEqual(MapView.Active.Map.SpatialReference)) { geometry = GeometryEngine.Project(geometry, MapView.Active.Map.SpatialReference); } -
验证几何有效性
csharp复制if (!GeometryEngine.IsSimple(geometry)) { geometry = GeometryEngine.Simplify(geometry); }
6.3 调试日志记录
建议在关键操作中添加日志记录：
csharp复制ArcGIS.Core.Diagnostics.Logger.Log(
LogLevel.Debug,
$"Created annotation at {geometry.Extent.Center}",
"AnnotationTool");
日志查看方式：
- 打开ArcGIS Pro安装目录下的
Logs文件夹 - 使用
TraceListener工具实时监控日志流
7. 扩展应用场景探索
7.1 与属性标注的联动
通过绑定要素属性实现动态注记内容：
csharp复制var attributes = feature.GetAttributes();
var textLines = new List<string>
{
attributes["NAME"].ToString(),
$"面积：{attributes["AREA"]}㎡",
$"编号：{attributes["ID"]}"
};
feature.SetAttributeValue("TEXT_CONTENT", JsonConvert.SerializeObject(textLines));
7.2 三维场景应用
将多行注记适配到三维场景需要额外处理：
csharp复制var sceneView = SceneView.Active;
if (sceneView != null)
{
var zOffset = 10; // 高程偏移量
var points3D = points.Select(p =>
MapPointBuilder.CreateMapPoint(
p.X, p.Y, p.Z + zOffset,
p.SpatialReference));
var multiPoint3D = MultipointBuilderEx.CreateMultipoint(points3D);
// 创建3D注记要素...
}
7.3 移动端适配策略
针对Field Maps等移动端应用，建议：
- 设置最小可见比例
csharp复制definition.SetMinimumScale(5000); - 简化文本内容
csharp复制if (isMobile) { textLines = textLines.Take(2).ToList(); // 移动端只显示前两行 }
在实际项目中，我们曾用这套方案为某省级电网公司实现了"输电线路杆塔多参数注记系统"，成功将平均标注效率提升75%，同时减少了80%的标注错误投诉。关键点在于：
- 采用几何对象集合确保所有参数标注的原子性
- 通过动态位置计算适应不同比例尺下的显示需求
- 建立注记与设备资产的双向关联关系
对于需要处理复杂标注需求的开发者，建议进一步研究：
- ArcGIS Pro SDK中的
TextFormattingTags类实现富文本标注 - 使用
AnnotationLayerDefinition控制图层级显示规则 - 结合
LabelClass实现混合标注策略