# @constructorfleet/sketchforge-engine 中文文档

规范地址：https://npmcn.com/package/%40constructorfleet/sketchforge-engine/

版本：1\.30\.0
npm 元数据更新时间：2026-10-28T04:27:58.449Z
中文译文更新时间：2026-11-10T16:18:50.169Z
软件包许可：AGPL-3\.0-only

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40constructorfleet/sketchforge-engine
原文对照：https://npmcn.com/package/%40constructorfleet/sketchforge-engine/?lang=original
项目主页：https://github.com/constructorfleet/SketchForge-3D#readme
源码仓库：https://github.com/constructorfleet/SketchForge-3D

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.5 MB，437 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：7 个
- 首次发布：2026-10-20T23:46:27.925Z
- 最新版本发布：2026-10-28T04:27:58.086Z
- 近 30 天下载量：5205（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 27 个）

## 中文简介

SketchForge的可移植几何和项目引擎.

## 安装

```sh
npm install @constructorfleet/sketchforge-engine
```

也可以使用：`pnpm add @constructorfleet/sketchforge-engine`、`yarn add @constructorfleet/sketchforge-engine`、`bun add @constructorfleet/sketchforge-engine`

## README

# SketchForge 引擎

`@constructorfleet/sketchforge-engine` 是SketchForge的项目模型和几何操作的TypeScript包。 它用于Node.js应用程序,这些应用程序需要读取或修改SketchForge项目,构建参数化形状,或者不运行网页编辑器而导入并导出几何.

## 节点兼容性

软件包的表单宣布了节点.js 20 或更新,但范围比其全几何堆栈支持的运行时间要宽: 已锁定 `brepjs` 依赖需要节点24或更新. 完整引擎使用Node.js 24+,包括精确的CAD和内核后置操作. 在Node.js 20–23上,npm可能警告依赖引擎的要求,而完整的引擎行为是不支持的. 软件包的引擎范围应该在未来的软件包发行中与这种依赖性相配合.

## 安装

```sh
npm install @constructorfleet/sketchforge-engine
```

软件包是ECMAScript模块(ESM). TypeScript 申报船与包件; 不分开 `@types` 需要软件包.

## 快开始

在不启动编辑器或打开工程的情况下从参数构造形状 :

```js
import { shapeFromRequest } from "@constructorfleet/sketchforge-engine";

const shape = shapeFromRequest({ kind: "box", width: 20, depth: 10, height: 5 });
if (!shape) throw new Error("The requested shape could not be built");
console.log(shape.kind, shape.width, shape.depth, shape.height);
```

形状请求是纯数据,可以存储或传递到 `createEngine`。 。 。 . `shapeFromRequest` 返回时 `null` 用于不能单独从参数创建的种类(例如,无几何线网).

要运行项目操作, 请将一个引擎绑定在 SketchForge 使用的目录存储上 :

```js
import { createEngine, directoryProjectStore } from "@constructorfleet/sketchforge-engine";

const projectsDirectory = process.env.SKETCHFORGE_PROJECTS_DIR;
if (!projectsDirectory) throw new Error("Set SKETCHFORGE_PROJECTS_DIR to the project directory");
const engine = createEngine(directoryProjectStore(projectsDirectory));
const result = await engine.project("project-id");
if (!result.ok) throw new Error(`Could not read project: ${result.failure.reason}`);
console.log(`Revision ${result.value.revision}; ${result.value.shapes.length} shapes`);
```

设定 `SKETCHFORGE_PROJECTS_DIR` 转到 SketchForge 已经使用的目录,并替换 `project-id` 带有现有项目标识。 目录必须包含支持的磁盘格式的工程. 保持对该目录的访问限制在可信任的本地代码: 此软件包是一个几何/项目库,而不是HTTP服务或访问控制边界.

## 公共 API

软件包根是支持的导入表面 。 它的主要引擎外观是 `Engine`,创建于 `createEngine(store)`每次操作返回一个 `EngineResult<T>`; 检查 `ok` 读取前 `value` 或者说 `failure`。 。 。 .

| 区域 | `Engine` 方法 | 他们做什么 |
| --- | --- | --- |
| 读取和编辑工程 | `project`, (中文(简体) ), `addShapes`, (中文(简体) ), `changeShape`, (中文(简体) ), `removeShape` | 读取放置的形状和项目元数据;添加参数化的形状或改变/移动已存在的形状. |
| 安排和重复 | `align`, (中文(简体) ), `distribute`, (中文(简体) ), `pattern`, (中文(简体) ), `mirrorBaked` | 将所选形状放入共享轴上,放出,创建线性/循环复制,或镜像支持的固体. |
| 导入和合并 | `importMesh`, (中文(简体) ), `cut`, (中文(简体) ), `group`, (中文(简体) ), `ungroup`, (中文(简体) ), `separate`, (中文(简体) ), `explode` | 导入模型文件, 减/ 组固件, 拆分组/ 体, 或爆炸一个保留的 STEP 组装 . |
| 检查和计量 | `edges`, (中文(简体) ), `faces`, (中文(简体) ), `measurements`, (中文(简体) ), `properties`, (中文(简体) ), `measureBetween`, (中文(简体) ), `interference` | 查询精确的几何地貌地貌,形状属性,相距/相角,以及缺口/相重叠. |
| 修改精确的几何 | `treat`, (中文(简体) ), `draftPrism`, (中文(简体) ), `shell`, (中文(简体) ), `changeShape` | 应用边缘处理, 起草出出角, 保留有边框的草图面部草稿, 或空心的形状. |

这些行动针对 **现有项目标识** 在一个 `ProjectStore`;此软件包不创建项目,项目记录,也不初始化项目目录. `addShapes` 是已存在的工程的第一个写入操作。 所有写入都持续到配置的商店 .

主要入境点还出口这些API区域:

-   **项目和业务:** `directoryProjectStore`, (中文(简体) ), `createEngine`, (中文(简体) ), `Engine`, (中文(简体) ), `EngineResult`, (中文(简体) ), `EngineFailure`,项目和业务请求/结果类型.
-   **形状请求 :** `shapeFromRequest`, (中文(简体) ), `shapeWithRequestedChanges`, (中文(简体) ), `REQUESTABLE_SHAPE_KINDS`,加上描述参数化形状的类型.
-   **项目文件和交换:** `.skf` 进出口和检查; 网格导入; STEP和场景导出; SVG/DXF 部分输出; StEP 组装爆炸.
-   **几何和 CAD:** 原始的构造器,精确的固体,分块,地貌分析,外形界限,CAD测量,炮击,边缘处理,壁厚,和投影布局.
-   **安置和重复:** 对齐/分发帮助器,图案布置帮助器,形状边框,镜像,条形化,以及工作计划洞-模式帮助器.

见 [生成类型脚本 API 引用](https://constructorfleet.github.io/SketchForge-3D/docs/reference/typescript-engine) 每个符号和声明。 参考链接可追溯到此用法指南. 有关文件: [(原始内容存档于2013-10-12) (英语). REST API](https://constructorfleet.github.io/SketchForge-3D/docs/REST_API), (中文(简体) ), [项目格式](https://constructorfleet.github.io/SketchForge-3D/docs/SKF_PROJECT_FORMAT),以及 [类型脚本客户端](https://constructorfleet.github.io/SketchForge-3D/docs/packages/typescript-client)。 。 。 .

## 编辑一个草图支持的功能

摇摆起起伏 扫荡出马厩 `sketchSourceId` 在生成的形状上。 把身份证传给你 `engine.changeShape(projectId, sketchSourceId, { sketchProfile })` 重建这个功能。 对于一个持续的草图轮回,同一源ID也接受操作设置更新,如 `{ sides: 64 }`棱镜草案保留了 `draftPrismAngle`; 源编辑接受 `{ draftPrismAngle: 12 }` 并在挤压剖面改变时重新应用草稿。 保留草图挤压,扫荡,符合条件的相轮可以存储一张相机草稿 `{ faceDraft: { sourceFaceId, angle, pullDirection } }`; 使用来自 `engine.faces`,并使用 `null` 来清理它。 配置文件编辑会按所存储的正态解析所选的平面并需要精确的匹配;它们永远不会将旧的平面索引向前. `.skf` 来回出行保存了面部草稿和源框. 单发素描挤出可以将一面文稿与一面文稿相接而后再取出一面全高尖的平马. 单节无孔草图扫地可以将一面草图与一面草图相接而后再取出一面全高平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平 扫荡处理重放源,草稿后再在剖面编辑上进行处理,包括归档导入后;测试涵盖回程,回放,不支持角度,以及原子拒绝. 扫瞄面部草稿不支持多节,分节孔,选取的尖端治疗,或附加治疗. 一个平坦的单区域全回合草图可以将一个面部草稿组合在一起,然后是一对称的45°全缘相机或一对全缘相机;配置和设置编辑重放源,草稿后再处理,包括归档导入后. 其他面部草稿处理组合,棱镜草稿和炮击仍然得不到支持. 当输出被嵌入被烘焙的布林组内时,引擎更新了草图输出,并在写出项目之前从保留了的操作中重新计算出它的布林祖先. 每个被重建的祖先都通过组的帧被放置在被解组的方式来安置组的子孙,因此一个被移动,转出,镜像或被再造后被调整大小的组保持了该放置,镜像和尺度贯穿编辑. 编辑是原子:无效的剖面图,缺失或模糊的面相匹配,或者失败的依赖重建让被存储的项目保持不变.

这种重算目前包括了草图背起的挤压,转盘,并被布林组所打入巢中,外加一个保留了的棱镜-草案角度应用于草图外接. 其他下游操作仍然被烘焙或不支持用于源驱动重算,目前还没有通用特征图. `.skf` 导出保留已更新的草图配置、草稿角度和重计算布尔结果.

## 限制

-   该软件包不提供SketchForge网络UI,HTTP路由,认证,或远程项目客户端. 使用 [类型脚本客户端](https://www.npmjs.com/package/@constructorfleet/sketchforge-client) 倒计时.
-   没有软件包级别 `meshForShape` 调度器; 使用原始的构建器或精确的固态帮助器来进行它们支持的特定形状类型.
-   引擎读取和写入 SketchForge 工程 `ProjectStore`· ; `directoryProjectStore` 是一个本地文件系统执行。 它期望有效的项目文件和与 SketchForge 的项目惯例管理的一个目录.
-   只参数形状创建不创建所绘制的草图或任意的网状几何. 导入网格数据通过 `engine.importMesh` 或使用编辑器绘制工作流程.
-   CAD,STEP,以及精确的固态操作依赖于本土/WASM几何依赖性,可以比纯参数和安放帮助器更需要资源. 当这些操作运行时,内核特定模块被加载.
-   使用软件包根作为支持的公开 API 。 导出图还允许对已编译模块进行子路径导入,但无文件的内部模块不是一个相容的承诺.

## 许可证

此软件包根据 [仅限AGPL-3.0](https://github.com/constructorfleet/SketchForge-3D/blob/main/LICENSE)。 。 。 .

## 常见问题

### @constructorfleet/sketchforge-engine 是什么？

SketchForge的可移植几何和项目引擎\.

### 如何安装 @constructorfleet/sketchforge-engine？

在项目目录运行 npm install @constructorfleet/sketchforge-engine，或使用 pnpm add / yarn add / bun add。

### @constructorfleet/sketchforge-engine 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @constructorfleet/sketchforge-engine 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @constructorfleet/sketchforge-engine 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @constructorfleet/sketchforge-engine 可以商用吗？

@constructorfleet/sketchforge-engine 使用 AGPL-3\.0-only 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @constructorfleet/sketchforge-engine 的下载量有多少？

根据 npm 官方下载统计，@constructorfleet/sketchforge-engine 在 2026/10/11 – 2026/11/09 这 30 天内被下载 5,205 次，日均约 174 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @constructorfleet/sketchforge-engine 还在维护吗？

最新版本 1\.30\.0 发布于 2026/10/28（13 天前）；至今共发布 27 个版本，其中过去 12 个月发布了 27 个；首次发布于 2026/10/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。