教程 ↗

用 SolidCraft 浏览器 API 创建第一个参数化盒体:页面调用、几何读回与会话边界

基于 SolidCraft v0.16.2 官方浏览器入口的实测记录,演示如何通过 window.solidcraft 创建 30 x 20 x 10 mm 参数化盒体、读回精确几何与拓扑数据、验证撤销重做历史,并厘清网页 API 与桌面 MCP 的运行机制。

由参数、浏览器命令和几何读回组成的参数化盒体工作流

用代码生成参数化 3D 小零件时,可以先在浏览器中创建一个尺寸明确的实体,再读回体积、包围盒和拓扑计数核对几何。若你试过带尺寸约束的 SVG 草图工作流,显式单位和程序化读回能减少不少肉眼核对。

我们打开 SolidCraft 的官方浏览器入口 https://solidcraft.io/app,从一个单位为 mm、没有 body 和 timeline feature 的 Untitled 设计开始,通过页面控制台调用 window.solidcraft 创建 30 x 20 x 10 mm 的长方体,读取它的几何测量结果,再沿时间线执行一次撤销和重做。这组操作记录了页面 API 的调用和读回数据,也说明了本次浏览器会话与网页 UI、桌面 MCP 的关系。

为什么从单个 30 x 20 x 10 mm 盒体开始

tangency-labs/solidcraft 是一个用 Rust 编写的开源参数化 3D CAD 项目,官方仓库 README 同时列出了桌面端、浏览器端、CLI 和 MCP 四种形态。初次接触时,开发者很容易产生疑问:在浏览器控制台里敲命令,和在本地终端里跑 CLI 或连接 MCP,操纵的究竟是不是同一个设计会话?

选择一个 30 x 20 x 10 mm 的标准盒体作为测试起点,是因为它的理论几何值可以直接口算:体积为 6000 mm3,表面积为 2200 mm2,从原点正向生成时包围盒范围是 [0, 0, 0] 到 [30, 20, 10],质心位于 [15, 10, 5],且具备标准六面体的 6 个面、12 条边和 8 个顶点。通过 API 创建实体并开启测量读回,一眼就能确认命令执行与几何内核输出是否吻合,同时观察网页 UI 的特征时间线与撤销栈是否同步更新。

页面 API 与当前标签页的共享机制

根据 v0.16.2 的浏览器 API 官方文档,当浏览器页面加载完成后,全局对象 window.solidcraft 会直接作用于当前标签页里的设计。官方暴露的核心接口有四个,调用均返回 Promise:

  • solidcraft.request(method, params?):发送控制请求,例如关闭起始面板或切换界面状态。
  • solidcraft.execute(command, params?):执行具体的建模或编辑命令。
  • solidcraft.commands():列出当前可用的命令与参数定义。
  • solidcraft.inspect(params?):检查当前设计状态,支持传入 { measure: true } 获取几何测量数据。

这套页面 API 与网页 UI 共享同一套底层状态:它直接复用相同的命令 ID、参数结构、控制处理器(control handler)和 undo history,调用时不会在后台另外启动独立引擎或外部服务器。同时,页面 API 的运行范围也完全收敛在当前浏览器标签页内:它不注册 WebMCP 工具,也不暴露网络监听器;脚本仅具备页面级浏览器权限,任何文件路径都指向浏览器虚拟文件系统,无法借此访问任意桌面文件或系统窗口。

最小可核对实验:创建、测量与撤销重做

在空的 Untitled 设计(单位 mm、无 body、无 timeline)状态下,我们按顺序执行了以下最小代码片段:

await solidcraft.commands();
await solidcraft.request("ui.home", { open: false });
await solidcraft.execute("solid.box", {
  length: 30,
  width: 20,
  height: 10,
  body_name: "Browser API box"
});
const created = await solidcraft.inspect({ measure: true });
await solidcraft.execute("edit.undo");
const afterUndo = await solidcraft.inspect({ measure: true });
await solidcraft.execute("edit.redo");
const afterRedo = await solidcraft.inspect({ measure: true });

这段脚本先通过 solidcraft.commands() 获取命令目录,并用 solidcraft.request("ui.home", { open: false }) 收起起始面板,随后调用 solidcraft.execute("solid.box", ...) 创建命名为 "Browser API box" 的 30 x 20 x 10 盒体。紧接着调用 solidcraft.inspect({ measure: true }),并在 edit.undo 和 edit.redo 之后各执行一次 inspect 观察状态变化。

SolidCraft 英文界面显示通过浏览器 API 创建的 30 x 20 x 10 mm 盒体

SolidCraft 页面中的 30 x 20 x 10 mm 盒体,测量读回见下文。

创建完成后的第一次 inspect({ measure: true }) 读回结果与口算值完全吻合:

  • 体积与面积:体积为 6000 mm3,表面积为 2200 mm2。
  • 包围盒与质心:包围盒 min 为 [0, 0, 0]、max 为 [30, 20, 10],质心位于 [15, 10, 5]。
  • 拓扑计数:6 个面、12 条边、8 个顶点。

在这次实测中,solid.box 创建调用返回了 22 ms 的耗时记录,但这只是单次简单原语在当前会话里的观测值,不能当作性能基准。而随后的历史栈操作则清晰体现了页面 API 与 UI 时间线的同步关系:执行 edit.undo 并再次 inspect 后,bodies 为空、timeline 为空、undo 计数为 0、redo 计数为 1;接着执行 edit.redo 并 inspect,这一个 body 和时间线上的 Box1 feature 随即完整恢复。

需要注意的是,所有这些状态流转都发生在当前内存会话中。根据浏览器 API 的生命周期机制,隐藏或暂停标签页会延迟请求完成,重新加载页面则会直接结束当前会话与待处理请求;本次实验也没有涉及模型导出、重新导入或跨重载的持久保存。

浏览器页面 API、网页 UI 与桌面 MCP 的关系

理清了页面 API 与网页 UI 共用同一会话后,就能看清它与桌面 MCP 的架构差异。根据 v0.16.2 的MCP 官方文档,桌面 MCP 是另一条独立文档化的路径:solidcraft-cli mcp 在默认的 headless 模式下拥有自己的独立设计 session,只有显式带上 --connect 参数时,才会桥接到正在运行的应用程序。本文仅在官方浏览器入口完成了单个盒体的页面 API 实测,没有测试桌面 app 或桌面 MCP,也没有验证草图约束重建与大型复杂模型。

对于想先在网页里验证参数化小零件逻辑的开发者来说,无需安装本地环境,直接打开官方浏览器入口调用 window.solidcraft 并配合 inspect({ measure: true }) 读回数据,是一条非常轻量的起步路径。至于涉及到跨会话文件持久化、复杂装配体、草图约束重建或本地 MCP 工具链集成的场景,则需要留待后续在对应环境中单独验证。

← 返回列表