Tekla 二次开发：BoltArray API 完全解析

Tekla Structures BoltArray API 完全解析

BoltArray 是用于创建矩形阵列螺栓组的核心类。通过定义螺栓在 X 方向和 Y 方向的间距列表，可在指定的起点与终点之间生成一个矩形排布的多螺栓组。该类继承自抽象类 BoltGroup，构造函数自动将形状类型设为 SHAPE_ARRAY，提供了完整的间距管理方法及重写的增删改查操作。

一、继承体系

BoltArray 是一个密封类（sealed），无法被其他类继承。它的继承链如下：

System.Object
  └── ModelObject
        └── BoltGroup (abstract)
              ├── BoltArray (sealed)    ← SHAPE_ARRAY（矩形阵列）
              ├── BoltCircle (sealed)   ← SHAPE_CIRCLE（圆形阵列）
              └── BoltXYList (sealed)   ← SHAPE_XY_LIST（XY 列表）

图1：BoltArray 继承层次图

BoltArray 直接继承了 BoltGroup 的所有属性（螺栓规格、构件连接、位置定义等）和操作能力，并重写了 Insert、Select、Modify、Delete 四个生命周期方法。BoltGroup 的三种预定义形状（SHAPE_ARRAY、SHAPE_CIRCLE、SHAPE_XY_LIST）分别对应三个密封子类，BoltArray 对应矩形阵列排布。

二、构造函数

BoltArray 仅提供一个无参构造函数。它在创建对象时自动完成以下初始化：

调用基类 BoltGroup() 构造函数，完成螺栓标准属性初始化：
  • BoltStandard 设置为 "7990"
  • BoltSize 设置为 20.0
  • ThreadInMaterial 设置为 THREAD_IN_MATERIAL_YES
  • CutLength 设置为 100.0，Tolerance 设置为 2.0
  • HoleType 设置为 HOLE_TYPE_SLOTTED
  • RotateSlots 设置为 ROTATE_SLOTS_PARALLEL
  • Bolt、Nut1、Washer3 设为 true
  • Position 的 Plane、Depth、Rotation 分别设为 MIDDLE、MIDDLE、FRONT

将 Shape 属性设为 BoltGroup.BoltShapeEnum.SHAPE_ARRAY
初始化内部 X 方向距离列表 _BoltDistX（ArrayList，最大 100 项）
初始化内部 Y 方向距离列表 _BoltDistY（ArrayList，最大 100 项）

BoltArray boltArray = new BoltArray();
// Shape 已自动设为 SHAPE_ARRAY
// 需要通过 AddBoltDistX / AddBoltDistY 添加螺栓间距

图2：构造函数初始化流程

三、属性

自身属性

BoltArray 自身未定义任何公开属性。X/Y 方向的螺栓间距通过方法管理（见第五章）。

继承自 BoltGroup 的属性

由于 BoltArray 是 BoltGroup 的子类，它完整继承了螺栓组的所有常用属性：

注意：以上仅为最常用的属性，BoltGroup 与 ModelObject 还提供更多细节属性，如 Hole1~Hole5（各零件孔开关）、UserDefinedProperty 等，可按需查阅 API 文档。

图5：BoltArray 常用操作流程

四、枚举类型

本类未定义任何公开枚举类型。BoltArray 使用了父类 BoltGroup 中定义的以下四个枚举：

注意：BoltShapeEnum 是 protected 枚举，包含 SHAPE_ARRAY、SHAPE_CIRCLE、SHAPE_XY_LIST，但仅用于内部分发，不对用户公开。

五、方法

自身方法

所有修改类方法（Select、Modify、Delete）在执行前都会检查 Identifier 的有效性，若标识符无效将抛出 ArgumentException。SetBoltDistX/SetBoltDistY 使用的是 ArrayList.Insert(Index, Dist)，即在指定位置"插入"一个元素（原位置及之后的元素后移），语义上更接近"插入"而非"替换"。如果需要在末尾添加，使用 AddBoltDistX/AddBoltDistY。

继承方法

六、完整代码示例

示例1：创建一个 3×2 矩形螺栓阵列

using Tekla.Structures.Model;
using Tekla.Structures.Geometry3d;

public void CreateBoltArray()
{
    // 1. 创建螺栓阵列对象
    BoltArray boltArray = new BoltArray();

    // 2. 定义螺栓间距：X 方向间距（沿起点→终点方向）
    //    螺栓将被放置在间距的"间隙"中：
    //    2 个间距 → 3 排螺栓
    boltArray.AddBoltDistX(100.0);  // 第 1→第 2 排间距 100mm
    boltArray.AddBoltDistX(120.0);  // 第 2→第 3 排间距 120mm

    // 3. 定义 Y 方向间距（垂直于起点→终点方向）
    //    1 个间距 → 2 列螺栓
    boltArray.AddBoltDistY(80.0);   // 间距 80mm

    // 4. 设置螺栓属性
    boltArray.BoltSize = 20.0;
    boltArray.BoltStandard = "7990";
    boltArray.BoltType = BoltGroup.BoltTypeEnum.BOLT_TYPE_SITE;
    boltArray.Tolerance = 2.0;
    boltArray.CutLength = 100.0;

    // 5. 设置连接零件
    boltArray.PartToBoltTo = mainBeam;
    boltArray.PartToBeBolted = secBeam;

    // 6. 定义螺栓组起点与终点
    boltArray.FirstPosition = new Point(0, 0, 1000);
    boltArray.SecondPosition = new Point(500, 0, 1000);

    // 7. 插入模型
    bool result = boltArray.Insert();
    if (result)
        Console.WriteLine("螺栓阵列创建成功，共 " + 
            (boltArray.GetBoltDistXCount() + 1) + "×" + 
            (boltArray.GetBoltDistYCount() + 1) + " 个螺栓");
}

示例2：读取已有螺栓阵列并修改间距

public void ModifyBoltArraySpacing(int boltGroupId)
{
    BoltArray boltArray = new BoltArray();
    boltArray.Identifier.ID = boltGroupId;

    if (!boltArray.Select())
    {
        Console.WriteLine("未找到指定的螺栓阵列");
        return;
    }

    int countX = boltArray.GetBoltDistXCount();
    int countY = boltArray.GetBoltDistYCount();
    Console.WriteLine($"X方向间距数：{countX}，Y方向间距数：{countY}");

    // 修改最后一个 X 方向间距
    if (countX > 0)
    {
        boltArray.RemoveBoltDistX(countX - 1);
        boltArray.AddBoltDistX(150.0);
    }

    if (boltArray.Modify())
        Console.WriteLine("间距修改成功");
}

示例3：删除螺栓阵列

public void DeleteBoltArray(int boltGroupId)
{
    BoltArray boltArray = new BoltArray();
    boltArray.Identifier.ID = boltGroupId;

    if (boltArray.Delete())
        Console.WriteLine("螺栓阵列已删除");
    else
        Console.WriteLine("删除失败，请检查 ID 是否存在");
}

示例4：遍历模型中的所有螺栓阵列

using Tekla.Structures.Model;

public void ListAllBoltArrays()
{
    Model model = new Model();
    ModelObjectEnumerator enumerator = model.GetModelObjectSelector()
        .GetAllObjectsWithType(ModelObject.ModelObjectEnum.BOLT_ARRAY);

    while (enumerator.MoveNext())
    {
        BoltArray ba = enumerator.Current as BoltArray;
        if (ba != null)
        {
            int rows = ba.GetBoltDistXCount() + 1;
            int cols = ba.GetBoltDistYCount() + 1;
            Console.WriteLine($"ID: {ba.Identifier.ID}, " +
                $"M{ba.BoltSize}, {rows}×{cols}={rows*cols}个螺栓, " +
                $"标准: {ba.BoltStandard}");
        }
    }
}

七、常见问题与注意事项

• 间距语义：AddBoltDistX 添加的是螺栓之间的"间距"（间隔数 = 螺栓数 − 1）。例如 X 方向添加 2 个间距 → 生成 3 排螺栓。开发时务必注意螺栓总数 = (间距数 + 1) × (间距数 + 1)。

• 最大间距数：X 和 Y 方向各最多支持 100 个间距（即最多 101 排/列）。超出会抛出 OverflowException。

• 插入的必要条件：PartToBoltTo、PartToBeBolted、Position、FirstPosition、SecondPosition 必须全部设置且不为 null，否则 Insert() 抛出 ArgumentException。

• 修改条件：Modify() 不要求 PartToBeBolted 非空（因为修改时可能只改间距），但仍要求 PartToBoltTo、Position 等有效。

• SetBoltDistX 的插入语义：SetBoltDistX(Index, Dist) 内部调用 ArrayList.Insert()，在指定位置"插入"一个元素（而非替换）。如果想修改已有间距，应先 RemoveBoltDistX 再 AddBoltDistX。

• PartToBoltTo 和 PartToBeBolted 的默认值：基类构造函数中两属性均被初始化为 new Beam()，只是占位，实际使用时必须替换为真实零件对象。

• 复合零件穿透：当螺栓需要穿透超过 2 个零件时，可通过 AddOtherPartToBolt() 添加附加零件（最多 98 个）。

• 间距与坐标的关系：X 方向沿 FirstPosition → SecondPosition 的方向，Y 方向垂直于该方向。螺栓在局部坐标系中按间距排布为矩形点阵。

图6：螺栓阵列间距排布示意图

八、总结

• BoltArray 是 Tekla Open API 中用于创建矩形阵列螺栓组的核心类，继承自 BoltGroup（抽象类），与 BoltCircle（圆形）和 BoltXYList（XY 列表）并列。

• 通过 AddBoltDistX / AddBoltDistY 方法定义 X 和 Y 方向的螺栓间距，间距数决定螺栓排布规模。

• 构造函数自动设定 Shape = SHAPE_ARRAY，并继承父类所有螺栓属性默认值。

• 自身提供 10 个间距管理方法（增删改查）+ 4 个重写的生命周期方法（Insert、Select、Modify、Delete）。

• 继承自 BoltGroup 的 30+ 属性和方法提供了完整的螺栓规格、连接关系、几何查询能力。

• 开发时应注意间距语义（间距数 ≠ 螺栓数）、插入前置条件、SetBoltDistX 的插入语义，以及 PartToBeBolted 在 Modify 时不强制的特性。

关注 Tekla 开发 · 扫码交流

公众号 / 小程序

微信个人号