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

Tekla Structures BoltXYList API 完全解析

BoltXYList 是用于创建 XY 坐标列表螺栓组的核心类。与 BoltArray（矩形阵列）和 BoltCircle（圆形阵列）不同，它通过 AddBoltDistX 和 AddBoltDistY 方法逐对添加螺栓的 X、Y 间距，实现对任意不规则排布的高自由度控制。该类继承自抽象类 BoltGroup，无自身公开属性，但提供了 6 个间距管理方法和完整的增删改查重写。

一、继承体系

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

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

[图] BoltXYList 继承层次图

BoltXYList 直接继承了 BoltGroup 的所有属性（螺栓规格、构件连接、位置定义等）和操作能力，并重写了 Insert、Select、Modify、Delete 四个生命周期方法。与 BoltArray（固定行/列间距）和 BoltCircle（圆形均匀分布）不同，BoltXYList 的螺栓位置通过 X/Y 间距列表逐对定义，灵活性最高。

二、构造函数

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

• 调用基类 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
• 将 Shape 属性设为 BoltGroup.BoltShapeEnum.SHAPE_XY_LIST
• 初始化 _BoltDistX 和 _BoltDistY 为空的 ArrayList

BoltXYList boltXYList = new BoltXYList();
// Shape 已自动设为 SHAPE_XY_LIST
// _BoltDistX 和 _BoltDistY 为空 ArrayList
// 需要通过 AddBoltDistX / AddBoltDistY 添加间距数据

[图] 构造函数初始化流程

三、属性

自身属性

BoltXYList 自身未定义任何公开属性。螺栓排布数据通过 _BoltDistX 和 _BoltDistY 两个私有 ArrayList 字段管理，外部需通过间距管理公开方法操作。

继承自 BoltGroup 的属性

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

BoltGroup 与 ModelObject 还提供 SlottedHoleX/Y、RotateSlots、Hole1~Hole5、BoltPositions 等更多属性，可按需查阅 API 文档。

[图] BoltXYList 核心属性与方法结构

四、枚举类型

BoltXYList 自身未定义任何枚举类型，使用了父类 BoltGroup 中定义的以下四个枚举：

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

五、方法

自身方法 — XY 间距管理

BoltXYList 提供了 6 个公开方法用于管理 XY 坐标列表，是实现任意不规则螺栓排布的核心机制：

注意：添加间距的顺序决定了螺栓的排列顺序。X 方向有 N 个间距 → N+1 列螺栓；Y 方向有 M 个间距 → M+1 行螺栓。总螺栓数 = (N+1) × (M+1)。间距值可为 0 或负数（表示反向偏移）。

自身方法 — 生命周期重写

所有修改类方法（Select、Modify、Delete）在执行前都会检查 Identifier 的有效性。Insert() 通过 CreateInstance()（私有方法）将 X/Y 间距列表写入 dotBoltShapeData_t 结构体，通过 COM 互操作调用底层 C++ API 完成创建。

继承方法

[图] BoltXYList 常用操作流程

六、完整代码示例

示例1：创建一个 4×3 的 XY 列表螺栓阵列

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

public void CreateBoltXYList()
{
    // 1. 创建 XY 列表螺栓组对象
    BoltXYList boltXYList = new BoltXYList();

    // 2. 添加 X 方向间距（3 个间距 → 4 列螺栓）
    boltXYList.AddBoltDistX(80.0);    // 第 1-2 列间距 80mm
    boltXYList.AddBoltDistX(80.0);    // 第 2-3 列间距 80mm
    boltXYList.AddBoltDistX(80.0);    // 第 3-4 列间距 80mm

    // 3. 添加 Y 方向间距（2 个间距 → 3 行螺栓）
    boltXYList.AddBoltDistY(60.0);    // 第 1-2 行间距 60mm
    boltXYList.AddBoltDistY(60.0);    // 第 2-3 行间距 60mm

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

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

    // 6. 定义螺栓组位置
    boltXYList.FirstPosition = new Point(500, 0, 1000);
    boltXYList.SecondPosition = new Point(500, 0, 1000);

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

示例2：使用不等间距创建任意排布

public void CreateIrregularBoltPattern()
{
    BoltXYList boltXYList = new BoltXYList();

    // 不等间距 X 列表
    boltXYList.AddBoltDistX(100.0);
    boltXYList.AddBoltDistX(150.0);
    boltXYList.AddBoltDistX(80.0);

    // 不等间距 Y 列表
    boltXYList.AddBoltDistY(50.0);
    boltXYList.AddBoltDistY(120.0);

    boltXYList.BoltSize = 20.0;
    boltXYList.BoltStandard = "7990";
    boltXYList.PartToBoltTo = mainBeam;
    boltXYList.PartToBeBolted = secBeam;
    boltXYList.FirstPosition = new Point(500, 0, 1000);
    boltXYList.SecondPosition = new Point(500, 0, 1000);

    bool result = boltXYList.Insert();

    // 遍历已添加的间距
    for (int xi = 0; xi < boltXYList.GetBoltDistXCount(); xi++)
    {
        Console.WriteLine("X[" + xi + "] = " +
            boltXYList.GetBoltDistX(xi) + "mm");
    }
    for (int yi = 0; yi < boltXYList.GetBoltDistYCount(); yi++)
    {
        Console.WriteLine("Y[" + yi + "] = " +
            boltXYList.GetBoltDistY(yi) + "mm");
    }
}

示例3：修改 XY 列表螺栓组

public void ModifyBoltXYList(int boltGroupId)
{
    BoltXYList boltXYList = new BoltXYList();
    boltXYList.Identifier.ID = boltGroupId;

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

    Console.WriteLine("X 间距数: " + boltXYList.GetBoltDistXCount() +
        ", Y 间距数: " + boltXYList.GetBoltDistYCount());

    // 修改螺栓规格
    boltXYList.BoltSize = 24.0;
    boltXYList.BoltStandard = "7990";

    if (boltXYList.Modify())
        Console.WriteLine("XY 列表螺栓组修改成功");
    else
        Console.WriteLine("修改失败");
}

示例4：遍历模型中的所有 XY 列表螺栓组

using Tekla.Structures.Model;

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

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

            // 打印所有间距
            string xDists = "";
            for (int i = 0; i < bl.GetBoltDistXCount(); i++)
                xDists += bl.GetBoltDistX(i) + " ";
            string yDists = "";
            for (int i = 0; i < bl.GetBoltDistYCount(); i++)
                yDists += bl.GetBoltDistY(i) + " ";
            Console.WriteLine("  X: [" + xDists.Trim() + "]");
            Console.WriteLine("  Y: [" + yDists.Trim() + "]");
        }
    }
}

七、常见问题与注意事项

插入的必要条件：Insert() 要求 PartToBoltTo、PartToBeBolted、Position、FirstPosition、SecondPosition 全部非空，且 PartToBeBolted.Identifier 有效。任一条件不满足均抛出 ArgumentException。

修改条件：Modify() 不要求 PartToBeBolted 非空，但仍要求 PartToBoltTo、Position、FirstPosition、SecondPosition 有效。

无自身公开属性：BoltXYList 是三个子类中唯一无自身公开属性的。X/Y 间距存储在私有 _BoltDistX 和 _BoltDistY 的 ArrayList 字段中，只能通过 6 个公开方法操作。

间距列表上限：每个方向的间距列表上限为 100 个。超出上限调用 AddBoltDistX 或 AddBoltDistY 将抛出 OverflowException。

螺栓总数计算：排布网格为 (N+1) × (M+1) 的矩形，其中 N = GetBoltDistXCount()（X 间距数），M = GetBoltDistYCount()（Y 间距数）。例如 3 个 X 间距 + 2 个 Y 间距 → 4 列 × 3 行 = 12 个螺栓。

与 BoltArray 的区别：BoltArray 为每行/列提供固定的 AddBoltDistX/AddBoltDistY，适合规则矩形排布；BoltXYList 的间距列表是全局的，所有列共用一个 X 间距列表、所有行共用一个 Y 间距列表，但每列的 X 间距和每行的 Y 间距都可独立设置，适合不等间距排布。

间距值可为负数：间距值支持负数，表示螺栓向相反方向偏移。但请注意，总螺栓数始终为 (N+1)×(M+1)，不受间距值正负影响。

Select() 后间距数据恢复：调用 Select() 后，现有间距列表会被清空（_BoltDistX.Clear() 和 _BoltDistY.Clear()），然后从模型读取的数据逐对重新填充。

[图] XY 列表螺栓阵列布局示意图

八、总结

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

• 通过 AddBoltDistX/AddBoltDistY 逐对添加间距，支持任意不等间距的不规则排布，灵活性最高。

• 自身无公开属性，X/Y 间距数据存储在私有 ArrayList 中，提供 6 个间距管理方法（添加、计数、获取）。

• 构造函数自动设定 Shape = SHAPE_XY_LIST，并初始化空的 _BoltDistX 和 _BoltDistY 列表。

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

• 与 BoltArray 的核心差异：X/Y 间距列表为全局共享（所有列/行），而 BoltArray 为每行独立设置间距。

• 开发时应注意间距列表上限（100 个）、Select() 后列表会自动重建、以及 Insert 与 Modify 的前置条件差异。

关注 Tekla 开发 · 扫码交流

公众号 / 小程序

微信个人号