# com.sldWorks：SOLIDWORKS 自动化

`com.sldWorks` 返回可直接访问 SOLIDWORKS API 的 COM 对象，并补充文档管理、模板校验、结构化模型反馈、视图导出以及 VBA/C# 宏功能。建模优先使用 API；图像用于辅助检查，而不是用鼠标坐标代替模型对象。

本版使用 **SOLIDWORKS 2025** 验证。`SaveAs` 调用的 `IModelDocExtension.SaveAs3` 要求 SOLIDWORKS 2020 SP02 或更新版本；其他版本不在本轮实测范围内。

## 快速开始：只观察，不修改模型

先启动 SOLIDWORKS，再执行：

```aardio
import com.sldWorks;
import JSON;

// 创建 SldWorks.Application 实例（已扩展增强），false 表示仅连接前台实例，不能仅连接后台实例（启动后保持 Visible=false）。
var sw,err = com.sldWorks(false);
if(!sw){
    print(err);
    return;
}

var documents = [];
for i,doc in sw.eachDocument(){
    table.push(documents,sw.GetDocInfo(doc));
}
print(JSON.stringify({app=sw.GetAppInfo();documents=documents},true));
```

没有活动文档不代表连接失败。可以先读取 `GetAppInfo()`，再通过 `NewDoc()` 或 `OpenDoc()` 取得目标文档。

## 指南

- [连接、文档管理与错误处理](documents.html)：连接模式、模板、打开/保存/关闭、COM 空对象、线程边界。
- [建模与反馈小闭环](modeling.html)：创建矩形和拉伸、修改尺寸、读取几何量、保存并导出；`NewSketch`/`Extrude` 助手与带孔零件示例。
- [模型反馈与图像](feedback.html)：摘要、有限特征扫描、草图状态、尺寸表、面列表、质量属性、PNG 与验证策略。
- [材料、自定义属性与配置](properties.html)：读取材料库、设置材料并用质量验证，读写自定义属性，配置增删/切换/派生、按配置压缩特征与回读规则；配置表 `GetConfigurationTable`/`ApplyConfigurationTable` 一次读写系列零件的尺寸/压缩/属性/材料/质量。
- [特征、装配与工程图助手](features.html)：按几何定位面/边、圆角、倒角、旋转、线性阵列（`toward` 自动定向与回读校正）/圆周阵列、装配体组件与配合、工程图视图与模型尺寸。
- [VBA 与 C# 宏](macros.html)：保留原有宏能力，使用模板传参并回读真实结果。
- [完整闭环示例源码](closed-loop.html)：运行后生成 SLDPRT、STEP、修改前后 PNG 与反馈 JSON。
- [带孔零件示例源码](plate-with-hole.html)：完全定义草图 → 拉伸 → 顶面找孔位 → 通孔切除 → 材料 → 属性 → 改尺寸 → 出图 → 保存。

## 常用入口

| 方法 | 用途 |
| --- | --- |
| `com.sldWorks(false,2025)` | 只连接已运行的前台实例；指定版本则不允许回退版本，年份可以用数值或字符串；如无必要不需要限定年份，不必步步设防 |
| `FindDoc(nameOrDoc)` | 通过文档对象、完整路径或准确标题定位 |
| `GetDefaultTemplate(docType)` | 读取并验证当前配置的模板，不弹选择框 |
| `NewDoc(docType,template)` | 从有效模板新建文档 |
| `OpenDoc(path,docType,options,config,visible)` / `ActivateDoc(nameOrDoc)` | 打开（可隐藏加载）/ 激活，保留原生状态码；拒绝同名冲突 |
| `SaveAs(path,version,options,exportData,doc,advancedOptions)` | 保存或导出完整模型；拒绝同名不同路径冲突 |
| `SaveDoc(doc)` | 保存已有路径的文档 |
| `GetDocumentList()` / `CloseDoc(doc,discard)` / `CloseDocs` / `CloseNewDocs(snapshot)` | 文档快照 / 按对象安全关闭 / 批量关闭 / 清理本任务打开的文档 |
| `com.sldWorks.isResponsive()` / `sw.IsResponsive()` | 不经 COM 探测 SOLIDWORKS 是否响应，连接前与长任务中调用 |
| `GetDocInfo(doc)` | 读取纯数据文档摘要（含单位、配置、材料） |
| `eachFeature(doc)` / `GetFeatures(doc,limit)` / `FindFeature(doc,name)` | 原生顶层特征遍历 / 有限纯数据诊断 / 按名取特征 |
| `NewSketch(doc,target,draw,name)` | 在基准面或面上安全地新建草图并找回草图特征 |
| `Extrude(doc,sketch,options)` | 凸台或切除拉伸，选项表代替 23/27 个位置参数 |
| `GetSketchInfo(doc,feature)` | 草图完全定义状态与轮廓数量 |
| `GetDimensions(doc,feature)` / `SetDimension(doc,name,value)` | 列出尺寸 / 设置尺寸并重建回读 |
| `GetFaces(doc)` / `GetEdges(doc)` / `FindEntity(doc,type,{x,y,z})` / `SelectByPoint(doc,type,x,y,z)` | 面与边的纯数据 / 按几何定位实体 / 选择实体 |
| `Fillet` / `Chamfer` / `Revolve` / `LinearPattern` / `CircularPattern` | 常用特征，选项表代替长参数列表；`LinearPattern` 用 `toward1/toward2` 指定方向并回读实际方向 |
| `GetConfigurations` / `AddConfiguration` / `ActivateConfiguration` / `DeleteConfiguration` | 配置明细 / 新增（可派生、可不激活）/ 激活并重建 / 删除（拒绝活动与唯一配置） |
| `GetFeatureSuppression` / `SetFeatureSuppression(doc,feature,suppressed,configuration)` | 按配置读取 / 压缩、解除压缩特征并逐配置回读 |
| `AddComponent` / `GetComponents` / `AddMate` / `GetMates` | 装配体组件与配合 |
| `GetDrawingViews` / `InsertModelDimensions` / `AddNote` | 工程图视图、模型尺寸、注释 |
| `GetMaterials()` / `GetMaterial(doc)` / `SetMaterial(doc,name)` | 材料库解析 / 读取 / 设置并回读 |
| `GetCustomProperties(doc)` / `SetCustomProperty(doc,name,value)` | 自定义属性读写 |
| `GetMassProperties(doc)` | 整个模型的 SI 质量属性 |
| `RebuildDoc(doc)` | 重建并检查返回状态 |
| `CaptureView(path,doc,width,height,view)` | 导出模型视图并返回图像元信息；可选标准视图名 |
| `com.nothing()` | 构造原生接口要求的空 COM 对象 |
| `VBA(code,templateOwner)` / `NetCompiler("C#")` | 文本宏 / C# 宏编译 |

`doc` 参数省略时通常使用活动文档；自动化更建议显式传入已经核对过的目标文档，避免活动窗口改变后操作错模型。

## 本版兼容性说明

- 保留原有构造、`OpenDoc`、`ActivateDoc`、`SaveAs`、`RunMacro`、`VBA`、`NetCompiler` 入口。
- `SaveAs` 的原四个参数顺序不变；后面新增目标文档和高级保存选项。现在默认导出**完整模型**，会激活目标并清空选择；要导出选择子集请自行调用原生接口。
- 打开/保存成功时也返回原生错误、警告码，不再丢弃。特别是 `OpenDoc` 返回了文档也不等于引用文件完整。
- 修正数值年份转换、未保存文档标题激活、默认参数与宏模板错误处理。
- 默认模板无效时明确失败，不自动猜选模板或修改全局设置。
- 第二版新增草图/拉伸/尺寸/面/材料/自定义属性助手，均为附加方法；`GetDocInfo` 与 `GetFeatures` 只增加字段，`CaptureView` 只增加可选的 `view` 参数，原有调用不受影响。
- 第三版新增边/圆角/倒角/旋转/阵列/装配配合/工程图助手（见 [features.md](features.html)），以及会话安全：`SaveAs`/`OpenDoc` 拒绝同名不同路径冲突；`CloseDoc` 改为按对象安全关闭（默认拒绝丢弃未保存修改，原生行为改用 `QuitDoc`）；`OpenDoc` 增加 `visible` 参数，`AddComponent` 默认隐藏加载组件；新增 `GetDocumentList/CloseDocs/CloseNewDocs/IsResponsive` 与静态 `probe/isResponsive`。

## 使用边界

连接的是桌面 SOLIDWORKS 会话，不是无界面 CAD 内核。建模 API 通常不需要前置窗口；图像导出仍依赖可用的模型图形窗口。模态对话框、程序忙、进程退出等情况仍会影响 COM 调用；主线程不泵消息时 COM 调用会无限等待，请先用 `com.sldWorks.isResponsive()` 探测，并遵守 [会话卫生](documents.html) 一节（唯一文件名、快照清理、不堆积同名文档）。

不要将“函数未抛异常”“宏引擎返回成功”或“截图看起来正确”单独当作任务完成依据。应同时核对目标文档、状态码、实体/特征、尺寸或体积等业务不变量。