【CATIA的二次开发13】根对象Application的Documents集合方法

【CATIA的二次开发12】根对象Application Documents集合的方法

CATIA二次开发第一步：引用或获取Application 对象这个CATIA的入口（根对象），之后进行其它操作。（引用或获取Application 对象阅读【CATIA的二次开发11】CATIA V5对象层次结构)。

Application 对象的 Documents 集合是管理所有打开的CATIA文档（如零件、装配、工程图等）的核心接口。它提供了对文档生命周期的全面控制，涵盖创建、访问、保存、关闭等操作。以下是其功能作用的详细解析：

一、Documents 集合的核心功能

Documents 集合是 Application 对象下用于操作文档的入口，主要功能包括：

创建新文档：支持生成零件、装配、工程图等不同类型的文档。
访问现有文档：通过索引或文件名获取已打开的文档对象。
批量管理文档：遍历所有文档进行统一操作（如保存、关闭）。
监控文档状态：获取当前打开的文档数量及详细信息。

二、Documents 属性、方法和对象

Documents的各种功能是通过属性、方法和对象来实现的，包括的属性、方法和对象如下图：

三、常用方法

3.1、Add方法

在CATIA VBA开发中，Documents集合的Add方法用于创建新的文档（如零件、装配、工程图等）。

语法

Function Add(DocumentType As String) As Document

参数：

DocumentType：字符串，指定要创建的文档类型（例如”Part”、“Product”、“Drawing”）。
返回值：返回新创建的文档对象（Document类型）。

基础用法示例

创建新零件文档

Sub CreatePart()
    Dim newPartDoc As PartDocument
    Set newPartDoc = CATIA.Documents.Add("Part")

    ' 访问零件对象并添加几何体
    Dim part As Part
    Set part = newPartDoc.Part
    part.Bodies.Add
End Sub

创建新装配文档

Sub CreateDrawing()
    Dim newDrawingDoc As DrawingDocument
    Set newDrawingDoc = CATIA.Documents.Add("Drawing")

    ' 添加图纸页（Sheet）
    Dim sheet As Sheet
    Set sheet = newDrawingDoc.Sheets.Add
End Sub

创建新工程图

Sub CreateDrawing()
    Dim newDrawingDoc As DrawingDocument
    Set newDrawingDoc = CATIA.Documents.Add("Drawing")

    ' 添加图纸页（Sheet）
    Dim sheet As Sheet
    Set sheet = newDrawingDoc.Sheets.Add
End Sub

关键注意事项

类型转换
Add方法返回的文档对象为Document类型，需显式转换为具体类型（如PartDocument）以访问专用功能：

Dim partDoc As PartDocument
Set partDoc = CATIA.Documents.Add("Part")

错误处理
如果传入无效的文档类型字符串，CATIA会抛出错误。建议使用错误处理：

On Error Resume Next
Set doc = CATIA.Documents.Add("InvalidType")
If Err.Number <> 0 Then
    MsgBox "无效的文档类型！"
End If
On Error GoTo 0

文档激活
新创建的文档会自动成为当前活动文档，可通过CATIA.ActiveDocument访问：

Dim activeDoc As Document
Set activeDoc = CATIA.ActiveDocument

扩展应用

批量创建文档

Sub BatchCreateDocuments()
    Dim docTypes As Variant
    docTypes = Array("Part", "Product", "Drawing")

    Dim i As Integer
    For i = 0 To UBound(docTypes)
        CATIA.Documents.Add(docTypes(i))
    Next
End Sub

创建后自动保存

Sub CreateAndSave()
Dim partDoc As PartDocument
Set partDoc = CATIA.Documents.Add("Part")

' 添加内容（例如几何体）
partDoc.Part.Bodies.Add

' 保存到指定路径
partDoc.SaveAs "C:MyPartsNewPart.CATPart"
End Sub

3.2、Item方法

在CATIA VBA开发中，Application.Documents集合的 Item 方法是访问和管理当前会话中已打开文档的核心工具。

语法

Function Item(Index As Variant) As Document

参数：

Index：可以是整数索引（从1开始）或字符串文档名称（需包含扩展名）。
返回值：返回匹配的文档对象（Document类型）。

基础用法示例

通过索引访问文档
索引范围：从 1 到 Documents.Count。

Dim firstDoc As Document
Set firstDoc = CATIA.Documents.Item(1)  ' 获取第一个打开的文档

通过名称访问文档
名称规则：需完整文件名（含扩展名，如.CATPart），区分大小写。

Dim targetDoc As Document
Set targetDoc = CATIA.Documents.Item("Assembly.CATProduct")

典型用法示例

遍历所有打开的文档

Sub ListAllDocuments()
    Dim docs As Documents
    Set docs = CATIA.Documents

    Dim doc As Document
    For Each doc In docs
        MsgBox "文档名: " & doc.Name & ", 类型: " & TypeName(doc)
    Next
End Sub

批量关闭所有零件文档

Sub CloseAllPartDocuments()
    Dim i As Integer
    For i = CATIA.Documents.Count To 1 Step -1  ' 倒序避免索引错位
        Dim doc As Document
        Set doc = CATIA.Documents.Item(i)
        If TypeName(doc) = "PartDocument" Then
            doc.Close True  ' 强制关闭不保存
        End If
    Next
End Sub

通过名称动态操作文档

Sub UpdateSpecificDocument()
    On Error Resume Next  ' 防止文档未找到时报错
    Dim doc As Document
    Set doc = CATIA.Documents.Item("DesignV2.CATProduct")

    If Not doc Is Nothing Then
        Dim productDoc As ProductDocument
        Set productDoc = doc  ' 类型转换
        productDoc.Product.Parameters.Item("Version").Value = "3.0"
        doc.Save
    Else
        MsgBox "文档未打开！"
    End If
    On Error GoTo 0
End Sub

关键注意事项

索引越界处理
当索引超出范围（例如Documents.Count = 0时访问Item(1)），会触发运行时错误。建议添加检查逻辑：

If CATIA.Documents.Count > 0 Then
    Set doc = CATIA.Documents.Item(1)
End If

同名文档冲突
若有多个同名文档，Item方法返回第一个匹配项。需遍历集合筛选所有同名文档：

If CATIA.Documents.Count > 0 Then
    Set doc = CATIA.Documents.Item(1)
End If

类型安全操作
Item方法返回Document通用对象，需转换为具体类型（如PartDocument）以访问专用接口：

Dim partDoc As PartDocument
Set partDoc = CATIA.Documents.Item("Part1.CATPart")
partDoc.Part.Bodies.Add  ' 仅限PartDocument可用

错误处理技巧

捕获无效名称或索引

Sub SafeAccess()
    On Error Resume Next
    Dim doc As Document
    Set doc = CATIA.Documents.Item("NonExistingDoc.CATPart")

    If Err.Number <> 0 Then
        MsgBox "错误: " & Err.Description
        Err.Clear
    End If
    On Error GoTo 0
End Sub

验证文档类型

If TypeName(doc) = "ProductDocument" Then
    ' 执行装配相关操作
End If

高级应用场景

跨文档数据交换

Sub CopyParametersBetweenDocs()
    Dim srcDoc As Document
    Set srcDoc = CATIA.Documents.Item("Source.CATPart")
    Dim srcPart As Part
    Set srcPart = srcDoc.Part

    Dim tgtDoc As Document
    Set tgtDoc = CATIA.Documents.Item("Target.CATPart")
    Dim tgtPart As Part
    Set tgtPart = tgtDoc.Part

    ' 复制参数值
    tgtPart.Parameters.Item("Length").Value = srcPart.Parameters.Item("Length").Value
End Sub

自动化文档关联更新

Sub UpdateLinkedDocuments()
    Dim mainProduct As ProductDocument
    Set mainProduct = CATIA.Documents.Item("MainAssembly.CATProduct")

    Dim component As Product
    For Each component In mainProduct.Product.Products
        Dim linkedDoc As Document
        Set linkedDoc = CATIA.Documents.Item(component.Name & ".CATPart")
        linkedDoc.Part.Parameters.Item("Revision").Value = "B"
    Next
End Sub

性能优化建议

减少冗余调用：避免在循环中重复调用Item方法，优先缓存对象：

Dim docs As Documents
Set docs = CATIA.Documents
Dim count As Integer
count = docs.Count  ' 缓存Count值

优先使用For Each：遍历时效率高于索引循环：

For Each doc In CATIA.Documents  ' 更高效
    ' 操作代码
Next

常见问题

为什么Item(“MyPart”)返回Nothing？
未包含扩展名（如.CATPart），或文档未打开。
如何处理文档被锁定？

If doc.ReadOnly Then
    MsgBox "文档只读，无法修改！"
End If

如何获取文档的完整路径？

Dim path As String
path = doc.FullName  ' 返回完整路径（如"C:ProjectPart1.CATPart"）

通过灵活运用Item方法，可以实现对CATIA文档的精准控制和批量操作，是自动化开发中不可或缺的核心接口。
建议结合Documents.Add和Documents.Open方法，构建完整的文档管理流程。

3.3、Open方法

在CATIA VBA开发中，Application.Documents集合的 Open 方法用于打开指定路径的文档（如零件、装配体、工程图等）。

语法

Function Open(FilePath As String) As Document

参数：

FilePath：字符串，指定要打开的文档完整路径（需包含扩展名，如.CATPart, .CATProduct）。
返回值：返回打开的文档对象（Document类型）。

基础用法示例

打开单个文档

Sub OpenSingleDocument()
    Dim docPath As String
    docPath = "C:ProjectEngineBlock.CATPart"

    Dim partDoc As Document
    Set partDoc = CATIA.Documents.Open(docPath)

    ' 验证是否成功打开
    If Not partDoc Is Nothing Then
        MsgBox "文档已打开: " & partDoc.Name
    Else
        MsgBox "打开失败！"
    End If
End Sub

批量打开多个文档

Sub BatchOpenDocuments()
    Dim fileList As Variant
    fileList = Array("C:PartsPart1.CATPart", "C:PartsAssembly1.CATProduct")

    Dim i As Integer
    For i = 0 To UBound(fileList)
        CATIA.Documents.Open(fileList(i))
    Next
End Sub

高级参数扩展
虽然VBA中的Open方法仅接受文件路径参数，但通过 Windows API 可实现更复杂操作（如进度条、取消按钮）。
以下为CATIA原生支持的扩展逻辑：

以只读模式打开

' 通过设置文档的ReadOnly属性（需先打开）
Dim doc As Document
Set doc = CATIA.Documents.Open("C:ReadOnlyTemplate.CATPart")
doc.ReadOnly = True  ' 阻止意外修改

强制重新加载最新版本

' 先关闭已打开的文档再重新打开
Dim docName As String
docName = "DesignV2.CATProduct"

On Error Resume Next
CATIA.Documents.Item(docName).Close  ' 关闭已打开的实例
Set doc = CATIA.Documents.Open("C:Latest" & docName)  ' 重新加载
On Error GoTo 0

关键注意事项

路径有效性
路径必须存在且文件未被其他进程锁定，否则触发错误。建议添加验证：

If Dir(docPath) = "" Then
    MsgBox "文件不存在！"
    Exit Sub
End If

扩展名匹配
CATIA根据扩展名自动识别文档类型。若扩展名不匹配（如将.txt改为.CATPart），打开时将报错。
性能优化
打开大型装配时，可禁用图形刷新提升速度：

CATIA.DisplayFileAlerts = False  ' 关闭提示
CATIA.RefreshDisplay = False     ' 禁用界面刷新
Set doc = CATIA.Documents.Open(largeAssemblyPath)
CATIA.RefreshDisplay = True      ' 恢复刷新

错误处理

基础错误捕获

Sub SafeOpen()
    On Error Resume Next
    Dim doc As Document
    Set doc = CATIA.Documents.Open("InvalidPath.CATPart")

    If Err.Number <> 0 Then
        MsgBox "错误代码: " & Err.Number & vbCrLf & "描述: " & Err.Description
        Err.Clear
    End If
    On Error GoTo 0
End Sub

处理文件锁定冲突

Sub OpenWithRetry()
    Dim docPath As String
    docPath = "C:SharedCollaboration.CATProduct"

    On Error Resume Next
    Set doc = CATIA.Documents.Open(docPath)

    If Err.Number = -2147220475 Then  ' CATIA文件锁定错误码
        MsgBox "文件被其他用户锁定，请稍后重试！"
    End If
    On Error GoTo 0
End Sub

典型应用场景

自动化设计验证

Sub OpenAndValidate()
    Dim docPath As String
    docPath = "C:DesignsSuspension.CATProduct"

    Dim productDoc As ProductDocument
    Set productDoc = CATIA.Documents.Open(docPath)

    ' 执行质量检查
    If productDoc.Product.Weight > 100 Then
        MsgBox "重量超标！"
    End If
End Sub

批量转换文件格式

Sub BatchConvertToSTEP()
    Dim catiaFiles As Variant
    catiaFiles = Array("C:InputPart1.CATPart", "C:InputPart2.CATPart")

    Dim i As Integer
    For i = 0 To UBound(catiaFiles)
        Dim doc As Document
        Set doc = CATIA.Documents.Open(catiaFiles(i))
    
        ' 导出为STEP
        doc.ExportData "C:STEP_OutputPart" & i+1 & ".stp", "stp"
        doc.Close False  ' 关闭不保存
    Next
End Sub

扩展：与其他方法联用

打开后自动添加特征

Sub OpenAndModify()
    Dim doc As PartDocument
    Set doc = CATIA.Documents.Open("C:EditMe.CATPart")

    ' 添加一个孔特征
    Dim hole As Hole
    Set hole = doc.Part.Holes.Add()
    hole.Type = 1  ' 简单直孔
    hole.Diameter = 10
    hole.Depth = 20

    doc.Save  ' 直接保存修改
End Sub

与Add方法结合创建装配

Sub BuildAssembly()
    ' 创建新装配
    Dim assemblyDoc As ProductDocument
    Set assemblyDoc = CATIA.Documents.Add("Product")

    ' 打开并插入零件
    Dim partDoc As Document
    Set partDoc = CATIA.Documents.Open("C:ComponentsBolt.CATPart")

    assemblyDoc.Product.AddComponent(partDoc.Part)
End Sub

常见问题

如何判断文档是否已打开？

Function IsDocumentOpen(docName As String) As Boolean
    On Error Resume Next
    Dim doc As Document
    Set doc = CATIA.Documents.Item(docName)
    IsDocumentOpen = Not doc Is Nothing
End Function

相对路径支持？
CATIA VBA默认使用绝对路径，若需相对路径需自行解析：

Dim relativePath As String
relativePath = CATIA.ActiveDocument.Path & "SubAssembly.CATProduct"

如何打开隐藏文档？
CATIA无原生隐藏打开方式，但可通过最小化窗口模拟：

CATIA.Windows.Item(1).WindowState = catWindowStateMinimized  ' 最小化主窗口
Set doc = CATIA.Documents.Open("C:TempHiddenDoc.CATPart")

通过Open方法，可以实现CATIA文档的灵活加载和自动化操作。建议结合错误处理与性能优化技巧，构建健壮的工业级脚本。

四、Documents 集合方法列表

方法	语法	功能描述	参数说明	返回值	示例
Add	Documents.Add(DocType)	创建新文档（零件、装配、工程图等）	DocType: 文档类型字符串（如 “Part”）	Document 对象	Set partDoc = CATIA.Documents.Add(“Part”)
Open	Documents.Open(FilePath)	打开指定路径的文档	FilePath: 文件完整路径（含扩展名）	Document 对象	Set doc = CATIA.Documents.Open(“C:PartsEngine.CATPart”)
Item	Documents.Item(Index/Name)	通过索引或文档名称获取文档对象	Index: 整数或字符串（文档名称）	Document 对象	Set doc = CATIA.Documents.Item(1) 或 Item(“Part1.CATPart”)