【CATIA的二次开发20】根对象Application常用属性(ActiveDocument属性Caption属性Name属性)

在CATIA VBA开发中，对根对象Application涉及相关属性进行详细总结，并且用不同形式展示出来。
供大家后续开发全面了解Application对象的属性，以便在开发过程中快速查找和使用：

图片[1] - 【CATIA的二次开发20】根对象Application常用属性(ActiveDocument属性Caption属性Name属性) - 宋马
# 一、Application常用属性

属性名称	功能描述	返回值类型	使用场景	注意事项	示例代码
ActiveDocument	获取当前活动（聚焦）的文档对象	Document对象（PartDocument, ProductDocument 等派生类）	• 操作当前编辑的文档 • 获取文档中的零件/装配体	• 无文档时返回 Nothing• 需判空处理：If Not CATIA.ActiveDocument Is Nothing Then • 文档切换时自动更新	Set part = CATIA.ActiveDocument.Part part.Update()
Caption	获取或设置主窗口标题栏文本	String	• 显示脚本进度 • 环境标识（测试/生产） • 多实例区分	• 最大长度 ~120字符 • 文档切换会重置标题 • 关闭时恢复默认值	CATIA.Caption = “处理中：” & counter & “/” & total
Name	获取CATIA应用程序名称标识（只读）	String	• 版本兼容检查 • 日志记录 • 初始化环境判断	• CATIA V5 返回 “CATIA” • 3DEXPERIENCE 返回 “3DEXPERIENCE” • 不包含版本号（需用 SystemConfiguration.Version）	If CATIA.Name = “CATIA” Then Call RunV5Feature End If
StatusBar	设置状态栏提示文本	String	• 操作进度反馈 • 调试信息显示 • 用户指引	• 超长文本自动截断 • 鼠标悬停对象会覆盖文本 • 脚本结束建议清空：CATIA.StatusBar = “”	CATIA.StatusBar = “保存中…请勿操作” DoEvents
RefreshDisplay	控制界面刷新开关（性能优化核心属性）	Boolean	• 批量参数修改 • 大型装配操作 • 循环生成几何	• 必须成对使用：操作后恢复 True • 需错误处理确保恢复 • 可能需手动调用 Viewer.Update 刷新视图	CATIA.RefreshDisplay = False '批量操作… CATIA.RefreshDisplay = True
Application	CATIA VBA 根对象（顶级入口点）	Application 对象	• 脚本启动入口 • 访问子对象（Documents, SystemService） • 系统级操作	• 无 Parent 属性（顶级对象） • 显式释放对象避免内存泄漏 • 不同版本对象模型可能差异	Set docs = CATIA.Documents Set sysCfg = CATIA.SystemConfiguration

特性	ActiveDocument	RefreshDisplay	StatusBar
核心作用	文档操作入口	性能优化开关	用户交互反馈
是否可写	只读	读写	读写
性能影响	低	极高（禁用后提速5-10倍）	低
错误风险	高（需判空）	高（未恢复导致界面假死）	低
跨平台差异	3DEXPERIENCE 中行为微调	无差异	3DEXPERIENCE 集成通知中心

二、Application常用属性

1、ActiveDocument属性

在CATIA VBA开发中，Application对象的ActiveDocument属性是用于获取当前活动窗口中的文档对象（Document类型）的关键接口。
以下是关于该属性的详细说明及使用场景：

属性功能
返回当前活动窗口显示的文档对象。若没有打开的文档，则返回Nothing。
属性语法
CATIA.ActiveDocument，其中CATIA是Application对象。
属性示例

Dim doc As Document
Set doc = CATIA.ActiveDocument
If Not doc Is Nothing Then
    MsgBox "当前文档名称：" & doc.Name
Else
    MsgBox "无活动文档"
End If

典型应用场景

场景一：操作当前文档中的元素
通过ActiveDocument可以访问文档中的选择集（Selection），进而操作用户选中的对象。
示例：修改选中对象的属性

Dim sel As Selection
Set sel = CATIA.ActiveDocument.Selection
sel.Item(1).Value.ATTRIBUTE = "新值"

场景二：访问用户定义的属性（User-Defined Properties）
用户自定义属性通常存储在UserRefProperties集合中，需通过层级路径访问。
示例：读取选中对象的用户属性

Dim selectedObj As Product
Set selectedObj = CATIA.ActiveDocument.Selection.Item(1).LeafProduct.ReferenceProduct
MsgBox selectedObj.UserRefProperties.Item("DESIGNER").ValueAsString

注意：若属性路径包含层级（如Product1PropertiesMINE），需完整指定路径。

注意事项与常见问题

避免空引用
在调用ActiveDocument前需检查文档是否打开：

If CATIA.Documents.Count = 0 Then
    MsgBox "请先打开文档"
    Exit Sub
End If

层级结构的影响

若对象是实例（Instance），需通过LeafProduct或ReferenceProduct获取其引用对象，再访问属性。
错误示例

' 直接访问可能失败，因为Selection可能指向实例
MsgBox CATIA.ActiveDocument.Selection.Item(1).UserRefProperties.Item("属性名").Value

修正后的代码：

MsgBox CATIA.ActiveDocument.Selection.Item(1).LeafProduct.ReferenceProduct.UserRefProperties.Item(1).ValueAsString

属性路径的命名规范
用户属性的路径需严格匹配其定义时的层级结构（如”Product1PropertiesMINE”）

完整代码示例
以下代码演示如何通过ActiveDocument获取用户选择的第一个对象，并读取其用户属性：

Sub ReadUserProperty()
    On Error Resume Next
    Dim sel As Selection
    Set sel = CATIA.ActiveDocument.Selection

    If sel.Count = 0 Then
        MsgBox "未选择任何对象"
        Exit Sub
    End If

    Dim refProduct As Product
    Set refProduct = sel.Item(1).LeafProduct.ReferenceProduct

    Dim propValue As String
    propValue = refProduct.UserRefProperties.Item("DESIGNER").ValueAsString
    MsgBox "设计者属性值：" & propValue
End Sub

2、Caption属性

在CATIA VBA开发中，Application对象的Caption属性用于获取或设置CATIA主窗口的标题栏文本。该属性允许开发者动态修改CATIA界面中显示的标题内容，
常用于自定义界面提示或集成调试场景。以下是详细说明及使用指南：

属性功能

读取标题：获取当前CATIA主窗口标题栏显示的文本（默认包含软件名称、版本及文档信息）。
修改标题：自定义标题内容（如添加环境标识、项目名称或调试信息）。

属性语法

' 获取当前标题
Dim currentTitle As String
currentTitle = CATIA.Caption

' 设置新标题
CATIA.Caption = "自定义标题 - 项目ABC"

典型应用场景

场景一：动态标识运行环境
在开发或测试环境中，通过标题区分不同配置：

Sub SetEnvironmentTag()
    CATIA.Caption = "[测试环境] CATIA V5 - " & CATIA.SystemConfiguration.Version
End Sub

场景二：调试信息展示
实时显示脚本运行状态或关键变量：

Sub ShowProgress(currentStep As Integer, totalSteps As Integer)
    CATIA.Caption = "处理中: " & currentStep & "/" & totalSteps & " 步骤"
End Sub

场景三：多实例窗口区分
当同时运行多个CATIA实例时，自定义标题便于用户识别：

CATIA.Caption = "CATIA - 模具设计模块 (实例1)"

注意事项

标题重置行为

文档操作影响：当切换活动文档（ActiveDocument）时，CATIA可能自动恢复默认标题格式（如包含文档名称）。
解决方案：通过事件监听（如DocumentActivate）重新设置标题：

Sub OnDocumentActivate()
    CATIA.Caption = "自定义前缀 - " & CATIA.ActiveDocument.Name
End Sub

兼容性与权限

版本差异：CATIA V5与3DEXPERIENCE平台对标题修改的支持可能不同（后者受沙盒安全限制）。
管理员权限：某些企业环境中，修改系统窗口标题可能需要额外权限。

副作用规避

用户混淆风险：避免过度修改标题导致用户操作困惑。
恢复默认标题：

Sub ResetDefaultCaption()
    CATIA.Caption = ""  ' 赋空值触发自动恢复
End Sub

完整代码示例
以下脚本实现标题动态计时器功能：

Dim startTime As Double
Sub StartTitleTimer()
    startTime = Timer
    Application.OnTime Now + TimeValue("00:00:01"), "UpdateTitleTimer"
End Sub

Sub UpdateTitleTimer()
    Dim elapsed As Integer
    elapsed = CInt(Timer - startTime)
    CATIA.Caption = "运行时间: " & elapsed & "秒"
    Application.OnTime Now + TimeValue("00:00:01"), "UpdateTitleTimer"
End Sub

Sub StopTitleTimer()
    CATIA.Caption = ""  ' 清除自定义标题
End Sub

替代方案与扩展

状态栏信息：若仅需临时提示，可通过状态栏显示信息（避免干扰标题）：

CATIA.StatusBar = "正在保存文档..."

窗口句柄控制：结合Windows API修改窗口属性（如图标、尺寸）：

Private Declare PtrSafe Function SetWindowText Lib "user32" Alias "SetWindowTextA" _
    (ByVal hWnd As LongPtr, ByVal lpString As String) As Long

Sub SetTitleViaAPI()
    SetWindowText CATIA.HWND, "API修改的标题"
End Sub

Windows API（SetWindowText）语法见资源文件

3、Name属性

在CATIA VBA开发中，Application对象的Name属性是用于获取当前CATIA应用程序实例的名称标识符的核心属性。以下是关于该属性的详细说明及典型应用场景：

属性功能
返回当前运行的CATIA应用程序的名称，例如 “CATIA” 或 “3DEXPERIENCE”（取决于版本）。
属性语法

Dim appName As String
appName = CATIA.Name

返回值：固定字符串，不因用户配置或文档内容改变。

典型应用场景

场景一：环境检测与版本适配
判断当前运行的CATIA类型，以调用版本特定的功能：

Sub CheckCATIAEnvironment()
    If CATIA.Name = "CATIA" Then
        MsgBox "当前运行环境：CATIA V5"
    ElseIf CATIA.Name = "3DEXPERIENCE" Then
        MsgBox "当前运行环境：3DEXPERIENCE平台"
    End If
End Sub

场景二：日志记录与调试
在自动化脚本中记录操作环境：

Sub LogOperation()
    Dim logText As String
    logText = "操作时间：" & Now() & vbCrLf & _
              "应用程序：" & CATIA.Name & vbCrLf & _
              "版本号：" & CATIA.SystemConfiguration.Version
    SaveToFile logText, "C:Logsoperation.log"  ' 自定义保存函数
End Sub

场景三：跨平台兼容性处理
针对不同平台（V5/3DEXPERIENCE）调整代码逻辑：

Sub LoadAddon()
    If CATIA.Name = "CATIA" Then
        LoadLibrary "V5_Plugin.dll"  ' 加载CATIA V5专用插件
    Else
        LoadLibrary "3DX_Plugin.dll" ' 加载3DEXPERIENCE插件
    End If
End Sub

注意事项

返回值固定性：

该属性仅返回应用程序名称，不包含版本号。需结合SystemConfiguration.Version获取详细版本信息。
例如：CATIA.Name返回”CATIA”，而CATIA.SystemConfiguration.Version返回”V5-6R2023″。

与Caption属性的区别：

Name：静态标识符，始终返回应用程序名称。
Caption：动态窗口标题，可通过代码修改（如CATIA.Caption = “自定义标题”）。

版本兼容性：

CATIA V5及3DEXPERIENCE平台均支持此属性。
部分旧版CATIA V5（如R20之前）可能返回空字符串，需测试验证。

完整代码示例
以下脚本演示如何根据应用程序名称初始化配置：

Sub InitializeConfiguration()
    On Error Resume Next
    
    Dim configPath As String
    
    Select Case CATIA.Name
        Case "CATIA"
            configPath = "C:ConfigV5_Settings.xml"
        Case "3DEXPERIENCE"
            configPath = "C:Config3DX_Settings.xml"
        Case Else
            MsgBox "未知的CATIA环境！"
            Exit Sub
    End Select
    
    If Dir(configPath) <> "" Then
        LoadConfiguration configPath  ' 自定义加载函数
        MsgBox "配置已加载！"
    Else
        MsgBox "配置文件不存在：" & configPath
    End If
End Sub

三、总结

ActiveDocument属性、Caption属性和Name属性应用不同场景。

ActiveDocument属性

场景类型	具体应用	示例代码	最佳实践
参数化设计	修改当前零件参数	vba Set param = CATIA.ActiveDocument.Part.Parameters.Item(“Length”) param.Value = 100 part.Update 配合 RefreshDisplay=False	提升批量修改性能
装配管理	获取当前装配中的组件列表	vba Set product = CATIA.ActiveDocument.Product For i=1 To product.Products.Count Debug.Print product.Products.Item(i).Name Next	使用 Product.Products 集合代替递归遍历
工程图操作	导出当前图纸为PDF	vba CATIA.ActiveDocument.ExportData “C:drawing.pdf”, “pdf”	检查文档类型： If TypeName(CATIA.ActiveDocument) = “DrawingDocument” Then
特征编辑	修改当前零件的拉伸特征	vba Set pad = CATIA.ActiveDocument.Part.MainBody.Shapes.Item(1) pad.FirstLimit.Dimension.Value = 50	通过 Shape.Name 精确查找特征避免索引错误
跨文档操作	复制当前文档几何到新文档	vba Set srcDoc = CATIA.ActiveDocument Set newDoc = CATIA.Documents.Add(“Part”) srcDoc.Part.Copy newDoc.Part.Paste	使用 Copy/Paste 代替API创建几何提升效率

Caption 属性

场景类型	具体应用	示例代码	最佳实践
进度显示	显示批量处理进度	vba For i=1 To 100 CATIA.Caption = “处理中: ” & i & “%” ProcessItem i Next 配合 DoEvents	确保标题刷新
环境标识	区分测试/生产环境	vba If IsTestEnvironment Then CATIA.Caption = “[测试模式] – CATIA” End If	在文档打开事件中重置标题
调试追踪	显示当前操作步骤	vba CATIA.Caption = “步骤2/5: 创建草图” CreateSketch	关键操作节点必设标题提示
多实例区分	标识不同CATIA实例	vba CATIA.Caption = “CATIA – 模具设计 (实例1)” 结合 App.Instance 实现唯一标识
用户引导	显示快捷键提示 “`	vba CATIA.Caption = “按F5运行宏	按ESC取消”“` 超长文本分页显示

Name 属性

场景类型	具体应用	示例代码	最佳实践
版本适配	根据平台加载不同功能	vba Select Case CATIA.Name Case “CATIA”: LoadV5Addon Case “3DEXPERIENCE”: Load3DXAddon End Select	使用 SystemConfiguration.Version 补充详细版本信息
日志记录	记录操作环境	vba Log.Write “操作环境: ” & CATIA.Name & ” ” & CATIA.SystemConfiguration.Version	关键操作必记环境信息
许可验证	检查是否正版环境	vba If CATIA.Name = “CATIA” And InStr(LicenseInfo, “Educational”) = 0 Then ’ 商业版操作 End If	结合 SystemConfiguration.LicenseInfo 增强验证
插件初始化	动态加载平台专用模块	vba Set module = If(CATIA.Name=“CATIA”, V5Module, 3DXModule)	使用工厂模式封装平台差异
错误报告	生成系统环境报告	vba bugReport = “Platform: ” & CATIA.Name & vbCrLf & “Version: ” & CATIA.SystemConfiguration.Version	自动附加到错误日志

属性组合应用场景
场景：自动化报告生成器

Sub GenerateReport()
    ' 设置环境标识
    CATIA.Caption = "报告生成中 - " & Format(Now, "yyyy-mm-dd hh:mm")
    
    ' 检查环境
    If CATIA.Name <> "CATIA" Then
        MsgBox "仅支持CATIA V5环境！", vbCritical
        Exit Sub
    End If
    
    ' 获取活动文档
    If CATIA.ActiveDocument Is Nothing Then
        MsgBox "请打开文档！", vbExclamation
        Exit Sub
    End If
    
    ' 优化性能
    CATIA.RefreshDisplay = False
    CATIA.StatusBar = "开始生成报告..."
    
    ' 核心操作
    Dim docName As String
    docName = CATIA.ActiveDocument.Name
    
    ' 生成报告内容
    Dim report As String
    report = "===== 设计报告 =====" & vbCrLf & _
             "文档: " & docName & vbCrLf & _
             "环境: " & CATIA.Name & " " & CATIA.SystemConfiguration.Version & vbCrLf & _
             "生成时间: " & Now & vbCrLf & vbCrLf & _
             "参数清单:" & vbCrLf
             
    ' 收集参数
    Dim param As Parameter
    For Each param In CATIA.ActiveDocument.Part.Parameters
        report = report & param.Name & ": " & param.Value & vbCrLf
    Next
    
    ' 保存报告
    SaveToFile report, "C:Reports" & docName & ".txt"
    
    ' 恢复状态
    CATIA.Caption = "CATIA"
    CATIA.StatusBar = "报告生成完成！"
    CATIA.RefreshDisplay = True
    
    ' 打开报告
    Shell "notepad.exe C:Reports" & docName & ".txt", vbNormalFocus
End Sub

跨平台差异处理方案

场景	CATIA V5 方案	3DEXPERIENCE 方案	兼容处理技巧
获取活动文档	Set doc = CATIA.ActiveDocument	Set editor = CATIA.ActiveEditor	If CATIA.Name=“CATIA” Then…Else…
标题显示范围	主窗口标题栏	选项卡标题 + 通知中心	同时设置 Caption 和 StatusBar 双保险
环境信息获取	SystemConfiguration.Version 返回本地版本	SystemConfiguration.Version 返回平台版本	在日志中记录 CATIA.Name 区分来源
文档类型判断	TypeName(doc) = “PartDocument”	doc.Type = “CATPart”	优先使用 TypeName 函数
进度显示	Caption 直接显示在主标题栏	需结合状态栏和通知中心	使用 StatusBar 作为跨平台通用方案

最佳实践

ActiveDocument 三重保护：

' 1. 检查文档集合
If CATIA.Documents.Count = 0 Then Exit Sub

' 2. 验证活动文档
If CATIA.ActiveDocument Is Nothing Then
    CATIA.ActiveDocument = CATIA.Documents.Item(1)
End If

' 3. 类型安全访问
If TypeOf CATIA.ActiveDocument Is PartDocument Then
    ' 安全操作
End If

Caption 动态管理：

Dim originalCaption As String
originalCaption = CATIA.Caption  ' 备份原始标题

' 操作期间修改标题
CATIA.Caption = "处理中..."

' 操作完成后恢复
CATIA.Caption = originalCaption

Name 驱动决策树：