连接、文档管理与错误处理

1. 连接模式

import com.sldWorks;

// 参数 @2 为 false 时只附加已运行的实例。
var sw,err = com.sldWorks(,false);
if(!sw){ print(err); return; }
print(sw.GetAppInfo());

• com.sldWorks()：先连接已运行的通用实例，失败后尝试创建。
• com.sldWorks(false)：只连接已运行的通用实例，允许版本回退。
• com.sldWorks(true,2025)：指定版本，失败时保留向其他已安装版本回退的旧行为。
• com.sldWorks(false,2025)：仅连接但不创建新实例、不跨版本回退，并核对返回实例的实际主版本。
• com.sldWorks(ISldWorksObject)： 封装已有的原生 ISldWorks COM 对象，为它添加本库的方法。

构造参数 @2 支持年份或表示主版本的整数，不接受完整修订字符串。 2025 对应内部主版本 33；33.4.0 是运行实例的修订号，而不是构造函数的版本参数。 对于普通的桌面应用或 AI 自动化，一般没必要限定版本号。建议忽略一台电脑跑多个版本 SOLIDWORKS 的边界情况，步步设防把简单的事复杂化无实际意义。

进程权限应一致。同版本多实例可能共享 COM 注册入口，本库不承诺选中其中哪一个；必要时先通过 GetProcessID() 和文档路径核对。不要误以为重复构造必然得到独立实例。

不要在 aardio 线程间直接传递 SOLIDWORKS COM 对象。每个执行线程内重新连接、按路径重新获取对象；跨线程只传参数和纯数据反馈。已关闭文档、重建后失效的面/边引用也必须重新获取。

2. 新建文档：先验证模板

NewDoc(docType,template,paperSize,width,height)：

支持 .prtdot、.asmdot、.drwdot。库检查模板存在且扩展名与文档类型一致，再调用 NewDocument。文件存在不代表模板一定有效，最终仍检查 SOLIDWORKS 的返回值。

import com.sldWorks;
var sw,err = com.sldWorks(false);
if(!sw){ print(err); return; }

// 示例位置，请根据实际安装修改；不是库内硬编码的回退路径。
var template = "%ProgramData%\SOLIDWORKS\SOLIDWORKS 2025\templates\gb_part.prtdot";
var doc,newError = sw.NewDoc(1,template);
if(!doc){ print(newError); return; }
print(sw.GetDocInfo(doc));

GetDefaultTemplate(1) 只读当前设置。如果路径指向旧版本、移动后的目录或已删除文件，会返回 null,说明，不会自动改注册表、首选项或弹模板选择框。显式给 NewDoc 传模板也不会修改默认模板配置。

3. 查找与激活

FindDoc() 取活动文档；也可传文档对象、完整路径或准确标题。标题忽略大小写比较，但不是模式匹配。有歧义时失败，完整路径查找失败时不会退而选择同名文档。

import com.sldWorks;
var sw,err = com.sldWorks(false);
if(!sw){ print(err); return; }

var doc,findError = sw.FindDoc();
if(!doc){ print(findError); return; }
var activated,status,message = sw.ActivateDoc(doc);
if(!activated){ print(status,message); return; }
if(status) print("激活附带状态，需要检查：",status);

默认 ActivateDoc(nameOrDoc,false,1) 不依据用户的“激活时重建”首选项，也不弹出询问框。如果文档需要重建，可能返回有效文档和 swDocNeedsRebuildWarning；请按任务需要调用 RebuildDoc。

未保存的文档使用 GetTitle()，不能先把该标题当文件路径转换。保存改名后应重新读取标题。

4. 打开与状态码

import com.sldWorks;
var sw,err = com.sldWorks(false);
if(!sw){ print(err); return; }

var doc,errors,warnings,message = sw.OpenDoc("/models/example.SLDPRT");
if(!doc){ print("打开失败",errors,warnings,message); return; }
if(errors || warnings){
    print("已返回文档，但载入不完整或有警告：",errors,warnings);
    return; // 先诊断，不盲目继续修改
}
print(sw.GetDocInfo(doc));

OpenDoc(path,docType,options,config) 默认推断原生扩展名，options=1（静默），config=""。只读可用 options=1|2。原生错误/警告为枚举位掩码，可按需要用按位与检查，不能只按单个相等值判断。

返回有效文档和非零错误码是可能的，例如装配体缺少引用文件。不要丢弃这些诊断，也不要把有效对象当作“完全成功”。STEP、IGES 等中性格式不由文件后缀假装成 SLDPRT；应根据对应格式使用原生 LoadFile4 和导入数据接口。

5. 保存、导出、关闭

import com.sldWorks;
var sw,err = com.sldWorks(false);
if(!sw){ print(err); return; }
var doc,findError = sw.FindDoc();
if(!doc){ print(findError); return; }

var outputDir = io.createDir("/output");
if(!outputDir){ print("不能创建输出目录"); return; }
var saved,errors,warnings,message = sw.SaveAs(io.joinpath(outputDir,"example.SLDPRT"),,,,doc);
if(!saved){ print("保存失败",errors,warnings,message); return; }
if(warnings) print("保存警告",warnings);

// STEP 导出也是 SaveAs，根据扩展名决定转换格式。
var exported,exportError,exportWarning = sw.SaveAs(io.joinpath(outputDir,"example.step"),,,,doc);
print(exported,exportError,exportWarning);

SaveAs(path,version,options,exportData,doc,advancedOptions)：

• 默认 version=0、options=1，对象空参自动构造 Nothing。
• doc 省略取活动文档；会激活目标并清空选择，避免只导出部分面或实体。
• 不自动创建保存目录；可能覆盖目标文件。生产脚本应使用独立输出目录、复制模型或预先检查目标是否存在。
• exportData 可传 PDF 等导出对象，advancedOptions 可传原生高级保存选项。
• SaveDoc(doc,options) 用原路径保存。新文档没有路径时直接失败，不弹另存为框。

CloseDoc(doc,discardChanges) 覆盖了原生按标题关闭的接口：doc 用法同 FindDoc（"" 表示活动文档）；默认拒绝丢弃未保存修改，必须显式传 discardChanges=true；同标题歧义时拒绝执行；已保存文档按完整路径唯一定位。成功返回 true,状态：closed 已关闭；hidden/referenced 表示文档仍被其他打开文档引用，SOLIDWORKS 只释放了窗口、模型数据仍在内存（正常行为，装配体关闭后自动释放）。原生行为可直接调用 QuitDoc(name)。不要为了清理自己的任务而调用 CloseAllDocuments(true)。

自行启动的后台实例在关闭最后一个文档时可能退出。要保留会话，可显式设置 sw.UserControl=true。本库不自动调用 ExitApp()。

5.1 会话卫生：同名冲突、快照清理与响应探测

SOLIDWORKS 按文件名（含扩展名）索引已打开文档：UI 会拒绝同时打开两个 block.SLDPRT（不同目录），但 SaveAs3 等 API 会放行。实测在一次自动化中反复把新文档另存为同名文件、又从不关闭旧文档，累计近 30 个文档后，SOLIDWORKS 主线程进入数小时的无响应状态，所有 COM 调用（包括重新连接）都无限等待。因此：

• SaveAs、OpenDoc 现在会先检查“已打开另一个同名不同路径的文档”，命中直接返回失败说明（SaveAs 为 false,-1,0,说明，OpenDoc 为 false,65536,0,说明，65536 即原生 swFileWithSameTitleAlreadyOpen），不调用 SOLIDWORKS。
• 自动化输出的文件名应带运行标记（时间戳或随机数），不要用固定名字覆盖。
• 任务开始时用 GetDocumentList() 记录快照，结束时用 CloseNewDocs(snapshot[,discardChanges]) 关闭自己打开的全部文档，包括 AddComponent、工程图视图隐式加载的引用文档。CloseDocs(docs) 按 工程图 → 装配体 → 零件 顺序批量关闭。
• AddComponent 默认以 visible=false 隐藏加载组件文件（OpenDoc(path,,,,false) 内部调用 DocumentVisible，用后自动恢复），不再弹出组件窗口。

import com.sldWorks;

// 连接前先探测：主线程不泵消息时任何 COM 调用都会无限等待，探测本身不经 COM。
var responsive,probe = com.sldWorks.isResponsive(2000);
if(!responsive){
    print(probe.running ? "SOLIDWORKS 无响应，请检查是否有模态对话框或长时间命令" : "SOLIDWORKS 未运行",probe);
    return;
}
var sw,err = com.sldWorks(false);
if(!sw){ print(err); return; }

var snapshot = sw.GetDocumentList(); // 任务开始前已打开的文档，不属于本任务
var runTag = tostring(time(),"%Y%m%d-%H%M%S");
var outputDir = io.createDir("/output/run-" + runTag);

var doc,newError = sw.NewDoc(1,"%ProgramData%\SOLIDWORKS\SOLIDWORKS 2025\templates\gb_part.prtdot");
if(!doc){ print(newError); return; }
// ... 建模 ...
var saved,errors,warnings,message = sw.SaveAs(io.joinpath(outputDir,"part-" + runTag + ".SLDPRT"),,,,doc);
if(!saved){ print(errors,message); }

// 结束：只关闭本任务打开的文档；未保存的修改必须显式允许丢弃
var cleanup = sw.CloseNewDocs(snapshot,true);
print(cleanup.count,cleanup.failed);
print(sw.IsResponsive(1000));

com.sldWorks.probe(timeout,processId) 返回 {running,responsive,processes=[{pid,responsive,hungThreads,mainWindow={title,hung},dialogs=[{title,text}],probed}]}：用 SendMessageTimeout(WM_NULL) 逐线程探测消息响应、读取 IsHungAppWindow，并列出可见的 #32770 对话框及其文本。已连接后可用 sw.IsResponsive(timeout)（使用连接时缓存的 sw.ProcessId）。探测发现无响应时不要继续发 COM 调用，也不要在代码里强杀进程；把 dialogs 与主窗口标题交给人工处理。

这台验证机显卡老旧、三维显示很慢，但上述无响应事故的根因是同名文档堆积，不是显示性能；在正常工作站上同样会发生。

6. 返回值约定

为兼容旧程序，已有文件操作保留首返回值的布尔/对象习惯：

-1 是本库的前置检查标识，不是 SOLIDWORKS 原生文件错误码。COM 断开、调用不受支持的成员等异常仍可能抛出；库不会吞掉所有异常，也不自动重试可能已经产生副作用的写操作。

7. 原生参数：Nothing 与输出引用

import com.sldWorks;

var noObject = com.nothing(); // VT_DISPATCH + NULL，等价 VBA Nothing
var errors = com.int(0,true);         // int 输出引用
var isWarning = com.Variant(false,11/*_VT_BOOL*/,true); // bool 输出引用
print(noObject.vt);                   // 9

某些 SOLIDWORKS 原生方法要求空对象而不接受普通 null。例如 SelectByID2 的 callout、SaveAs3 的 exportData 和 advancedOptions。应使用经过验证的 nothing()， com.Variant(null,9) 则会忽略第 2 个参数并返国 _VT_NULL 类型。

原生 GetErrorCode2 的输出参数是 BOOL，不是 int。没有运行时类型信息时，不能用普通变量代替明确构造的输出引用。

官方接口依据

• ActivateDoc3
• SaveAs3
• CloseDoc

返回首页

Markdown 格式