NavisworksTransport/.agents/skills/project-tools/utils/NavisworksApiHelper.md

NavisworksApiHelper 使用指南

文件位置

src/Utils/NavisworksApiHelper.cs

用途

提供 Navisworks API 通用工具方法，包括缓存刷新、线程安全操作、模型项查找等。

核心方法

缓存刷新

// 安全的缓存刷新（轻量级）
NavisworksApiHelper.SafeCacheRefresh("MyComponent");

// 线程安全的缓存刷新（自动确保在UI线程执行）
NavisworksApiHelper.SafeCacheRefreshUIThread("MyComponent");

线程检查与执行

// 检查当前是否在主UI线程
bool isUIThread = NavisworksApiHelper.IsOnUIThread();

// 在UI线程执行操作（无返回值）
NavisworksApiHelper.ExecuteOnUIThread(() =>
{
    // 这段代码确保在UI线程执行
    document.CurrentSelection.Clear();
});

// 在UI线程执行操作（有返回值）
var result = NavisworksApiHelper.ExecuteOnUIThread(() =>
{
    return document.CurrentSelection.SelectedItems.Count;
});

模型项操作

// 获取ModelItem的显示名称（安全）
string name = NavisworksApiHelper.GetModelItemName(modelItem);

// 使用PathId查找ModelItem
ModelItem item = NavisworksApiHelper.FindModelItemByPathId(modelIndex, pathId);

使用示例

示例1：API操作后刷新缓存

// 执行某些API操作
document.Models.SetHidden(items, true);

// 刷新缓存以确保状态同步
NavisworksApiHelper.SafeCacheRefresh("VisibilityManager");

示例2：确保在UI线程操作

// 在后台线程中需要操作UI
Task.Run(() =>
{
    // 后台计算...
    var result = DoCalculation();
    
    // 回到UI线程更新界面
    NavisworksApiHelper.ExecuteOnUIThread(() =>
    {
        StatusText = $"计算完成: {result}";
        ProgressBar.Value = 100;
    });
});

示例3：查找模型项

// 从路径ID恢复模型项引用
var item = NavisworksApiHelper.FindModelItemByPathId(0, "1/2/3/4");
if (item != null)
{
    LogManager.Info($"找到模型项: {item.DisplayName}");
}

示例4：获取模型项名称（安全）

// 安全的获取名称，处理空值和异常
string name = NavisworksApiHelper.GetModelItemName(modelItem);
// 如果 modelItem 为 null，返回 "未知对象"
// 如果获取失败，返回 "获取失败"

注意事项

1. 缓存刷新机制：使用空集合的 SetHidden 操作触发缓存更新，开销极小
2. 线程安全：SafeCacheRefreshUIThread 会自动检查当前线程，必要时切换到UI线程
3. 异常处理：所有方法内部都处理了异常，不会抛出错误
4. 日志前缀：传入的日志前缀用于标识调用来源，便于调试