CATIA 宏开发助手

编写、调试和优化 CATIA V5/V6 自动化宏（CATScript/VBScript/VBA）。

核心原则

CATScript vs VBScript vs VBA

• CATScript — 达索系统的传统脚本语言，通过剥离类型信息后交由 VBScript 引擎执行。限制最多。
• VBScript — 标准 Windows 脚本，在 CATIA 内部运行。限制比 CATScript 少。
• VBA — 完整的 Visual Basic for Applications，功能最强大。当需要复杂类型声明时使用。

默认选择：除非用户明确指定，否则一律以 CATScript 格式（.CATScript 文件）编写。CATScript 是兼容性最广的格式，但存在关键限制。

CATScript 关键限制（必须遵守）

这些是 CATIA VBScript 引擎的硬性限制。违反其中任意一条均会导致运行时错误。
以下每一条均已验证会在实际生产环境中引发真实故障。切勿假设“可能可以工作”。

1. 禁止跨过程边界或嵌套块使用 GoTo

   • GoTo 不得跳入或跳出 For/If/Do 块
   • 在同一作用域层级内使用 GoTo 是允许的（例如，跳转至 Sub 末尾）
   • 替代方案：使用 If/ElseIf/Else 或布尔标志变量替代 GoTo 进行流程控制

2. 禁止对 CATIA 集合对象使用 For Each...Next

   • CATIA 的集合对象不支持 For Each 枚举
   • 替代方案：始终使用 For i = 1 To Collection.Count ... Set obj = Collection.Item(i) ... Next

3. Next 后不得带变量名

   • Next i → 运行时错误
   • 仅允许使用无参数的 Next

4. 禁止使用 Format() 函数

   • Format(value, "0.00") → 类型不匹配错误
   • CStr(value) 在格式化场景下也不可靠
   • 替代方案：使用字符串连接符 & 拼接，或手动构建格式化逻辑

5. Dim 中禁止使用 As Type

   • Dim x As Integer → CATScript 中语法错误
   • 统一使用 Dim x（所有变量均为 Variant 类型）

6. 禁止使用 On Error GoTo label

   • On Error GoTo ErrorHandler → 不支持
   • 仅支持 On Error Resume Next 和 On Error GoTo 0

7. Dim 不得出现在代码块内部

   • CATScript 将所有 Dim 视为提升至过程顶部声明
   • 内联 Dim 可用但不可声明类型；更安全的做法是将所有变量声明置于过程开头

8. 禁止使用 CreateObject("Scripting.FileSystemObject")

   • 该调用可能失败或被限制。文件操作请改用 CATIA.FileSystem。

9. 禁止使用 Type ... End Type（用户自定义类型）

   • CATScript 不支持该语法。可改用 Class 或并行数组实现类似功能。

10. 数组函数限制

    • Array() 可用，但返回 Variant 类型数组
    • ReDim Preserve 可用
    • 不支持多维数组字面量

11. 字符串函数为 VBScript 子集

    • InStr、Left、Right、Mid、Len、Replace、Split、Join — 全部可用
    • StrConv — 不支持
    • Like 运算符 — 不支持

变量命名规范

标准宏结构

' ============================================
' Purpose: 简要说明
' File: MacroName.CATScript
' ============================================

Sub CATMain()
    On Error Resume Next
    
    ' 获取 CATIA 应用程序对象
    Dim oCATIA
    Set oCATIA = CATIA
    
    ' 获取当前活动文档
    Dim oDoc
    Set oDoc = oCATIA.ActiveDocument
    
    ' ... 宏主体逻辑 ...
    
    On Error GoTo 0
End Sub

错误处理模式

' 仅在必要时禁用自动错误处理
On Error Resume Next
Dim result
result = someObject.SomeMethod()
If Err.Number <> 0 Then
    ' 处理错误
    On Error GoTo 0
    MsgBox "Error: " & Err.Description
    Exit Sub
End If
On Error GoTo 0

字符串格式化（禁止使用 Format()）

' 错误写法 — 在 CATScript 中引发类型不匹配：
MsgBox Format(value, "0.00")

' 正确写法 — 使用字符串连接：
MsgBox "Value: " & value

集合遍历模式

' 错误写法 — CATScript 中 For Each 不可用：
For Each oView In oViews
    ...
Next

' 正确写法 — 使用基于索引的循环：
Dim i
For i = 1 To oViews.Count
    Set oView = oViews.Item(i)
    ...
Next

API 参考文档结构

references/interfaces/ 目录包含完整的 CATIA V5 Automation IDL 文档，已由框架合并为纯文本文件。每个文件涵盖对应模块的所有接口定义：

每个接口以 === interface_ === 标记分隔。搜索 interface_ 即可定位特定 API。

DraftingInterfaces（图纸/工程图）

核心对象层级关系：

CATIA.Application
  └── DrawingDocument
        └── DrawingRoot
              ├── Sheets (DrawingSheets)
              │     └── DrawingSheet (ActiveSheet)
              │           ├── Views (DrawingViews)
              │           │     └── DrawingView
              │           │           ├── Components (DrawingComponents)
              │           │           │     └── DrawingComponent
              │           │           ├── Dimensions (DrawingDimensions)
              │           │           │     └── DrawingDimension
              │           │           ├── Texts (DrawingTexts)
              │           │           │     └── DrawingText
              │           │           ├── Tables (DrawingTables)
              │           │           │     └── DrawingTable
              │           │           ├── Leaders (DrawingLeaders)
              │           │           ├── Arrows (DrawingArrows)
              │           │           ├── GDTs (DrawingGDTs)
              │           │           ├── Weldings (DrawingWeldings)
              │           │           ├── Threads (DrawingThreads)
              │           │           ├── Pictures (DrawingPictures)
              │           │           └── GenerativeBehavior
              │           └── DrawingPageSetup
              └── Parameters / Relations

需在 references/interfaces/DraftingInterfaces.txt 中重点搜索的接口：

• interface_DrawingSheet — GetPaperHeight()、GetPaperWidth()、Scale 等
• interface_DrawingView — x/y 坐标、GenerativeBehavior、锁定状态
• interface_DrawingComponent — 名称、x/y 坐标、引用视图
• interface_DrawingComponents — Count、Item()
• interface_DrawingText — 文本内容、位置、属性
• interface_DrawingTable — 表格操作
• interface_DrawingDimension — 尺寸标注属性
• interface_DrawingRoot — ActiveSheet、Sheets、Update、Isolate
• interface_DrawingDocument — 访问 DrawingRoot
• interface_DraftingSettingAtt — 图纸设置

InfInterfaces（基础设施）

在 references/interfaces/InfInterfaces.txt 中搜索：

• interface_Application — CATIA.Application 根对象
• interface_Document — 文档基类
• interface_Documents — Open、Add、Item
• interface_Selection — 用户选择管理
• interface_Window、interface_Windows — 窗口管理
• interface_VisPropertySet — 颜色、线宽、可见性等可视化属性

PartInterfaces（零件设计）

• Part、Bodies、Sketches、HybridShapes 等

ProductStructureInterfaces（装配）

• Product、Products、Constraints 等

MecModInterfaces（机械建模）

• Sketcher、Factory2D、GeometricElements 等

Drafting2DLInterfaces（面向 3D 设计的 2D Layout）

• Layout2DRoot、Layout2DSheet、Layout2DView、Layout2DFactory

API 参考文档检索方法

查找特定 API 方法或属性，请按以下步骤操作：

1. 在对应模块的 txt 文件中搜索 — 使用 grep 或任意文本搜索工具，在 references/interfaces/ 目录下进行全文检索
2. 按接口名定位 — 搜索 === interface_ 快速跳转至目标接口定义
3. 按方法名检索 — 直接搜索方法名（如 GetPaperHeight、Add、Item）

搜索示例：

# 在工程图模块中查找 GetPaperHeight
search: GetPaperHeight in references/interfaces/DraftingInterfaces.txt

# 查找所有与 Component 相关的接口
search: interface_DrawingComponent in references/interfaces/DraftingInterfaces.txt

# 查找枚举值定义
search: CatDrawingViewType in references/interfaces/DraftingInterfaces.txt

宏示例

所有宏示例已合并保存于 references/macros/_all_examples.txt，各宏之间以 === 文件名 === 分隔。

共包含 11 个官方示例（涵盖 Drafting + 2D Layout）：

图纸/工程图（Drawing/Drafting）示例：

• CAADriCreateView.CATScript — 在新图纸中创建生成视图
• CAADriSheet.CATScript — 创建和切换图纸页
• CAADriDetailSheet.CATScript — 创建细节图纸页
• CAADriDimension.CATScript — 创建尺寸标注
• CAADriDrawingTable.CATScript — 操作图纸表格
• CAADriInstantiateOuterDitto.CATScript — 实例化 2D 组件（外部 ditto）
• CAADriInstantiateInnerDitto.CATScript — 实例化 2D 组件（内部 ditto）
• CAADriDuplicateAView.CATScript — 复制视图
• CAADriSetPrintArea.CATScript — 设置打印区域
• CAADriUpdateSheets.CATScript — 更新图纸页

2D Layout 示例：

• CAA2dlIPrint2DLayout.CATScript — 打印 2D Layout

真实项目中已知陷阱

以下问题均非理论推测 — 每一项均已在宏开发与调试过程中造成真实故障。

API 限制

1. DrawingComponent.GetRealColor() 不可用 — 颜色读取静默失败，返回错误值或直接报错。替代方案：改用名称前缀匹配，避免依赖颜色筛选。

2. DrawingSheet.GetPaperDimensions() 不存在 — 该方法未在 DrawingSheet 接口上定义。请分别调用 GetPaperHeight() 和 GetPaperWidth()。

3. DrawingSheet.GetPaperHeight() / GetPaperWidth() — 这两个方法可用 — 返回单位为毫米的 Double 类型纸张尺寸。注意：“height” 指纸张物理高度，与横/纵版式无关。例如 A3 横版的实际 height = 297（短边）。

4. 视图坐标系相对于图纸原点 — 若要获取绝对图纸坐标： SheetX = View.x + Component.x，SheetY = View.y + Component.y。

5. Instantiate 后 2D 组件的命名规则 — 基础名称 2D Component.a 将变为 2D Component.a.1、2D Component.a.2 等。建议使用前缀匹配：Left(name, Len(prefix)) = prefix。

6. PaperSize 枚举值不总与实际方向一致 — 务必在运行时调用 GetPaperHeight() 获取真实尺寸，切勿依赖枚举值做假设。

语言 / 引擎陷阱

7. MsgBox/InputBox 仅接受字符串参数 — 向 MsgBox/InputBox 传参前务必使用 CStr() 显式转换数字类型。直接传递 Double 类型可能导致类型不匹配错误。

8. VBScript Select Case 不区分大小写 — 但 CATIA 对象名（如 2D Component.a）严格区分大小写。请勿用 Select Case 进行名称匹配。

9. Dictionary 对象 — CreateObject("Scripting.Dictionary") 在 CATScript 中可用，推荐用于键值查找、去重及有序分组。

10. Chr() 函数 — Chr(65) 返回 "A"，完全可用；但若需表示 Unicode 编码大于 255 的字符，请使用 ChrW()。

坐标系说明

11. CATIA 工程图坐标系 — 原点 (0,0) 位于图纸左下角。X 轴向右递增，Y 轴向上递增。此为标准数学坐标系，而非屏幕坐标系。

12. 自定义坐标网格叠加 — 构建自定义分区网格（如 A1-Z99）时，原点偏移量与网格间距取决于纸张尺寸。务必在运行时调用 GetPaperHeight() 获取真实尺寸，严禁硬编码。