【CATIA的二次开发24】抽象对象Document涉及文档生命周期的方法-CSDN博客

本文链接：https://blog.csdn.net/qq124512097com/article/details/148530731

在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 -1
    docs.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
Else
    doc.Close catDoNotSaveChanges
End If

错误处理

On Error Resume Next
doc.Close
If Err.Number = -2147220698 Then
    MsgBox "文档已被其他进程锁定"
ElseIf Err.Number <> 0 Then
    MsgBox "关闭错误: " & 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 String
    testName = targetDoc.Name  ' 尝试访问属性
    
    If Err.Number = 0 Then
        targetDoc.Close saveOption
    Else
        Err.Clear  ' 清除错误
    End If
End Sub

关闭前保存检查

Sub CloseWithBackup(doc As Document)
    If Not doc.Saved Then
        Dim backupPath As String
        backupPath = "C:\Backups\" & Format(Now, "yyyymmdd_hhmmss_") & doc.Name
        
        doc.SaveAs backupPath  ' 创建备份
        MsgBox "已创建备份: " & backupPath
    End If
    
    doc.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.Save
    MsgBox "文档已保存: " & doc.FullName
Else
    MsgBox "文档无修改，无需保存"
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
Else
    doc.Save
End If

高级应用场景

场景一：批量保存所有修改文档

Sub SaveAllModifiedDocuments()
    Dim docs As Documents
    Set docs = CATIA.Documents
    
    Dim doc As Document
    For Each doc In docs
        If Not doc.Saved And Not doc.ReadOnly Then
            On Error Resume Next ' 错误处理
            doc.Save
            If Err.Number = 0 Then
                LogAction "已保存: " & doc.Name
            Else
                LogAction "保存失败: " & doc.Name & " - " & Err.Description
            End If
            On Error GoTo 0
        End If
    Next
End Sub

场景二：带版本控制的自动保存

Sub AutoSaveWithVersioning()
    Dim doc As Document
    Set doc = CATIA.ActiveDocument
    Dim version As Integer
    
    ' 获取当前版本号
    version = GetDocumentVersion(doc)
    
    ' 生成版本化文件名
    Dim newPath As String
    newPath = "C:\Versions\" & GetBaseName(doc.Name) & "_v" & version + 1 & ".CATPart"
    
    ' 执行版本保存
    doc.SaveAs newPath
    UpdateVersionMetadata(doc, version + 1)
End Sub

Function GetDocumentVersion(doc As Document) As Integer
    ' 从自定义属性获取版本号
    On Error Resume Next
    GetDocumentVersion = doc.Part.UserRefProperties.Item("Version").Value
    If Err.Number <> 0 Then
        GetDocumentVersion = 1 ' 默认版本
    End If
End Function

场景三：保存前自动清理

Sub CleanAndSave()
    Dim doc As Document
    Set doc = CATIA.ActiveDocument
    
    ' 仅零件文档需要清理
    If doc.Type = "Part" Then
        ' 压缩历史记录
        doc.Part.CompressHistory
        
        ' 删除空几何图形集
        Dim hybridBody As HybridBody
        For Each hybridBody In doc.Part.HybridBodies
            If hybridBody.HybridShapes.Count = 0 Then
                hybridBody.Delete
            End If
        Next
    End If
    
    ' 执行保存
    doc.Save
End Sub

场景四：保存到云存储

Sub SaveToCloudStorage()
    Dim doc As Document
    Set doc = CATIA.ActiveDocument
    
    ' 本地临时保存
    Dim tempPath As String
    tempPath = Environ("TEMP"