【CATIA的二次开发23】抽象对象Document涉及文档激活控制的方法
在CATIA VBA开发中，Document对象是最核心、最基础的对象之一。它代表了当前在CATIA会话中打开的一个文档（文件）。
几乎所有与文件操作、模型访问相关的操作都始于获取一个Document对象。Document对象包含多种方法和属性，以下介绍Document对象方法和属性
一、Document对象方法
1、方法和属性列表
2、方法分类
| 分类 | 方法 | 功能描述 | 适用文档类型 | 示例代码 |
|---|---|---|---|---|
| 文档激活控制 | Activate | 激活文档使其成为当前活动文档 | 所有文档类型 | targetDoc.Activate |
| NewWindow | 为文档创建新窗口 | 所有文档类型 | doc.NewWindow | |
| 文档生命周期 | Close | 关闭文档 | 所有文档类型 | doc.Close catSaveChanges |
| Save | 保存文档 | 所有文档类型 | If Not doc.Saved Then doc.Save | |
| SaveAs | 文档另存为 | 所有文档类型 | doc.SaveAs “C:\NewName.CATPart” | |
| 数据交换 | ExportData | 导出文档为其他格式 | 所有文档类型 | doc.ExportData “C:\export.stp”, “stp” |
| 交互选择 | Indicate2D | 在2D环境(工程图)中交互选择元素 | DrawingDocument | Set elem = doc.Indicate2D(“选择元素”, catSelectionFilterDimension) |
| Indicate3D | 在3D环境(零件/装配)中交互选择元素 | PartDocument ProductDocument | Set face = doc.Indicate3D(“选择面”, catSelectionFilterFace) | |
| 对象引用 | CreateReferenceFromName | 通过名称创建对象引用 | 所有文档类型 | Set ref = doc.CreateReferenceFromName(“Part1\Sketch.1”) |
| GetItem | 通过名称获取文档中的项目(参数、关系等) | 所有文档类型 | Set param = doc.GetItem(“LengthParam”) | |
| 工作环境控制 | GetWorkbench | 获取指定工作台对象 | 所有文档类型 | Set pdWB = doc.GetWorkbench(“PartDesignWorkbench”) |
| 选择过滤 | CreateFilter | 创建选择过滤器 | 所有文档类型 | Set filter = doc.CreateFilter(“FaceFilter”) |
| RemoveFilter | 移除选择过滤器 | 所有文档类型 | doc.RemoveFilter filter |
二、方法～文档激活控制(Activate方法和NewWindow方法)
1、Activate方法
在CATIA VBA开发中，Document 对象的Activate方法 用于将指定的文档设置为当前活动文档（即获得焦点的文档）。
当CATIA会话中有多个文档打开时，该方法至关重要，因为它决定了后续操作将在哪个文档上执行。
- 方法功能
- 目标文档会前置显示在 CATIA 窗口中（如果被遮挡）；
- 该文档成为当前操作上下文（后续代码默认作用于该文档）；
- CATIA.ActiveDocument 属性会自动更新为被激活的文档。
- 方法语法
myDocument.Activate
- 典型使用场景
场景一：切换活动文档（多文档操作）
Dim doc1 As Document, doc2 As Document
Set doc1 = CATIA.Documents.Open("C:\Part1.CATPart")
Set doc2 = CATIA.Documents.Open("C:\Assembly1.CATProduct")' 激活零件文档
doc1.Activate
' 此时在 Part1 上操作...' 切换到装配文档
doc2.Activate
' 后续操作在 Assembly1 上进行
场景二：确保文档处于活动状态
' 获取非活动文档的引用
Dim inactiveDoc As Document
Set inactiveDoc = CATIA.Documents.Item(2) ' 假设是第二个打开的文档' 强制激活它
inactiveDoc.Activate' 现在可以安全操作该文档
Dim sel As Selection
Set sel = CATIA.ActiveDocument.Selection ' 正确获取选择集
场景三：新建文档后立即激活
Dim newDrawing As Document
Set newDrawing = CATIA.Documents.Add("Drawing")
newDrawing.Activate ' 确保新工程图成为当前文档' 直接操作新文档
Dim sheet1 As DrawingSheet
Set sheet1 = newDrawing.Sheets.Item("Sheet.1")
- 重要注意事项
- 非阻塞方法
Activate 方法会立即返回，但 CATIA 界面可能需要短暂时间完成切换（通常无需额外等待） - 与 ActiveDocument 的关系激活后，以下等式成立：
myDocument.Activate Debug.Print (myDocument Is CATIA.ActiveDocument) ' 输出 True- 避免不必要的激活
如果只需读取文档属性（如 Name, Path），无需激活：
' 不激活即可获取信息 Dim docName As String docName = myDocument.Name- 错误处理
尝试激活已关闭的文档会引发错误：
On Error Resume Next myDocument.Activate If Err.Number <> 0 ThenMsgBox "文档已关闭或无效" End If - 非阻塞方法
- 最佳实践
' 安全激活文档的模板代码
Sub SafeActivate(targetDoc As Document)On Error GoTo err_handlertargetDoc.ActivateExit Suberr_handler:If Err.Number = -2147467259 Then ' 典型错误号MsgBox "无法激活文档: " & targetDoc.Name & vbCrLf & _"可能已被关闭", vbExclamationElseMsgBox "未知错误: " & Err.DescriptionEnd If
End Sub
- 经验总结
| 方法 | 作用 | 是否需要激活文档 |
|---|---|---|
| Activate | 切换活动文档 | 前置条件 |
| Save | 保存文档 | 否 |
| Close | 关闭文档 | 否 |
| GetItem | 按名称获取文档内对象 | 否（但对象需有效） |
| Update | 强制更新文档特征 | 否 |
2、NewWindow方法
在 CATIA VBA 开发中，Document.NewWindow 方法 是一个强大的多窗口管理工具，用于为当前文档创建新的独立视图窗口。
这个方法在需要同时查看同一文档的不同区域或视角时特别有用，显著提升设计效率和可视化能力。
- 方法功能
为当前文档创建新的视图窗口 - 方法语法
Function NewWindow() As Window- 返回值：新创建的 Window 对象
- 核心功能与优势
- 多视图协同
同时查看模型的多个视角（如俯视图、前视图、3D视图） - 独立控制
每个窗口可独立设置：- 缩放级别
- 观察角度
- 渲染模式
- 显示/隐
- 多视图协同