# NavisworksApiHelper 使用指南

## 文件位置

`src/Utils/NavisworksApiHelper.cs`

## 用途

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

## 核心方法

### 缓存刷新

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

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

### 线程检查与执行

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

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

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

### 模型项操作

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

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

## 使用示例

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

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

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

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

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

### 示例3：查找模型项

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

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

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

## 注意事项

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