1493 lines
47 KiB
Markdown
1493 lines
47 KiB
Markdown
# Navisworks API 使用方法指南
|
||
|
||
基于真实官方示例的正确API用法总结
|
||
|
||
## 参考示例来源
|
||
|
||
基于以下官方示例文件的真实API用法：
|
||
|
||
- `C:\Users\Tellme\apps\NavisworksTransport\doc\navisworks_api\NET\examples\PlugIns\SearchComparisonPlugIn\SearchComparisonPlugIn.cs`
|
||
- `C:\Users\Tellme\apps\NavisworksTransport\doc\navisworks_api\NET\examples\PlugIns\Examiner\Examiner.cs`
|
||
|
||
## 1. 模型遍历和节点访问
|
||
|
||
### 1.1 正确的遍历方式
|
||
|
||
```csharp
|
||
// ✅ 正确：获取所有模型项
|
||
IEnumerable<ModelItem> allItems =
|
||
Application.ActiveDocument.Models.RootItemDescendantsAndSelf;
|
||
|
||
// ✅ 正确：遍历特定模型的所有项
|
||
foreach (Model model in document.Models)
|
||
{
|
||
foreach (ModelItem item in model.RootItem.DescendantsAndSelf)
|
||
{
|
||
// 处理每个模型项
|
||
}
|
||
}
|
||
|
||
// ✅ 正确：只获取顶级节点
|
||
foreach (Model model in document.Models)
|
||
{
|
||
foreach (ModelItem topLevelItem in model.RootItem.Children)
|
||
{
|
||
// 处理顶级节点
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.2 获取子节点
|
||
|
||
```csharp
|
||
// ✅ 正确：获取某个节点的所有后代
|
||
var childItems = selectedItem.DescendantsAndSelf.Where(x => x != selectedItem);
|
||
|
||
// ✅ 正确：只获取直接子节点
|
||
foreach (ModelItem child in parentItem.Children)
|
||
{
|
||
// 处理直接子节点
|
||
}
|
||
```
|
||
|
||
### 1.3 遍历祖先节点
|
||
|
||
```csharp
|
||
// ✅ 正确：向上遍历父节点链
|
||
var current = selectedItem.Parent;
|
||
while (current != null)
|
||
{
|
||
// 处理祖先节点
|
||
current = current.Parent;
|
||
}
|
||
```
|
||
|
||
## 2. 搜索和查询
|
||
|
||
### 2.1 使用LINQ查询
|
||
|
||
```csharp
|
||
// ✅ 正确：使用LINQ查询模型项
|
||
IEnumerable<ModelItem> results =
|
||
Application.ActiveDocument.Models.RootItemDescendantsAndSelf
|
||
.Where(x =>
|
||
x.HasGeometry &&
|
||
!x.IsHidden &&
|
||
x.ClassDisplayName.ToLower().Contains("wall"));
|
||
```
|
||
|
||
### 2.2 使用Search类
|
||
|
||
```csharp
|
||
// ✅ 正确：使用Search API
|
||
Search search = new Search();
|
||
|
||
// 添加搜索条件
|
||
search.SearchConditions.Add(
|
||
SearchCondition.HasCategoryByName(PropertyCategoryNames.Geometry));
|
||
search.SearchConditions.Add(
|
||
SearchCondition.HasPropertyByName(PropertyCategoryNames.Item, DataPropertyNames.ItemHidden)
|
||
.EqualValue(VariantData.FromBoolean(false)));
|
||
|
||
// 设置搜索范围
|
||
search.Selection.SelectAll();
|
||
search.Locations = SearchLocations.DescendantsAndSelf;
|
||
|
||
// 执行搜索
|
||
ModelItemCollection results = search.FindAll(document, false);
|
||
```
|
||
|
||
### 2.3 迭代遍历（性能对比）
|
||
|
||
```csharp
|
||
// ✅ 可用但性能较低：迭代方法
|
||
ModelItemCollection searchResults = new ModelItemCollection();
|
||
foreach (ModelItem modelItem in Application.ActiveDocument.Models.CreateCollectionFromRootItems().DescendantsAndSelf)
|
||
{
|
||
if (modelItem.HasGeometry && !modelItem.IsHidden)
|
||
searchResults.Add(modelItem);
|
||
}
|
||
```
|
||
|
||
## 3. 选择操作
|
||
|
||
### 3.1 操作当前选择
|
||
|
||
```csharp
|
||
// ✅ 正确：获取当前选择
|
||
var currentSelection = document.CurrentSelection.SelectedItems;
|
||
|
||
// ✅ 正确：清空选择
|
||
document.CurrentSelection.Clear();
|
||
|
||
// ✅ 正确：添加到选择
|
||
document.CurrentSelection.Add(modelItem);
|
||
|
||
// ✅ 正确：复制集合到选择
|
||
document.CurrentSelection.CopyFrom(modelItems);
|
||
```
|
||
|
||
## 4. 可见性控制
|
||
|
||
### 4.1 隐藏和显示
|
||
|
||
```csharp
|
||
// ✅ 正确：隐藏项目
|
||
ModelItemCollection itemsToHide = new ModelItemCollection();
|
||
itemsToHide.Add(modelItem);
|
||
document.Models.SetHidden(itemsToHide, true);
|
||
|
||
// ✅ 正确：显示项目
|
||
document.Models.SetHidden(itemsToHide, false);
|
||
|
||
// ✅ 正确：检查是否隐藏
|
||
if (modelItem.IsHidden)
|
||
{
|
||
// 项目被隐藏
|
||
}
|
||
```
|
||
|
||
## 5. 文件导出
|
||
|
||
### 5.1 基本文件保存
|
||
|
||
```csharp
|
||
// ✅ 正确：保存NWD文件
|
||
document.SaveFile(filePath);
|
||
|
||
// ✅ 正确：指定版本保存
|
||
document.SaveFile(filePath, DocumentFileVersion.Current);
|
||
```
|
||
|
||
### 5.2 ExportToNwd API
|
||
|
||
```csharp
|
||
// ✅ 正确：使用ExportToNwd导出
|
||
var exportOptions = new NwdExportOptions();
|
||
exportOptions.ExcludeHiddenItems = true; // 只导出可见项目
|
||
exportOptions.EmbedXrefs = false;
|
||
exportOptions.PreventObjectPropertyExport = false;
|
||
|
||
document.ExportToNwd(saveFilePath, exportOptions);
|
||
```
|
||
|
||
## 6. 性能最佳实践
|
||
|
||
### 6.1 避免的做法
|
||
|
||
```csharp
|
||
// ❌ 错误：使用不存在的API
|
||
// SearchCondition.HasAncestor(items) // 这个API不存在
|
||
|
||
// ❌ 错误：深度递归遍历
|
||
// void RecursiveTraversal(ModelItem item) // 大模型中可能导致堆栈溢出
|
||
```
|
||
|
||
### 6.2 推荐的做法
|
||
|
||
```csharp
|
||
// ✅ 推荐：使用内置的DescendantsAndSelf
|
||
var allDescendants = rootItem.DescendantsAndSelf;
|
||
|
||
// ✅ 推荐：使用LINQ进行高效查询
|
||
var filteredItems = allItems.Where(x => x.HasGeometry);
|
||
|
||
// ✅ 推荐：批量操作而不是逐个操作
|
||
ModelItemCollection batchItems = new ModelItemCollection();
|
||
// 添加所有需要处理的项目
|
||
document.Models.SetHidden(batchItems, true); // 一次性操作
|
||
```
|
||
|
||
## 7. 完整示例：多选节点导出
|
||
|
||
```csharp
|
||
public void ExportSelectedNodes(List<ModelItem> selectedItems, string filePath)
|
||
{
|
||
var document = Application.ActiveDocument;
|
||
var nodesToKeepVisible = new HashSet<ModelItem>();
|
||
|
||
// 1. 收集需要保持可见的节点
|
||
foreach (var selectedItem in selectedItems)
|
||
{
|
||
// 添加选中节点本身
|
||
nodesToKeepVisible.Add(selectedItem);
|
||
|
||
// 添加所有祖先节点
|
||
var current = selectedItem.Parent;
|
||
while (current != null)
|
||
{
|
||
nodesToKeepVisible.Add(current);
|
||
current = current.Parent;
|
||
}
|
||
|
||
// 添加所有子节点（可选）
|
||
var childItems = selectedItem.DescendantsAndSelf.Where(x => x != selectedItem);
|
||
foreach (ModelItem child in childItems)
|
||
{
|
||
nodesToKeepVisible.Add(child);
|
||
}
|
||
}
|
||
|
||
// 2. 收集顶级节点并决定隐藏哪些
|
||
var itemsToHide = new ModelItemCollection();
|
||
foreach (Model model in document.Models)
|
||
{
|
||
foreach (ModelItem topLevelItem in model.RootItem.Children)
|
||
{
|
||
bool shouldKeep = false;
|
||
|
||
// 检查是否包含选中节点
|
||
foreach (var selectedItem in selectedItems)
|
||
{
|
||
var current = selectedItem;
|
||
while (current != null)
|
||
{
|
||
if (current == topLevelItem)
|
||
{
|
||
shouldKeep = true;
|
||
break;
|
||
}
|
||
current = current.Parent;
|
||
}
|
||
if (shouldKeep) break;
|
||
}
|
||
|
||
if (!shouldKeep)
|
||
{
|
||
itemsToHide.Add(topLevelItem);
|
||
}
|
||
}
|
||
}
|
||
|
||
// 3. 执行隐藏和导出
|
||
try
|
||
{
|
||
document.Models.SetHidden(itemsToHide, true);
|
||
|
||
var exportOptions = new NwdExportOptions();
|
||
exportOptions.ExcludeHiddenItems = true;
|
||
document.ExportToNwd(filePath, exportOptions);
|
||
}
|
||
finally
|
||
{
|
||
// 4. 恢复可见性
|
||
document.Models.SetHidden(itemsToHide, false);
|
||
}
|
||
}
|
||
```
|
||
|
||
## 8. 线程安全 - 关键重要
|
||
|
||
### 8.1 Navisworks API 线程安全要求
|
||
|
||
**核心原则：所有 Navisworks API 调用必须在主 UI 线程（STA 线程）中执行**
|
||
|
||
```csharp
|
||
// ❌ 错误：在后台线程中调用 Navisworks API
|
||
await Task.Run(() =>
|
||
{
|
||
var document = Application.ActiveDocument; // 可能崩溃
|
||
document.ExportToNwd(path, options); // 会崩溃
|
||
});
|
||
|
||
// ✅ 正确：使用 Dispatcher.Invoke 确保主线程执行
|
||
await Task.Run(() =>
|
||
{
|
||
System.Windows.Application.Current.Dispatcher.Invoke(() =>
|
||
{
|
||
var document = Application.ActiveDocument;
|
||
document.ExportToNwd(path, options); // 安全执行
|
||
});
|
||
});
|
||
```
|
||
|
||
### 8.2 实际案例：分层导出修复
|
||
|
||
**问题场景**：`SimplifiedModelSplitterManager.ExportLayerToNwd` 方法通过后台线程调用时崩溃
|
||
|
||
```csharp
|
||
// ❌ 问题代码：导致崩溃
|
||
public bool ExportLayerToNwd(...)
|
||
{
|
||
var document = NavisApplication.ActiveDocument;
|
||
document.ExportToNwd(outputPath, exportOptions); // 后台线程崩溃
|
||
}
|
||
```
|
||
|
||
**修复方案**：使用 Dispatcher.Invoke 包装所有 API 调用
|
||
|
||
```csharp
|
||
// ✅ 修复代码：线程安全
|
||
public bool ExportLayerToNwd(...)
|
||
{
|
||
bool exportResult = false;
|
||
Exception exportException = null;
|
||
|
||
// 确保在主线程中执行所有 Navisworks API 调用
|
||
System.Windows.Application.Current.Dispatcher.Invoke(() =>
|
||
{
|
||
try
|
||
{
|
||
var document = NavisApplication.ActiveDocument;
|
||
|
||
// 保存可见性状态
|
||
var originalVisibilityState = SaveCurrentVisibilityState(document);
|
||
|
||
try
|
||
{
|
||
// 隐藏不需要的项目
|
||
var itemsToHide = GetItemsToHide(...);
|
||
document.Models.SetHidden(itemsToHide, true);
|
||
|
||
// 创建导出选项
|
||
var exportOptions = new NwdExportOptions
|
||
{
|
||
ExcludeHiddenItems = true,
|
||
EmbedXrefs = false,
|
||
PreventObjectPropertyExport = false
|
||
};
|
||
|
||
// 在主线程中安全执行导出
|
||
document.ExportToNwd(outputPath, exportOptions);
|
||
exportResult = true;
|
||
}
|
||
finally
|
||
{
|
||
// 恢复可见性状态
|
||
RestoreVisibilityState(document, originalVisibilityState);
|
||
}
|
||
}
|
||
catch (Exception ex)
|
||
{
|
||
exportException = ex;
|
||
}
|
||
});
|
||
|
||
if (exportException != null)
|
||
throw exportException;
|
||
|
||
return exportResult;
|
||
}
|
||
```
|
||
|
||
### 8.3 线程安全检查和诊断
|
||
|
||
```csharp
|
||
// ✅ 检查当前线程状态
|
||
var apartmentState = System.Threading.Thread.CurrentThread.GetApartmentState();
|
||
LogManager.Info($"当前线程状态: {apartmentState}"); // 应该是 STA
|
||
|
||
if (apartmentState != System.Threading.ApartmentState.STA)
|
||
{
|
||
LogManager.Warning("警告：不在STA线程中，API调用可能失败");
|
||
}
|
||
|
||
// ✅ 验证是否在主线程中
|
||
bool isMainThread = System.Windows.Application.Current.Dispatcher.CheckAccess();
|
||
if (!isMainThread)
|
||
{
|
||
LogManager.Warning("警告：不在主线程中，需要使用Dispatcher.Invoke");
|
||
}
|
||
```
|
||
|
||
### 8.4 常见线程安全问题和解决方案
|
||
|
||
| 问题场景 | 症状 | 解决方案 |
|
||
|---------|------|---------|
|
||
| 后台线程调用 API | 程序崩溃，无错误信息 | 使用 `Dispatcher.Invoke()` |
|
||
| Command.ExecuteAsync() | Task 中的 API 调用崩溃 | 在 Task 内部使用 Dispatcher |
|
||
| 异步方法调用 API | 间歇性崩溃 | 检查执行线程，确保主线程 |
|
||
| Timer 中调用 API | 定时器触发时崩溃 | Timer 回调使用 Dispatcher |
|
||
|
||
### 8.5 最佳实践模式
|
||
|
||
```csharp
|
||
// ✅ 推荐模式：安全的异步 Navisworks API 调用
|
||
public async Task<bool> SafeNavisworksOperationAsync()
|
||
{
|
||
// 1. 后台准备数据
|
||
var preparedData = await Task.Run(() =>
|
||
{
|
||
// 在后台线程中进行数据准备（不涉及 Navisworks API）
|
||
return PrepareDataSafely();
|
||
});
|
||
|
||
// 2. 主线程执行 API 调用
|
||
bool result = false;
|
||
await System.Windows.Application.Current.Dispatcher.InvokeAsync(() =>
|
||
{
|
||
// 所有 Navisworks API 调用都在主线程中
|
||
var document = Application.ActiveDocument;
|
||
result = document.SomeNavisworksOperation(preparedData);
|
||
});
|
||
|
||
return result;
|
||
}
|
||
|
||
// ✅ 推荐模式：批量 API 操作
|
||
public void BatchNavisworksOperations(List<ModelItem> items)
|
||
{
|
||
System.Windows.Application.Current.Dispatcher.Invoke(() =>
|
||
{
|
||
var document = Application.ActiveDocument;
|
||
|
||
// 批量操作，避免多次线程切换
|
||
var itemCollection = new ModelItemCollection();
|
||
foreach (var item in items)
|
||
{
|
||
itemCollection.Add(item);
|
||
}
|
||
|
||
// 一次性完成所有操作
|
||
document.Models.SetHidden(itemCollection, true);
|
||
document.CurrentSelection.CopyFrom(itemCollection);
|
||
});
|
||
}
|
||
```
|
||
|
||
## 9. 常用属性和方法速查
|
||
|
||
### ModelItem 常用属性
|
||
|
||
- `HasGeometry` - 是否有几何体
|
||
- `IsHidden` - 是否隐藏
|
||
- `IsRequired` - 是否必需
|
||
- `IsInsert` - 是否为插入对象
|
||
- `IsLayer` - 是否为图层
|
||
- `DisplayName` - 显示名称
|
||
- `ClassName` - 类名
|
||
- `ClassDisplayName` - 类显示名称
|
||
- `Parent` - 父节点
|
||
- `Children` - 子节点集合
|
||
- `DescendantsAndSelf` - 所有后代节点（包括自己）
|
||
|
||
### Document 常用方法
|
||
|
||
- `SaveFile(string path)` - 保存文件
|
||
- `ExportToNwd(string path, NwdExportOptions options)` - 导出NWD
|
||
- `CurrentSelection` - 当前选择
|
||
- `Models` - 模型集合
|
||
|
||
### Models 常用方法
|
||
|
||
- `SetHidden(ModelItemCollection items, bool hidden)` - 设置隐藏状态
|
||
- `SetRequired(ModelItemCollection items, bool required)` - 设置必需状态
|
||
- `RootItemDescendantsAndSelf` - 所有根项目的后代
|
||
|
||
## 10. 错误避免指南
|
||
|
||
1. **线程安全是第一要务**：所有 Navisworks API 调用必须在主 UI 线程中执行
|
||
2. **不要使用不存在的API**：如 `SearchCondition.HasAncestor`
|
||
3. **避免深度递归**：使用内置的 `DescendantsAndSelf` 代替手写递归
|
||
4. **批量操作**：使用 `ModelItemCollection` 进行批量设置，而不是逐个操作
|
||
5. **正确的命名空间**：确保引用 `using Autodesk.Navisworks.Api;`
|
||
6. **异常处理**：文件操作和API调用要适当处理异常
|
||
7. **资源清理**：隐藏操作后要恢复原始状态
|
||
8. **线程状态检查**：在关键操作前验证线程状态（STA）
|
||
9. **Dispatcher 模式**：后台线程中需要调用 API 时，始终使用 Dispatcher.Invoke
|
||
|
||
## 11. Transform 变换操作
|
||
|
||
### 11.1 Transform 相关 API 概念
|
||
|
||
**核心概念**：
|
||
|
||
- `ModelItem.Transform` - 返回设计文件中的原始变换，只读属性
|
||
- `OverridePermanentTransform()` - 应用增量变换（与现有变换叠加）
|
||
- `ResetPermanentTransform()` - 清除所有增量变换，恢复到设计文件原始位置
|
||
|
||
### 11.2 Transform 操作的正确用法
|
||
|
||
```csharp
|
||
// ✅ 获取物体的原始Transform（设计文件中的位置）
|
||
Transform3D originalTransform = modelItem.Transform;
|
||
|
||
// ✅ 应用增量变换（累积变换）
|
||
var doc = Application.ActiveDocument;
|
||
var modelItems = new ModelItemCollection { modelItem };
|
||
doc.Models.OverridePermanentTransform(modelItems, newTransform, false);
|
||
|
||
// ✅ 重置到原始位置（清除所有增量变换）
|
||
doc.Models.ResetPermanentTransform(modelItems);
|
||
```
|
||
|
||
### 11.3 Transform 操作的关键区别
|
||
|
||
| API方法 | 作用 | 使用场景 | 注意事项 |
|
||
|---------|------|---------|---------|
|
||
| `ModelItem.Transform` | 获取原始变换 | 记录物体初始位置 | 只读属性，返回设计文件位置 |
|
||
| `OverridePermanentTransform()` | 应用增量变换 | 动画中移动物体 | 与现有变换累积，不是绝对位置 |
|
||
| `ResetPermanentTransform()` | 重置到原始位置 | 清除所有移动，恢复初始状态 | 忽略所有之前的变换 |
|
||
|
||
### 11.4 实际应用案例
|
||
|
||
**案例1：动画系统中的Transform管理**
|
||
|
||
```csharp
|
||
// 动画开始时记录原始位置
|
||
private Transform3D _originalTransform;
|
||
|
||
public void StartAnimation(ModelItem animatedObject)
|
||
{
|
||
// 记录原始Transform
|
||
_originalTransform = animatedObject.Transform;
|
||
|
||
// 移动到路径起点（增量变换）
|
||
var startTransform = Transform3D.CreateTranslation(startPosition);
|
||
var modelItems = new ModelItemCollection { animatedObject };
|
||
doc.Models.OverridePermanentTransform(modelItems, startTransform, false);
|
||
}
|
||
|
||
public void ResetAnimation()
|
||
{
|
||
// 动画结束后，使用原始Transform恢复位置
|
||
var modelItems = new ModelItemCollection { _animatedObject };
|
||
doc.Models.OverridePermanentTransform(modelItems, _originalTransform, false);
|
||
}
|
||
```
|
||
|
||
**案例2：用户手动位置恢复**
|
||
|
||
```csharp
|
||
public void RestoreToOriginalPosition(ModelItem selectedObject)
|
||
{
|
||
// 不需要记录Transform，直接重置到设计文件原始位置
|
||
var doc = Application.ActiveDocument;
|
||
var modelItems = new ModelItemCollection { selectedObject };
|
||
|
||
// 清除所有增量变换，恢复到设计文件原始位置
|
||
doc.Models.ResetPermanentTransform(modelItems);
|
||
}
|
||
```
|
||
|
||
### 11.5 常见Transform问题和解决方案
|
||
|
||
**问题1：位置恢复有偏移**
|
||
|
||
```csharp
|
||
// ❌ 错误：使用增量变换恢复位置
|
||
doc.Models.OverridePermanentTransform(modelItems, originalTransform, false);
|
||
// 问题：如果物体已经被移动过，这会导致累积偏移
|
||
|
||
// ✅ 正确：重置到原始位置
|
||
doc.Models.ResetPermanentTransform(modelItems);
|
||
// 结果：直接恢复到设计文件中的原始位置，无偏移
|
||
```
|
||
|
||
**问题2：动画结束后位置不准确**
|
||
|
||
```csharp
|
||
// ✅ 动画系统应该记录原始Transform并使用增量恢复
|
||
private Transform3D _originalTransform;
|
||
|
||
// 动画开始时
|
||
_originalTransform = animatedObject.Transform;
|
||
|
||
// 动画结束时恢复
|
||
doc.Models.OverridePermanentTransform(modelItems, _originalTransform, false);
|
||
```
|
||
|
||
**问题3：记录Transform但不使用**
|
||
|
||
```csharp
|
||
// ❌ 不必要：记录Transform但使用Reset
|
||
private Transform3D _originalTransform;
|
||
_originalTransform = selectedItem.Transform; // 记录了但不使用
|
||
doc.Models.ResetPermanentTransform(modelItems); // 直接重置
|
||
|
||
// ✅ 简化：直接重置，无需记录
|
||
doc.Models.ResetPermanentTransform(modelItems);
|
||
```
|
||
|
||
### 11.6 Transform 最佳实践
|
||
|
||
1. **选择合适的恢复方式**：
|
||
- 动画系统：使用 `OverridePermanentTransform` + 原始Transform
|
||
- 用户操作：使用 `ResetPermanentTransform` 直接重置
|
||
|
||
2. **避免不必要的Transform记录**：
|
||
- 如果只需要恢复到设计文件原始位置，使用 `ResetPermanentTransform`
|
||
- 只有需要恢复到特定中间状态时才记录Transform
|
||
|
||
3. **理解增量vs绝对变换**：
|
||
- `OverridePermanentTransform` 是增量的，会与现有变换叠加
|
||
- `ResetPermanentTransform` 是绝对的，清除所有变换
|
||
|
||
4. **线程安全**：
|
||
- 所有Transform操作都必须在主UI线程中执行
|
||
- 使用 `Dispatcher.Invoke` 确保线程安全
|
||
|
||
## 12. Item属性和自定义属性访问
|
||
|
||
基于官方示例的正确属性访问方法总结。
|
||
|
||
### 12.1 NET API 属性访问方法
|
||
|
||
#### 基础属性访问（基于 Examiner.cs）
|
||
|
||
```csharp
|
||
// ✅ 通过PropertyCategories查找特定分类
|
||
var category = item.PropertyCategories.FindCategoryByDisplayName("Material");
|
||
|
||
// ✅ 访问基础属性
|
||
string displayName = item.DisplayName;
|
||
string className = item.ClassName;
|
||
string classDisplayName = item.ClassDisplayName;
|
||
bool hasGeometry = item.HasGeometry;
|
||
bool isHidden = item.IsHidden;
|
||
bool isRequired = item.IsRequired;
|
||
|
||
// ✅ 通过LINQ查询特定属性的项目
|
||
IEnumerable<ModelItem> itemsWithMaterial =
|
||
Application.ActiveDocument.Models.RootItemDescendantsAndSelf
|
||
.Where(x =>
|
||
x.PropertyCategories.FindCategoryByDisplayName("Material") != null);
|
||
```
|
||
|
||
#### 高级属性搜索（基于 SearchComparisonPlugIn.cs）
|
||
|
||
```csharp
|
||
// ✅ 使用预定义属性分类和属性名进行搜索
|
||
Search search = new Search();
|
||
|
||
// 搜索有几何体的项目
|
||
search.SearchConditions.Add(
|
||
SearchCondition.HasCategoryByName(PropertyCategoryNames.Geometry));
|
||
|
||
// 搜索非隐藏的项目
|
||
search.SearchConditions.Add(
|
||
SearchCondition.HasPropertyByName(PropertyCategoryNames.Item, DataPropertyNames.ItemHidden)
|
||
.EqualValue(VariantData.FromBoolean(false)));
|
||
|
||
// 设置搜索范围并执行
|
||
search.Selection.SelectAll();
|
||
search.Locations = SearchLocations.DescendantsAndSelf;
|
||
ModelItemCollection results = search.FindAll(document, false);
|
||
```
|
||
|
||
#### 属性分类和属性名常量
|
||
|
||
```csharp
|
||
// ✅ 使用预定义常量访问标准属性
|
||
// PropertyCategoryNames 包含：
|
||
// - PropertyCategoryNames.Item (项目属性)
|
||
// - PropertyCategoryNames.Geometry (几何属性)
|
||
// - PropertyCategoryNames.Material (材质属性)
|
||
|
||
// DataPropertyNames 包含：
|
||
// - DataPropertyNames.ItemHidden (隐藏状态)
|
||
// - DataPropertyNames.ItemRequired (必需状态)
|
||
// 等等...
|
||
```
|
||
|
||
### 12.2 COM API 属性访问方法（基于 AutoUserPropsExample.cs）
|
||
|
||
#### 获取和遍历属性
|
||
|
||
```csharp
|
||
// ✅ 获取选中对象的属性节点
|
||
InwOpSelection2 selection = m_state.CurrentSelection as InwOpSelection2;
|
||
if (selection.Paths().Count > 0)
|
||
{
|
||
InwGUIPropertyNode2 propertyNode =
|
||
m_state.GetGUIPropertyNode(selection.Paths()[1], true) as InwGUIPropertyNode2;
|
||
|
||
// 遍历所有属性分类
|
||
foreach (InwGUIAttribute2 guiAttribute in propertyNode.GUIAttributes())
|
||
{
|
||
Console.WriteLine($"分类: {guiAttribute.ClassName}");
|
||
Console.WriteLine($"显示名: {guiAttribute.ClassUserName}");
|
||
Console.WriteLine($"用户自定义: {guiAttribute.UserDefined}");
|
||
|
||
// 遍历分类中的所有属性
|
||
foreach (InwOaProperty property in guiAttribute.Properties())
|
||
{
|
||
string propertyName = property.name; // 内部名称
|
||
string displayName = property.UserName; // 显示名称
|
||
string value = property.value; // 属性值
|
||
|
||
Console.WriteLine($" {displayName}({propertyName}) = {value}");
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 添加自定义属性
|
||
|
||
```csharp
|
||
// ✅ 创建新的自定义属性
|
||
private void AddCustomProperty(string categoryName, string internalName, string value)
|
||
{
|
||
InwOpSelection2 selection = m_state.CurrentSelection as InwOpSelection2;
|
||
if (selection.Paths().Count > 0)
|
||
{
|
||
InwGUIPropertyNode2 propertyNode =
|
||
m_state.GetGUIPropertyNode(selection.Paths()[1], true) as InwGUIPropertyNode2;
|
||
|
||
// 创建属性容器
|
||
InwOaPropertyVec propertyVector =
|
||
m_state.ObjectFactory(nwEObjectType.eObjectType_nwOaPropertyVec);
|
||
|
||
// 创建单个属性
|
||
InwOaProperty property =
|
||
m_state.ObjectFactory(nwEObjectType.eObjectType_nwOaProperty);
|
||
property.name = "CustomProperty1"; // 内部名称
|
||
property.UserName = "自定义属性1"; // 显示名称
|
||
property.value = value; // 属性值
|
||
|
||
// 添加到容器
|
||
propertyVector.Properties().Add(property);
|
||
|
||
// 设置到对象上
|
||
propertyNode.SetUserDefined(0, categoryName, internalName, propertyVector);
|
||
}
|
||
}
|
||
|
||
// ✅ 使用示例
|
||
AddCustomProperty("自定义分类", "Custom_Category", "自定义值");
|
||
```
|
||
|
||
#### 修改现有自定义属性
|
||
|
||
```csharp
|
||
// ✅ 正确的修改方法（基于实际修复经验和官方AutoUserPropsExample示例）
|
||
private void UpdateCustomProperty(string categoryName, string internalName, string newValue)
|
||
{
|
||
InwOpSelection2 selection = m_state.CurrentSelection as InwOpSelection2;
|
||
if (selection.Paths().Count > 0)
|
||
{
|
||
InwGUIPropertyNode2 propertyNode =
|
||
m_state.GetGUIPropertyNode(selection.Paths()[1], true) as InwGUIPropertyNode2;
|
||
|
||
// 🔍 关键第一步：查找现有属性分类的正确索引
|
||
int existingIndex = GetFloorAttributeIndex(propertyNode, categoryName);
|
||
|
||
// 创建新的属性内容
|
||
InwOaPropertyVec propertyVector =
|
||
m_state.ObjectFactory(nwEObjectType.eObjectType_nwOaPropertyVec);
|
||
|
||
InwOaProperty property =
|
||
m_state.ObjectFactory(nwEObjectType.eObjectType_nwOaProperty);
|
||
property.name = "Floor_Level";
|
||
property.UserName = "楼层";
|
||
property.value = newValue;
|
||
|
||
propertyVector.Properties().Add(property);
|
||
|
||
if (existingIndex >= 0)
|
||
{
|
||
// 🎯 存在属性时：使用正确的索引进行更新
|
||
// 注意：SetUserDefined的索引是从1开始的
|
||
int updateIndex = existingIndex + 1;
|
||
propertyNode.SetUserDefined(updateIndex, categoryName, internalName, propertyVector);
|
||
}
|
||
else
|
||
{
|
||
// 🆕 不存在属性时：使用索引0创建新属性分类
|
||
propertyNode.SetUserDefined(0, categoryName, internalName, propertyVector);
|
||
}
|
||
}
|
||
}
|
||
|
||
// ✅ 查找现有属性分类索引的正确方法
|
||
private int GetFloorAttributeIndex(InwGUIPropertyNode2 propertyNode, string categoryName)
|
||
{
|
||
int userDefinedIndex = 0; // 用户定义属性的索引计数器
|
||
|
||
foreach (InwGUIAttribute2 attribute in propertyNode.GUIAttributes())
|
||
{
|
||
if (attribute.UserDefined)
|
||
{
|
||
// ⚠️ 关键修复：只需要匹配ClassUserName，不需要匹配ClassName
|
||
// ClassName是系统生成的（如"LcOaPropOverrideCat"），不是我们控制的
|
||
if (attribute.ClassUserName == categoryName)
|
||
{
|
||
return userDefinedIndex; // 返回在用户定义属性中的索引位置
|
||
}
|
||
userDefinedIndex++;
|
||
}
|
||
}
|
||
return -1; // 未找到返回-1
|
||
}
|
||
|
||
// ✅ 使用示例 - 正确的更新方式
|
||
// 第一次设置：创建新属性
|
||
UpdateCustomProperty("分层信息", "Floor_Category", "F1");
|
||
// 第二次设置：找到并更新现有属性
|
||
UpdateCustomProperty("分层信息", "Floor_Category", "F2");
|
||
// 第三次设置：继续更新同一个属性
|
||
UpdateCustomProperty("分层信息", "Floor_Category", "F3");
|
||
```
|
||
|
||
**关键要点**（基于实际修复经验）：
|
||
|
||
- **动态索引查找**：不能使用硬编码索引，必须动态查找现有属性的位置
|
||
- **只匹配ClassUserName**：`ClassName`是系统生成的标识符（如`LcOaPropOverrideCat`），我们无法控制
|
||
- **索引转换规则**：查找返回的是0基索引，`SetUserDefined`使用的是1基索引
|
||
- **创建vs更新**：index=0表示创建新属性，index>0表示更新指定位置的属性
|
||
|
||
#### 删除自定义属性
|
||
|
||
```csharp
|
||
// ✅ 删除指定的自定义属性分类
|
||
private void RemoveCustomProperty()
|
||
{
|
||
InwOpSelection2 selection = m_state.CurrentSelection as InwOpSelection2;
|
||
if (selection.Paths().Count > 0)
|
||
{
|
||
InwGUIPropertyNode2 propertyNode =
|
||
m_state.GetGUIPropertyNode(selection.Paths()[1], true) as InwGUIPropertyNode2;
|
||
|
||
// 删除索引为0的用户自定义属性分类
|
||
propertyNode.RemoveUserDefined(0);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 12.3 两种API的选择建议
|
||
|
||
| 操作类型 | 推荐API | 理由 |
|
||
|---------|---------|------|
|
||
| 搜索和过滤 | NET API | LINQ查询更灵活，性能更好 |
|
||
| 读取标准属性 | NET API | 类型安全，代码简洁 |
|
||
| 添加/修改自定义属性 | COM API | 提供完整的属性操作能力 |
|
||
| 删除自定义属性 | COM API | NET API不支持属性删除 |
|
||
| 批量属性操作 | NET API | 支持ModelItemCollection批量操作 |
|
||
|
||
### 12.4 属性操作最佳实践
|
||
|
||
```csharp
|
||
// ✅ 推荐模式：结合两种API的优势
|
||
public void ProcessItemsWithCustomProperties()
|
||
{
|
||
// 1. 使用NET API进行搜索和过滤
|
||
var itemsWithGeometry = Application.ActiveDocument.Models.RootItemDescendantsAndSelf
|
||
.Where(item => item.HasGeometry && !item.IsHidden)
|
||
.ToList();
|
||
|
||
// 2. 对每个项目使用COM API添加自定义属性
|
||
foreach (ModelItem item in itemsWithGeometry)
|
||
{
|
||
// 选中当前项目
|
||
Application.ActiveDocument.CurrentSelection.Clear();
|
||
Application.ActiveDocument.CurrentSelection.Add(item);
|
||
|
||
// 使用COM API添加自定义属性
|
||
AddCustomProperty("物流信息", "Logistics_Info", $"处理时间: {DateTime.Now}");
|
||
}
|
||
}
|
||
```
|
||
|
||
### 12.5 常见属性操作示例
|
||
|
||
```csharp
|
||
// ✅ 检查项目是否有特定属性分类
|
||
public bool HasPropertyCategory(ModelItem item, string categoryName)
|
||
{
|
||
return item.PropertyCategories.FindCategoryByDisplayName(categoryName) != null;
|
||
}
|
||
|
||
// ✅ 获取项目的所有属性信息（用于调试）
|
||
public string GetItemPropertyInfo(ModelItem item)
|
||
{
|
||
var sb = new StringBuilder();
|
||
sb.AppendLine($"项目: {item.DisplayName}");
|
||
|
||
foreach (PropertyCategory category in item.PropertyCategories)
|
||
{
|
||
sb.AppendLine($" 分类: {category.DisplayName}");
|
||
foreach (DataProperty property in category.Properties)
|
||
{
|
||
sb.AppendLine($" {property.DisplayName}: {property.Value}");
|
||
}
|
||
}
|
||
|
||
return sb.ToString();
|
||
}
|
||
|
||
// ✅ 基于属性值进行复杂搜索
|
||
public List<ModelItem> FindItemsByPropertyValue(string categoryName, string propertyName, string searchValue)
|
||
{
|
||
return Application.ActiveDocument.Models.RootItemDescendantsAndSelf
|
||
.Where(item =>
|
||
{
|
||
var category = item.PropertyCategories.FindCategoryByDisplayName(categoryName);
|
||
if (category == null) return false;
|
||
|
||
var property = category.Properties.FirstOrDefault(p => p.DisplayName == propertyName);
|
||
return property != null && property.Value.ToString().Contains(searchValue);
|
||
})
|
||
.ToList();
|
||
}
|
||
```
|
||
|
||
### 12.6 Item属性的可编辑性分析
|
||
|
||
根据官方示例和Navisworks API设计，**大部分标准Item属性是只读的**，但有**少数属性可以编辑**。
|
||
|
||
#### 可编辑的Item属性
|
||
|
||
**1. 可见性和状态属性（通过Models API编辑）**
|
||
|
||
```csharp
|
||
// ✅ 可以修改：隐藏状态
|
||
document.Models.SetHidden(modelItemCollection, true);
|
||
|
||
// ✅ 可以修改：必需状态
|
||
document.Models.SetRequired(modelItemCollection, true);
|
||
|
||
// ✅ 可以修改：颜色覆盖
|
||
document.Models.OverridePermanentColor(modelItemCollection, Color.Red);
|
||
|
||
// ✅ 可以修改：透明度覆盖
|
||
document.Models.OverridePermanentTransparency(modelItemCollection, 0.5);
|
||
|
||
// ✅ 可以修改：Transform变换
|
||
document.Models.OverridePermanentTransform(modelItemCollection, transform, false);
|
||
```
|
||
|
||
**2. 基于官方Examiner.cs示例的确认**
|
||
|
||
```csharp
|
||
// 官方示例中的这些操作证实了这些属性是可修改的
|
||
document.Models.SetRequired(items, (required == SearchForm.ChangeDecision.Yes));
|
||
document.Models.SetHidden(items, (hidden == SearchForm.ChangeDecision.Yes));
|
||
document.Models.OverridePermanentColor(items, overrideColor);
|
||
document.Models.OverridePermanentTransparency(items, overrideTransparencyValue);
|
||
```
|
||
|
||
#### 只读的Item属性
|
||
|
||
**1. 基础标识属性（只读）**
|
||
|
||
```csharp
|
||
// ❌ 只读：无法修改，由原始CAD文件决定
|
||
item.DisplayName // 显示名称
|
||
item.ClassName // 类名
|
||
item.ClassDisplayName // 类显示名称
|
||
item.HasGeometry // 几何体标志
|
||
item.IsInsert // 插入对象标志
|
||
item.IsLayer // 图层标志
|
||
```
|
||
|
||
**2. 结构关系属性（只读）**
|
||
|
||
```csharp
|
||
// ❌ 只读：结构关系由模型文件决定，无法通过API修改
|
||
item.Parent // 父节点
|
||
item.Children // 子节点
|
||
item.Ancestors // 祖先节点
|
||
item.Descendants // 后代节点
|
||
```
|
||
|
||
**3. 几何和材质属性（只读）**
|
||
|
||
```csharp
|
||
// ❌ 只读：由原始CAD文件决定
|
||
item.Geometry // 几何信息
|
||
item.BoundingBox() // 包围盒
|
||
item.PropertyCategories // 标准属性分类（但可通过COM API添加自定义分类）
|
||
```
|
||
|
||
#### 特殊情况：自定义属性完全可编辑
|
||
|
||
通过COM API可以**完全控制自定义属性**：
|
||
|
||
```csharp
|
||
// ✅ 完全可编辑：自定义属性
|
||
// 添加新的自定义属性
|
||
propertyNode.SetUserDefined(index, categoryName, internalName, propertyVector);
|
||
|
||
// 修改现有自定义属性（重新设置）
|
||
propertyNode.SetUserDefined(index, categoryName, internalName, newPropertyVector);
|
||
|
||
// 删除自定义属性
|
||
propertyNode.RemoveUserDefined(index);
|
||
```
|
||
|
||
#### 物流插件的实际应用策略
|
||
|
||
**1. 使用可编辑的标准属性进行状态管理**
|
||
|
||
```csharp
|
||
// 物流分类可见性管理
|
||
document.Models.SetHidden(obstacleItems, true); // 隐藏障碍物
|
||
document.Models.SetHidden(loadingZoneItems, false); // 显示装卸区
|
||
|
||
// 路径可视化
|
||
document.Models.OverridePermanentColor(pathItems, pathColor); // 路径颜色标记
|
||
document.Models.OverridePermanentColor(selectedItems, highlightColor); // 选中高亮
|
||
|
||
// 动画和移动
|
||
document.Models.OverridePermanentTransform(movableItems, newTransform, false); // 物体移动动画
|
||
```
|
||
|
||
**2. 使用自定义属性存储业务数据**
|
||
|
||
```csharp
|
||
// 存储物流分类信息
|
||
AddCustomProperty("物流信息", "Logistics_Category", "装卸区");
|
||
AddCustomProperty("物流信息", "Access_Level", "高优先级");
|
||
AddCustomProperty("物流信息", "Capacity", "1000kg");
|
||
|
||
// 存储路径规划数据
|
||
AddCustomProperty("路径信息", "Path_ID", "Path_001");
|
||
AddCustomProperty("路径信息", "Path_Length", "15.5m");
|
||
AddCustomProperty("路径信息", "Travel_Time", "120s");
|
||
|
||
// 存储碰撞检测结果
|
||
AddCustomProperty("碰撞信息", "Collision_Status", "Safe");
|
||
AddCustomProperty("碰撞信息", "Last_Check", DateTime.Now.ToString());
|
||
```
|
||
|
||
**3. 只读属性用于查询和智能分析**
|
||
|
||
```csharp
|
||
// 基于只读属性进行智能空间分析
|
||
var suitableForStorage = items.Where(x =>
|
||
x.HasGeometry &&
|
||
x.ClassDisplayName.Contains("Room") &&
|
||
!x.IsHidden &&
|
||
x.BoundingBox().Max.Z > 3.0); // 高度足够的房间
|
||
|
||
// 基于结构关系进行逻辑分组
|
||
var floorItems = selectedFloor.DescendantsAndSelf
|
||
.Where(x => x.HasGeometry);
|
||
```
|
||
|
||
**4. 综合应用示例：物流节点标记**
|
||
|
||
```csharp
|
||
public void MarkAsLogisticsNode(ModelItem item, string category, Dictionary<string, string> properties)
|
||
{
|
||
var itemCollection = new ModelItemCollection { item };
|
||
|
||
// 1. 使用标准可编辑属性设置可视化
|
||
Color categoryColor = GetCategoryColor(category);
|
||
document.Models.OverridePermanentColor(itemCollection, categoryColor);
|
||
document.Models.SetRequired(itemCollection, true); // 标记为重要
|
||
|
||
// 2. 使用自定义属性存储详细信息
|
||
document.CurrentSelection.Clear();
|
||
document.CurrentSelection.Add(item);
|
||
|
||
AddCustomProperty("物流分类", "Category", category);
|
||
foreach (var kvp in properties)
|
||
{
|
||
AddCustomProperty("物流属性", kvp.Key, kvp.Value);
|
||
}
|
||
|
||
// 3. 基于只读属性进行验证
|
||
if (!item.HasGeometry)
|
||
{
|
||
LogManager.Warning($"警告：{item.DisplayName} 没有几何体，可能不适合作为物流节点");
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 属性编辑最佳实践
|
||
|
||
| 用途 | 推荐方法 | API类型 | 特点 |
|
||
|------|----------|---------|------|
|
||
| 状态标记 | SetHidden, SetRequired | NET API | 影响显示和选择 |
|
||
| 可视化 | OverridePermanentColor | NET API | 临时视觉效果 |
|
||
| 空间变换 | OverridePermanentTransform | NET API | 支持动画 |
|
||
| 业务数据 | SetUserDefined | COM API | 持久化存储 |
|
||
| 查询分析 | 只读属性 + LINQ | NET API | 高性能筛选 |
|
||
|
||
### 12.7 属性操作注意事项
|
||
|
||
1. **线程安全**：所有属性操作都必须在主UI线程中执行
|
||
2. **选择状态**：COM API属性操作需要先选中目标对象
|
||
3. **性能考虑**：大批量属性读取时，NET API性能更佳
|
||
4. **属性持久化**：自定义属性会保存在NWD文件中，标准属性覆盖是临时的
|
||
5. **属性索引**：COM API中的用户自定义属性使用索引管理
|
||
6. **错误处理**：属性不存在时API会返回null，需要检查
|
||
7. **属性类型限制**：只读属性无法通过API修改，只能通过可编辑API间接影响
|
||
8. **覆盖vs原始**：OverridePermanent系列方法是覆盖原始属性，可以恢复
|
||
|
||
### 12.8 COM API 自定义属性重要修复经验
|
||
|
||
基于实际生产环境中发现的问题和修复经验，这里记录COM API操作自定义属性时的关键要点。
|
||
|
||
#### 🚨 常见陷阱：重复创建属性分类
|
||
|
||
**问题现象**：对同一对象多次设置自定义属性时，会创建多个同名的属性分类，而不是更新现有属性。
|
||
|
||
**错误做法**：
|
||
|
||
```csharp
|
||
// ❌ 错误：硬编码索引会导致重复创建
|
||
propertyNode.SetUserDefined(1, "分层信息", "Floor_Category", propertyVector);
|
||
```
|
||
|
||
**正确做法**：
|
||
|
||
```csharp
|
||
// ✅ 正确：动态查找现有属性的索引
|
||
int existingIndex = GetFloorAttributeIndex(propertyNode, "分层信息");
|
||
if (existingIndex >= 0)
|
||
{
|
||
// 更新现有属性（注意索引转换：查找用0基，设置用1基）
|
||
propertyNode.SetUserDefined(existingIndex + 1, "分层信息", "Floor_Category", propertyVector);
|
||
}
|
||
else
|
||
{
|
||
// 创建新属性
|
||
propertyNode.SetUserDefined(0, "分层信息", "Floor_Category", propertyVector);
|
||
}
|
||
```
|
||
|
||
#### 🔍 ClassName vs ClassUserName 的区别
|
||
|
||
这是导致重复创建问题的根本原因：
|
||
|
||
**ClassUserName**：用户定义的显示名称，由我们控制
|
||
|
||
```csharp
|
||
// 我们定义的显示名称
|
||
attribute.ClassUserName == "分层信息"
|
||
```
|
||
|
||
**ClassName**：系统生成的内部标识符，我们无法控制
|
||
|
||
```csharp
|
||
// 系统生成的内部名称，每次可能不同
|
||
attribute.ClassName == "LcOaPropOverrideCat" // 系统生成，不可预测
|
||
```
|
||
|
||
**修复要点**：
|
||
|
||
```csharp
|
||
// ❌ 错误：同时匹配两个条件会导致找不到现有属性
|
||
if (attribute.UserDefined &&
|
||
attribute.ClassUserName == FLOOR_CATEGORY &&
|
||
attribute.ClassName == FLOOR_CATEGORY_INTERNAL)
|
||
|
||
// ✅ 正确：只匹配用户显示名称
|
||
if (attribute.UserDefined &&
|
||
attribute.ClassUserName == FLOOR_CATEGORY)
|
||
```
|
||
|
||
#### 📝 索引管理的正确方式
|
||
|
||
**索引计算规则**：
|
||
|
||
1. 遍历所有属性，只计算 `UserDefined == true` 的属性
|
||
2. 查找方法返回的是**0基索引**（第一个用户属性是0）
|
||
3. `SetUserDefined`方法使用的是**1基索引**（第一个用户属性是1）
|
||
4. `RemoveUserDefined`方法也使用**1基索引**
|
||
|
||
```csharp
|
||
// ✅ 正确的索引转换
|
||
int foundIndex = GetFloorAttributeIndex(propertyNode, categoryName); // 返回0, 1, 2...
|
||
if (foundIndex >= 0)
|
||
{
|
||
// SetUserDefined 需要1基索引
|
||
int setIndex = foundIndex + 1; // 转换为 1, 2, 3...
|
||
propertyNode.SetUserDefined(setIndex, categoryName, internalName, propertyVector);
|
||
|
||
// RemoveUserDefined 也需要1基索引
|
||
int removeIndex = foundIndex + 1; // 转换为 1, 2, 3...
|
||
propertyNode.RemoveUserDefined(removeIndex);
|
||
}
|
||
```
|
||
|
||
#### 🛠️ 完整的修复模板
|
||
|
||
```csharp
|
||
public class CustomPropertyManager
|
||
{
|
||
// ✅ 设置自定义属性的正确方式
|
||
public bool SetCustomProperty(ModelItem item, string categoryName,
|
||
string internalName, string propertyName,
|
||
string displayName, string value)
|
||
{
|
||
return ExecuteWithUIThread(() =>
|
||
{
|
||
var state = ComApiBridge.State;
|
||
var comPath = ComApiBridge.ToInwOaPath(item);
|
||
var propertyNode = (ComApi.InwGUIPropertyNode2)state.GetGUIPropertyNode(comPath, false);
|
||
|
||
// 🔍 关键：动态查找现有属性索引
|
||
int existingIndex = FindCustomPropertyIndex(propertyNode, categoryName);
|
||
|
||
// 创建属性内容
|
||
var propertyCategory = (ComApi.InwOaPropertyVec)state.ObjectFactory(
|
||
ComApi.nwEObjectType.eObjectType_nwOaPropertyVec, null, null);
|
||
|
||
var property = (ComApi.InwOaProperty)state.ObjectFactory(
|
||
ComApi.nwEObjectType.eObjectType_nwOaProperty, null, null);
|
||
property.name = propertyName;
|
||
property.UserName = displayName;
|
||
property.value = value;
|
||
propertyCategory.Properties().Add(property);
|
||
|
||
if (existingIndex >= 0)
|
||
{
|
||
// 🎯 更新现有属性（索引+1）
|
||
propertyNode.SetUserDefined(existingIndex + 1, categoryName, internalName, propertyCategory);
|
||
LogManager.Info($"更新现有属性分类 '{categoryName}' (index={existingIndex + 1})");
|
||
}
|
||
else
|
||
{
|
||
// 🆕 创建新属性（索引0）
|
||
propertyNode.SetUserDefined(0, categoryName, internalName, propertyCategory);
|
||
LogManager.Info($"创建新属性分类 '{categoryName}' (index=0)");
|
||
}
|
||
|
||
return true;
|
||
});
|
||
}
|
||
|
||
// ✅ 查找自定义属性索引的正确方式
|
||
private int FindCustomPropertyIndex(ComApi.InwGUIPropertyNode2 propertyNode, string categoryName)
|
||
{
|
||
int userDefinedIndex = 0;
|
||
|
||
foreach (ComApi.InwGUIAttribute2 attribute in propertyNode.GUIAttributes())
|
||
{
|
||
if (attribute.UserDefined)
|
||
{
|
||
// ⚠️ 关键：只匹配ClassUserName，不匹配ClassName
|
||
if (attribute.ClassUserName == categoryName)
|
||
{
|
||
return userDefinedIndex;
|
||
}
|
||
userDefinedIndex++;
|
||
}
|
||
}
|
||
return -1;
|
||
}
|
||
|
||
// ✅ 清除自定义属性的正确方式
|
||
public bool ClearCustomProperty(ModelItem item, string categoryName)
|
||
{
|
||
return ExecuteWithUIThread(() =>
|
||
{
|
||
var state = ComApiBridge.State;
|
||
var comPath = ComApiBridge.ToInwOaPath(item);
|
||
var propertyNode = (ComApi.InwGUIPropertyNode2)state.GetGUIPropertyNode(comPath, false);
|
||
|
||
int existingIndex = FindCustomPropertyIndex(propertyNode, categoryName);
|
||
if (existingIndex >= 0)
|
||
{
|
||
// 🗑️ 删除属性（索引+1）
|
||
propertyNode.RemoveUserDefined(existingIndex + 1);
|
||
LogManager.Info($"删除属性分类 '{categoryName}' (removed index={existingIndex + 1})");
|
||
return true;
|
||
}
|
||
else
|
||
{
|
||
LogManager.Info($"属性分类 '{categoryName}' 不存在，无需删除");
|
||
return false;
|
||
}
|
||
});
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 📋 问题诊断检查列表
|
||
|
||
当遇到属性重复创建问题时，检查以下要点：
|
||
|
||
- [ ] 是否使用了硬编码索引（如固定使用索引1）
|
||
- [ ] 是否同时匹配了`ClassUserName`和`ClassName`
|
||
- [ ] 是否正确进行了索引转换（0基→1基）
|
||
- [ ] 是否在主UI线程中执行COM API调用
|
||
- [ ] 日志中是否显示"未找到现有属性分类"但实际存在
|
||
|
||
#### 🎯 修复验证方法
|
||
|
||
**测试步骤**：
|
||
|
||
1. 选择一个对象，设置自定义属性（如"F1"）
|
||
2. 再次选择同一对象，设置不同值（如"F2"）
|
||
3. 检查属性面板，应该只有一个属性分类
|
||
4. 重复步骤2，设置第三个值（如"F3"）
|
||
5. 确认仍然只有一个属性分类，值为最新设置的值
|
||
|
||
**日志验证**：
|
||
|
||
```
|
||
[FloorAttributeManager] 找到楼层属性分类，索引为: 0
|
||
[FloorAttributeManager] ✅ 成功更新现有楼层属性分类 (index=1)
|
||
```
|
||
|
||
#### 💡 经验总结
|
||
|
||
1. **COM API的ClassUserName是关键**：这是我们控制的显示名称，用于匹配现有属性
|
||
2. **ClassName不可靠**：系统生成的内部标识符，每次可能不同
|
||
3. **索引转换至关重要**：查找用0基，设置/删除用1基
|
||
4. **动态索引查找必不可少**：硬编码索引是重复创建问题的根源
|
||
5. **详细日志帮助调试**：记录索引查找和转换过程，便于问题定位
|
||
|
||
## 13. 缓存刷新和状态同步 ⚠️ 重要
|
||
|
||
### 13.1 缓存刷新的必要性
|
||
|
||
在某些API操作（特别是自定义属性的删除）后，Navisworks内部缓存可能与实际状态不同步，导致：
|
||
|
||
- 搜索结果不准确
|
||
- 属性面板显示异常
|
||
- 后续API调用出现意外行为
|
||
|
||
### 13.2 安全的缓存刷新方法 ✅
|
||
|
||
基于实际生产环境的测试和验证，以下是推荐的缓存刷新方法：
|
||
|
||
```csharp
|
||
// ✅ 最安全的缓存刷新方法：空集合的SetHidden操作
|
||
public static void SafeCacheRefresh()
|
||
{
|
||
try
|
||
{
|
||
var document = NavisApplication.ActiveDocument;
|
||
if (document?.Models != null)
|
||
{
|
||
// 使用空集合的SetHidden操作触发缓存更新
|
||
// 这是一个几乎零开销的"伪操作"
|
||
var emptyCollection = new ModelItemCollection();
|
||
document.Models.SetHidden(emptyCollection, false);
|
||
LogManager.WriteLog("✅ 已执行轻量级缓存刷新");
|
||
}
|
||
}
|
||
catch (Exception ex)
|
||
{
|
||
LogManager.WriteLog($"⚠️ 缓存刷新失败，但不影响主要操作: {ex.Message}");
|
||
}
|
||
}
|
||
```
|
||
|
||
### 13.3 危险的缓存刷新方法 ❌
|
||
|
||
**⚠️ 避免使用以下方法，已确认会导致程序崩溃：**
|
||
|
||
```csharp
|
||
// ❌ 危险：会导致程序崩溃
|
||
document.Models.ResetAllTemporaryMaterials();
|
||
|
||
// ❌ 危险：重载过重，可能影响性能
|
||
document.ActiveView.RequestDelayedRedraw(ViewRedrawRequests.All);
|
||
|
||
// ❌ 危险：可能干扰用户界面状态
|
||
document.Models.ResetOverriddenTransparency(allItems);
|
||
```
|
||
|
||
### 13.4 何时需要缓存刷新
|
||
|
||
**必须刷新的操作**：
|
||
|
||
- COM API删除自定义属性后
|
||
- 大批量修改模型可见性后
|
||
- 复杂的Transform操作后
|
||
|
||
**可选刷新的操作**：
|
||
|
||
- 添加自定义属性（通常自动同步）
|
||
- 简单的颜色或透明度覆盖
|
||
- 单个对象的操作
|
||
|
||
### 13.5 实践模式：操作后刷新
|
||
|
||
```csharp
|
||
// ✅ 推荐模式：操作 + 刷新 + 验证
|
||
public int RemoveLogisticsAttributes(ModelItemCollection items)
|
||
{
|
||
int successCount = 0;
|
||
|
||
try
|
||
{
|
||
// 1. 执行主要操作
|
||
foreach (var item in items)
|
||
{
|
||
// COM API删除操作...
|
||
successCount++;
|
||
}
|
||
}
|
||
catch (Exception ex)
|
||
{
|
||
LogManager.WriteLog($"操作失败: {ex.Message}");
|
||
}
|
||
|
||
// 2. 如果有成功操作，执行缓存刷新
|
||
if (successCount > 0)
|
||
{
|
||
SafeCacheRefresh(); // 使用安全的刷新方法
|
||
}
|
||
|
||
return successCount;
|
||
}
|
||
```
|
||
|
||
### 13.6 缓存问题的诊断
|
||
|
||
**常见症状**：
|
||
|
||
- 删除属性后，搜索仍能找到已删除的属性
|
||
- 属性面板显示的内容与API返回不一致
|
||
- 连续相同操作的结果不同
|
||
|
||
**诊断代码**：
|
||
|
||
```csharp
|
||
// ✅ 验证缓存同步状态
|
||
public bool VerifyCacheSync(ModelItem item, string categoryName)
|
||
{
|
||
// 通过NET API检查
|
||
bool netApiResult = HasPropertyCategory(item, categoryName);
|
||
|
||
// 通过COM API检查
|
||
bool comApiResult = HasPropertyCategoryViaCom(item, categoryName);
|
||
|
||
if (netApiResult != comApiResult)
|
||
{
|
||
LogManager.Warning($"缓存不同步检测: NET={netApiResult}, COM={comApiResult}");
|
||
SafeCacheRefresh();
|
||
return false;
|
||
}
|
||
|
||
return true;
|
||
}
|
||
```
|
||
|
||
### 13.7 多线程环境下的缓存刷新
|
||
|
||
```csharp
|
||
// ✅ 线程安全的缓存刷新
|
||
public async Task SafeCacheRefreshAsync()
|
||
{
|
||
await System.Windows.Application.Current.Dispatcher.InvokeAsync(() =>
|
||
{
|
||
SafeCacheRefresh(); // 确保在主线程中执行
|
||
});
|
||
}
|
||
```
|
||
|
||
### 13.8 缓存刷新最佳实践
|
||
|
||
| 场景 | 刷新时机 | 刷新方法 | 必要性 |
|
||
|------|----------|----------|--------|
|
||
| 删除自定义属性 | 操作完成后 | 空集合SetHidden | 必须 |
|
||
| 批量隐藏对象 | 操作完成后 | 可选择不刷新 | 可选 |
|
||
| Transform动画 | 动画结束后 | 空集合SetHidden | 推荐 |
|
||
| 颜色覆盖 | 通常不需要 | 无 | 不需要 |
|
||
|
||
**关键原则**：
|
||
|
||
1. **安全第一**：只使用验证过的安全方法
|
||
2. **按需刷新**：不是所有操作都需要缓存刷新
|
||
3. **异常处理**：缓存刷新失败不应该影响主要功能
|
||
4. **线程安全**：在主UI线程中执行刷新操作
|
||
|
||
## 14. 参考官方示例
|
||
|
||
强烈建议查看以下官方示例了解更多用法：
|
||
|
||
- `SearchComparisonPlugIn.cs` - 搜索性能对比和属性搜索
|
||
- `Examiner.cs` - LINQ查询和属性过滤示例
|
||
- `AutoUserPropsExample.cs` - COM API自定义属性操作
|
||
- `BasicDockPanePlugin.cs` - 基础插件结构
|
||
- `DatabaseDockPane/Models.cs` - 数据库操作示例
|
||
- `ClashDetective` 相关示例 - 高级功能示例
|