第十九章：常见问题与解决方案

19.1 开发环境问题

19.1.1 编译错误：找不到LightCAD相关程序集

问题描述：编译时提示"未能找到类型或命名空间名LightCAD"

解决方案：

1. 确认Libs目录下所有DLL文件完整（36+个DLL）
2. 检查QdLayout.csproj中的HintPath路径是否正确指向..\Libs\
3. 在VS2022中右键项目→重新加载项目

<!-- 确保引用路径正确 -->
<Reference Include="LightCAD.Core">
  <HintPath>..\Libs\LightCAD.Core.dll</HintPath>
</Reference>

19.1.2 运行时错误：插件未加载

问题描述：飞扬主程序启动后看不到"场布"工具栏

排查步骤：

1. 确认Build输出路径正确（<BaseOutputPath>..\Build</BaseOutputPath>）
2. 检查ILcPlugin接口的5个方法是否都已实现
3. 检查LayoutPlugin类是否为public
4. 查看飞扬主程序日志中是否有加载错误信息

19.1.3 .NET版本不匹配

问题描述：编译提示目标框架不支持

解决方案：

• 安装.NET 10 SDK（必须是Windows版本）
• VS2022版本需要17.14以上
• 确认项目TargetFramework为net10.0-windows

19.2 元素创建问题

19.2.1 创建元素后不可见

排查清单：

□ 元素类型已在LayoutElementType.All数组中注册
□ ElementAction已在Loaded()中添加到LcDocument.ElementActions
□ 元素Layer属性已设置且图层可见
□ ResetBoundingBox()已调用
□ InsertElement()已调用
□ 元素的Outline/BaseCurve有有效几何数据

19.2.2 元素类型注册失败

常见原因：GUID重复。每个元素类型的GUID必须全局唯一。

// 错误示例：Road和Ground使用了相同的GUID
public static ElementType Road = new ElementType
{
    Guid = Guid.ParseExact("{85AB36C8-FBB1-424B-C7C4-1F92576EC5BD}", "B").ToLcGuid(),
    // ...
};
public static ElementType Ground = new ElementType
{
    Guid = Guid.ParseExact("{85AB36C8-FBB1-424B-C7C4-1F92576EC5BD}", "B").ToLcGuid(),
    // ... 注意：与Road相同的GUID！
};

解决方案：为每个元素类型生成唯一的GUID。

19.2.3 多段线转换失败

问题描述：使用LawnChange等转换命令时无法创建元素

原因：选择的线段无法组成闭合环路

解决方案：

• 确保选择的线段端点相连（容差为0）
• 使用LcCurveChangeLoop.CheckLoops()检查闭合性
• 支持的元素类型：LcLine、LcPolyLine、LcArc、LcCircle

19.3 三维显示问题

19.3.1 三维视图中元素不显示

排查步骤：

1. 检查Element3dAction是否已注册
2. 检查Provider是否已在QdLayoutProviderRegist中注册
3. 验证GeometryData数据：顶点数组长度是3的倍数，索引不越界

19.3.2 三维模型面片翻转

原因：三角面片顶点顺序不一致

解决方案：确保所有面片使用逆时针顶点顺序（面向观察者时）。对于基坑等双面显示的元素，需要同时生成正反两个面：

var pitB = new PlanarSurface3d(new Plane(new Vector3(0, 0, 1)), curves);
var pitT = new PlanarSurface3d(new Plane(new Vector3(0, 0, -1)), curves);

19.3.3 基坑放坡显示异常

常见原因：

• 轮廓方向不一致（需统一为逆时针）
• Factor（放坡系数）为0导致宽度为0
• Pattern值不正确（0=向外放坡，1=向内放坡）

// 确保轮廓为逆时针方向
if (ShapeUtils.isClockWise(outline.Curve2ds
    .SelectMany(n => n.GetPoints(2)).ToListEx()))
{
    outline.Reverse();
}

19.4 UI与命令问题

19.4.1 快捷键冲突

FY_Layout中多个命令使用了相同的快捷键"W"（如Fence、PlateBuilding等），这会导致快捷键冲突。

解决方案：自定义插件时使用唯一的快捷键。

19.4.2 属性面板不更新

原因：PropertyObserver的Setter中未调用OnPropertyChangedBefore/After

// 正确的属性设置流程
Setter = (ele, value) =>
{
    var lawn = ele as QdLawn;
    if (!double.TryParse(value.ToString(), out var bottom)) return;
    lawn.OnPropertyChangedBefore("Bottom", lawn.Bottom, bottom);  // ①
    lawn.Properties.SetValue("Bottom", bottom);                    // ②
    lawn.ResetCache();                                             // ③
    lawn.OnPropertyChangedAfter("Bottom", lawn.Bottom, bottom);   // ④
}

19.5 性能问题

19.5.1 大量元素时卡顿

优化建议：

• Draw方法中添加视口裁剪判断
• 小缩放级别使用简化绘制
• 利用ResetCache()避免重复计算

19.5.2 三维渲染帧率低

优化建议：

• 合并相同材质的几何体
• 远距离元素使用简化模型
• 缓存不变的几何数据

19.6 本章小结

本章汇总了FY_Layout开发中最常见的问题及其解决方案，涵盖开发环境、元素创建、三维显示、UI命令和性能优化五大类。建议开发者在遇到问题时首先参考本章的排查清单。

上一章：API参考手册 | 下一章：学习资源与社区指南