在 AutoCAD C# 二次开发中，`DocumentCollectionEventHandler` 是一个委托（delegate）**，用于处理与 AutoCAD 文档集合（DocumentCollection）相关的事件。它属于 AutoCAD .NET API 的事件处理机制，本质上是一种**反应器（Reactor）模式**的实现，用于响应文档生命周期事件（如创建、激活、销毁文档等）。
核心概念解释：
- **DocumentCollection**
`Application.DocumentManager` 属性返回当前 AutoCAD 会话中所有打开文档的集合（`DocumentCollection`类）。
- **事件类型**
`DocumentCollection` 包含以下关键事件：
-
`DocumentCreated`：创建新文档时触发
-
`DocumentActivated`：切换活动文档时触发
-
`DocumentToBeDestroyed`：文档关闭前触发
-
`DocumentLockModeChanged`：文档锁定状态变化时触发
- **DocumentCollectionEventHandler**
这是处理上述事件的**委托签名**，定义如下：
```csharp
public delegate void DocumentCollectionEventHandler(
object sender,
DocumentCollectionEventArgs e
);
```
完整代码示例（响应文档切换事件）
以下示例演示如何监听文档激活事件，并在切换文档时执行操作：
```csharp
using Autodesk.AutoCAD.ApplicationServices;
using Autodesk.AutoCAD.Runtime;
using Autodesk.AutoCAD.EditorInput;
public class DocumentEventReactor
{
// 初始化时订阅事件
public DocumentEventReactor()
{
DocumentCollection docCol = Application.DocumentManager;
docCol.DocumentActivated += OnDocumentActivated;
}
// 文档激活事件处理
private void OnDocumentActivated(object sender, DocumentCollectionEventArgs e)
{
Document activeDoc = e.Document;
Editor ed = activeDoc.Editor;
// 获取文档名称（不含路径）
string docName = System.IO.Path.GetFileName(activeDoc.Name);
// 在命令行显示提示
ed.WriteMessage($"\n切换到文档: {docName} | 事件类型: {e.GetType().Name}");
// 示例扩展操作：检查文档是否只读
if (activeDoc.Database.ReadOnly)
{
ed.WriteMessage("\n警告：当前文档为只读模式！");
}
}
// 清理时取消订阅（重要！）
public void Unsubscribe()
{
DocumentCollection docCol = Application.DocumentManager;
docCol.DocumentActivated -= OnDocumentActivated;
}
}
// 在插件入口初始化
public class PluginCommands : IExtensionApplication
{
private static DocumentEventReactor _reactor;
public void Initialize()
{
_reactor = new DocumentEventReactor();
Application.DocumentManager.MdiActiveDocument.Editor.WriteMessage(
"\n文档事件反应器已启动");
}
public void Terminate()
{
_reactor?.Unsubscribe();
}
}
```
关键功能说明：
- **事件响应场景**：
-
用户新建/打开文档
-
在多个图形窗口间切换
-
关闭文档前执行清理操作
-
同步不同文档间的状态
- **实际应用场景**：
-
**多文档协同**：在文档切换时更新全局变量
-
**许可控制**：限制特定文档的功能访问
-
**日志记录**：跟踪用户操作路径
-
**资源管理**：文档关闭时释放关联资源
- **注意事项**：
-
**必须显式取消订阅**：否则导致内存泄漏（在 `Terminate()` 或 `Dispose()` 中处理）
-
**避免耗时操作**：事件处理应快速完成，否则影响用户体验
-
**线程安全**：事件在 AutoCAD 主线程触发，可直接操作 UI
其他常用事件处理示例：
响应文档创建事件
```csharp
Application.DocumentManager.DocumentCreated += (sender, e) =>
{
Editor ed = e.Document.Editor;
ed.WriteMessage($"\n新文档已创建: {e.Document.Name}");
};
```
响应文档关闭事件
```csharp
Application.DocumentManager.DocumentToBeDestroyed += (sender, e) =>
{
// 保存自定义数据到外部文件
string backupPath = $"C:\\Backups\\{e.Document.Name}.settings";
SaveCustomData(e.Document, backupPath);
};
```
通过合理利用 `DocumentCollectionEventHandler`，您可以构建响应 AutoCAD 文档环境变化的智能插件，显著提升用户体验和自动化水平。
