【CATIA的二次开发24】抽象对象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 |
二、方法～文档生命周期(Close方法、Save方法和SaveAs方法)
1、Close方法
在 CATIA VBA 开发中，Document 对象的 Close 方法 用于关闭当前文档。
这是管理文档生命周期的重要方法，允许开发者以编程方式控制文档的关闭行为，特别是处理未保存的更改时。
- 方法功能
- 关闭当前文档，释放系统资源
- 可选择保存或不保存更改
- 关闭后文档对象引用失效
- 方法语法
Sub Close([SaveChanges As CatSaveStatus])-
SaveChanges (可选参数)：
指定关闭时如何处理未保存的更改，使用 CatSaveStatus 枚举值：- catSaveForClosing (默认值)：提示用户保存（如果有未保存更改）
- catDoNotSaveChanges：不保存直接关闭
- catSaveChanges：保存更改后关闭
参数值 常量 值 行为 保存更改 catSaveChanges 1 保存更改后关闭 不保存更改 catDoNotSaveChanges 2 不保存直接关闭 未指定参数 - - 对未保存文档弹出保存提示框
-
- 使用示例
1、完成操作后清理资源；2、批量处理多个文档；3、实现文档自动清理机制；4、关闭不需要的临时文档。
场景一：默认关闭（提示保存）
Dim doc As Document
Set doc = CATIA.ActiveDocument
doc.Close ' 等同于 doc.Close catSaveForClosing
场景二：强制不保存关闭
doc.Close catDoNotSaveChanges ' 放弃所有未保存的更改
场景三：保存后关闭
doc.Close catSaveChanges ' 自动保存后关闭文档
场景四：关闭所有打开文档
Dim docs As Documents
Set docs = CATIA.Documents' 必须从后向前遍历（关闭后集合会变化）
For i = docs.Count To 1 Step -1docs.Item(i).Close catDoNotSaveChanges ' 不保存关闭所有
Next i
- 关键特性与注意事项
- 未保存文档处理
新建未保存文档使用 catSaveChanges 会触发"另存为"对话框
Dim newDoc As Document Set newDoc = CATIA.Documents.Add("Part") newDoc.Close catSaveChanges ' 弹出保存对话框- 关闭后对象状态
关闭后文档对象即失效，继续访问会引发运行时错误
doc.Close Debug.Print doc.Name ' 错误 424: 对象已释放!- 只读文档行为
Set doc = CATIA.Documents.Open("C:\ReadOnly.Part", True) ' 以只读打开 doc.Close catSaveChanges ' 忽略保存请求直接关闭- 与保存状态的关系
If doc.Saved = False Then' 有未保存更改时的特殊处理doc.Close catSaveChanges Elsedoc.Close catDoNotSaveChanges End If- 错误处理
On Error Resume Next doc.Close If Err.Number = -2147220698 ThenMsgBox "文档已被其他进程锁定" ElseIf Err.Number <> 0 ThenMsgBox "关闭错误: " & Err.Description End If- ⚠️ 重要提示：关闭文档后，所有关联对象（如 Part、Product 等）都会失效。
继续使用这些对象引用将导致"对象已释放"错误(Error 424)。
- 未保存文档处理
- 最佳实践
- 安全关闭函数
Sub SafeCloseDocument(targetDoc As Document, Optional saveOption As CatSaveStatus = catSaveForClosing)On Error Resume Next' 检查文档是否有效If targetDoc Is Nothing Then Exit Sub' 检查文档是否已关闭Dim testName As StringtestName = targetDoc.Name ' 尝试访问属性If Err.Number = 0 ThentargetDoc.Close saveOptionElseErr.Clear ' 清除错误End If End Sub- 关闭前保存检查
Sub CloseWithBackup(doc As Document)If Not doc.Saved ThenDim backupPath As StringbackupPath = "C:\Backups\" & Format(Now, "yyyymmdd_hhmmss_") & doc.Namedoc.SaveAs backupPath ' 创建备份MsgBox "已创建备份: " & backupPathEnd Ifdoc.Close catDoNotSaveChanges End Sub
2、Save方法
在 CATIA VBA 开发中，Document.Save 方法 是文档持久化的核心操作，用于将当前文档的修改保存到其关联文件。
这个方法在自动化工作流中至关重要，确保设计变更被正确持久化，避免数据丢失。
- 方法功能
- 将文档保存到当前关联文件
- 对新建文档会触发"另存为"对话框
- 更新文件修改时间和版本信息
- 清除"未保存"状态标志
- 新建文档：弹出"另存为"对话框
- 只读文档：保存失败，返回错误
- 未更改文档：无操作，直接返回
- 方法语法
Sub Save()- 对已保存过的文档：覆盖原文件
- 对新文档：触发"另存为"对话框（等同于 SaveAs）
- 关键特性与行为
1、定期自动保存；2、关键操作后保存进度；3、文档修改后持久化存储；4、准备导出或共享前的保存。
场景一：保存状态管理
Dim doc As Document
Set doc = CATIA.ActiveDocument' 检查文档是否需要保存
If Not doc.Saved Then' 执行保存操作doc.SaveMsgBox "文档已保存: " & doc.FullName
ElseMsgBox "文档无修改，无需保存"
End If
场景二：新文档处理
' 创建新文档
Dim newDoc As Document
Set newDoc = CATIA.Documents.Add("Part")' 添加内容...
newDoc.Part.HybridBodies.Add' 首次保存会触发另存为行为
newDoc.Save ' 将弹出保存对话框
场景三：只读文档处理
If doc.ReadOnly Then' 只读文档需要另存为doc.SaveAs "C:\Modified_" & doc.Name
Elsedoc.Save
End If
- 高级应用场景
场景一： 批量保存所有修改文档
Sub SaveAllModifiedDocuments()Dim docs As DocumentsSet docs = CATIA.DocumentsDim doc As DocumentFor Each doc In docsIf Not doc.Saved And Not doc.ReadOnly ThenOn Error Resume Next ' 错误处理doc.SaveIf Err.Number = 0 ThenLogAction "已保存: " & doc.NameElseLogAction "保存失败: " & doc.Name & " - " & Err.DescriptionEnd IfOn Error GoTo 0End IfNext
End Sub
场景二： 带版本控制的自动保存
Sub AutoSaveWithVersioning()Dim doc As DocumentSet doc = CATIA.ActiveDocumentDim version As Integer' 获取当前版本号version = GetDocumentVersion(doc)' 生成版本化文件名Dim newPath As StringnewPath = "C:\Versions\" & GetBaseName(doc.Name) & "_v" & version + 1 & ".CATPart"' 执行版本保存doc.SaveAs newPathUpdateVersionMetadata(doc, version + 1)
End SubFunction GetDocumentVersion(doc As Document) As Integer' 从自定义属性获取版本号On Error Resume NextGetDocumentVersion = doc.Part.UserRefProperties.Item("Version").ValueIf Err.Number <> 0 ThenGetDocumentVersion = 1 ' 默认版本End If
End Function
场景三： 保存前自动清理
Sub CleanAndSave()Dim doc As DocumentSet doc = CATIA.ActiveDocument' 仅零件文档需要清理If doc.Type = "Part" Then' 压缩历史记录doc.Part.CompressHistory' 删除空几何图形集Dim hybridBody As HybridBodyFor Each hybridBody In doc.Part.HybridBodiesIf hybridBody.HybridShapes.Count = 0 ThenhybridBody.DeleteEnd IfNextEnd If' 执行保存doc.Save
End Sub
场景四：保存到云存储
Sub SaveToCloudStorage()Dim doc As DocumentSet doc = CATIA.ActiveDocument' 本地临时保存Dim tempPath As StringtempPath = Environ("TEMP"