前言

在 MxCAD 平台中，对象捕捉的规则与底层逻辑与 AutoCAD 保持了高度一致，它允许光标在绘图时自动吸附到现有几何对象的关键特征点上，如端点、中点、圆心等，从而彻底消除手动定位带来的误差。而控制这一功能的正是系统变量 OSMODE。下面我们逐步讲解对象捕捉的运行逻辑。

一、OSMODE：对象捕捉的“数字基因”

用户通过界面勾选或快捷键开启的捕捉模式，本质上都是在修改 OSMODE 这个系统变量的值。OSMODE 并不是一个简单的开关，而是一个由多个捕捉状态组合而成的复合数值。每一个基础捕捉模式（如端点、中点、交点）都被分配了一个特定的数值，当用户同时启用多种捕捉时，系统会将这些数值进行叠加运算，最终生成一个唯一的 OSMODE 总值。这意味着，图纸上当前生效的所有捕捉规则，都被精确地编码在了这一个数字之中。

在 MxCAD 的底层代码中，这些捕捉模式被统一定义，且与 AutoCAD 的规则保持完全一致。具体包含以下端点值：

// 对象捕捉模式规则枚举
enum SysVarLongSketchSettingsOsMode {
 /** 端点捕捉 */
 End = 1,
 /** 中点捕捉 */
 Mid = 2,
 /** 圆心点捕捉 */
 Cen = 4,
 /** 节点捕捉 */
 Node = 8,
 /** 象限点捕捉 */
 Quad = 16,
 /** 交点捕捉 */
 Int = 32,
 /** 插入点捕捉 */
 Ins = 64,
 /** 垂足点捕捉 */
 Perp = 128,
 /** 切点捕捉 */
 Tan = 256,
 /** 最近点捕捉 */
 Near = 512,
 /**外观交点捕捉*/
 App = 2048,
 /**延伸点捕捉*/
 Ext = 4096,
 /** 平行点捕捉 */
 Par = 8192,
 /**捕捉关闭 */
 Off = 16384,
}

二、位码运算：OSMODE 的底层逻辑

OSMODE 的值是基于“位码（Bitcode）”机制运算得出的，这要求每个捕捉模式的值必须是 2 的幂次方，以确保它们在二进制层面互不干扰。

1. 正向设置规则：

正向规则是指通过开启的捕捉端点模式，计算出最终的 OSMODE 值。当我们在 MxCAD 中组合捕捉功能时，实际上是在做加法或按位或运算。例如，若我们需要同时开启“端点（1）”、“中点（2）”和“圆心（4）”，系统会将这三个值相加（1 + 2 + 4 = 7），此时 OSMODE 的值即为 7。这种机制允许将任意数量的捕捉模式无缝融合在一个变量中。

在 TypeScript 中，我们可以这样实现正向计算：

/**
 * 根据选中的捕捉模式数组，计算最终的 OSMODE 总值
 * @param selectedModes 用户选中的捕捉模式枚举值数组
 * @returns 计算后的 OSMODE 数值
 */
export function calculateOsModeTotal(selectedModes: SysVarLongSketchSettingsOsMode[]): number {
 // 使用 reduce 进行累加，初始值设为 0 (代表没有任何捕捉开启)
 return selectedModes.reduce((total, currentMode) => {
 // 推荐使用按位或运算符 (|) 将当前模式合并到总数中
 // 例如: 0 | 1 = 1; 1 | 2 = 3; 3 | 4 = 7
 return total | currentMode;
 }, 0);
}

假设用户在界面上勾选了“端点”、“中点”和“圆心”，我们可以直接调用该方法得出需要设置给 MxCAD 的值：

// 1. 模拟用户选中的项
const userSelection = [
 SysVarLongSketchSettingsOsMode.End,   // 1
 SysVarLongSketchSettingsOsMode.Mid,   // 2
 SysVarLongSketchSettingsOsMode.Cen    // 4
];
// 2. 调用方法计算
const totalValue = calculateOsModeTotal(userSelection);
// 3. 输出结果
console.log(totalValue); 
// 控制台输出: 7 
// (二进制: 111，代表第1、2、3位都被激活了)

2. 反向推理规则

反向推理规则是指拿到 OSMODE 的值后，通过运算得到原始选择捕捉的端点。这依赖于“按位与（&）”运算。以 OSMODE = 7 为例，系统会依次用 7 与各个捕捉位码进行按位与操作：

• 7 & 1 = 1（成立，说明开启了端点）
• 7 & 2 = 2（成立，说明开启了中点）
• 7 & 4 = 4（成立，说明开启了圆心）

在 TypeScript 中，我们可以这样实现反向推理：

/**
 * 解析 OSMODE 数值，返回当前开启的捕捉模式列表
 * @param osModeValue 获取到的 OSMODE 整数值 (例如: 7)
 */
export function getEnabledOsnapModes(osModeValue: number): SysVarLongSketchSettingsOsMode[] {
 const enabledModes: SysVarLongSketchSettingsOsMode[] = [];
 // 遍历枚举中的所有位码值
 Object.values(SysVarLongSketchSettingsOsMode)
 .filter((v) => typeof v === 'number') // 过滤掉反向映射的字符串
 .forEach((bitCode) => {
 // 核心逻辑：按位与运算
 // 如果 (总值 & 某一项) === 某一项，说明该位被置为1，即被开启
 if ((osModeValue & (bitCode as number)) === bitCode) {
 enabledModes.push(bitCode as SysVarLongSketchSettingsOsMode);
 }
 });
 return enabledModes;
}

当 MxCAD 加载图纸时，我们需要读取当前的 OSMODE 状态，并同步到前端的 UI 勾选框上：

// 1. 假设从 MxCAD 获取到的当前 OSMODE 值为 15253
const currentOsMode = 15253;
// 2. 调用方法解析出具体开启了哪些捕捉
const activeModes = getEnabledOsnapModes(currentOsMode);
// 3. 输出结果
console.log(activeModes); 
// 控制台输出: [1, 4, 16, 128, 256, 512, 2048, 4096, 8192]
// 代表当前开启了：端点、圆心、象限点、垂足、切点、最近点、外观交点、延伸点、平行点

三、MxCAD 实战：捕捉功能的代码落地

在 MxCAD 的实际项目开发中，开发者可以通过丰富的 API 接口对 OSMODE 进行灵活控制。结合前面提到的位运算逻辑，我们可以轻松实现捕捉状态的读取、UI 回填、动态设置以及持久化处理，形成一个完整的业务闭环。

1. 获取状态与 UI 回填

通过调用 MxCAD 的系统变量读取接口，可以实时获取当前的捕捉配置。使用 getSysVarLong("OSMODE") 拿到数值后，再利用封装好的反向推理工具将其解析为具体的捕捉模式列表，从而同步到前端 UI 界面的勾选框上。

import { MxCpp } from “mxcad”;
// 1. 获取当前图纸的 OSMODE 值
const currentOsMode = MxCpp.getCurrentMxCAD().getSysVarLong(“OSMODE”);
console.log(“当前捕捉总值:”, currentOsMode);
// 2. 反向解析：根据总值获取当前开启了哪些捕捉
const activeModes = getEnabledOsnapModes(currentOsMode);
console.log(“当前开启的捕捉模式:”, activeModes);
// 3. UI 回填：将解析出的捕捉模式同步到前端界面的勾选框上
// 假设 uiState 是你的前端状态管理对象
activeModes.forEach((mode) => {
uiState.setOsnapChecked(mode, true);
});

2. 动态设置与持久化存储

当用户在界面上修改了捕捉选项时，可以通过正向计算得出新的总值，并使用 setSysVarLong("OSMODE", value) 将配置注入 MxCAD 引擎。同时，在实际的工程业务中，如果希望 OSMODE 的值能做持久化处理，避免每次打开图纸都需要重新配置，可以将 OSMODE 单独存储（如存入本地缓存或后端数据库），方便后续的读取和恢复。

// 4. 动态设置：假设用户在前端勾选了“端点(1)”和“中点(2)”，计算得出总值为 3
const totalValue = calculateOsModeTotal([
 SysVarLongSketchSettingsOsMode.End, 
 SysVarLongSketchSettingsOsMode.Mid
]);
// 5. 将新的捕捉配置设置回 MxCAD 引擎
MxCpp.getCurrentMxCAD().setSysVarLong("OSMODE", totalValue);
// 6. 持久化存储：将 OSMODE 单独存储（以存入 LocalStorage 为例），方便后续读取和设置
localStorage.setItem("my_cad_osmode", totalValue.toString());

这种代码级的控制，使得 MxCAD 能够轻松实现诸如“一键切换捕捉模式”、“智能绘图辅助”以及“用户个性化配置记忆”等高级功能。

四、效果演示：精准吸附的视觉体验

当 OSMODE 被正确配置后，MxCAD 将展现出极佳的交互体验。
1.在绘制线段时，光标靠近已有线条的端点，会自动触发高亮标记并牢牢吸附，确保新线条完美衔接

2.在绘制相切圆时，开启“切点（256）”捕捉，光标会沿着圆弧滑动并在切点位置精准锁定

3.在任意取点时，开启“最近点（512）”捕捉，光标会像被磁铁吸附般牢牢贴合线条边缘，精准锁定距离光标最近的几何位置，避免误选空白区域或偏离目标对象。

本作品采用《CC 协议》，转载必须注明作者和本文链接