# @hlang-org/editor-core 中文文档

规范地址：https://npmcn.com/package/%40hlang-org/editor-core/

版本：0\.1\.1
npm 元数据更新时间：2026-11-01T05:50:27.914Z
中文译文更新时间：2026-11-01T08:56:02.351Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40hlang-org/editor-core
原文对照：https://npmcn.com/package/%40hlang-org/editor-core/?lang=original
项目主页：https://github.com/hlang-tech/hlang/tree/main/packages/editor-core#readme
源码仓库：https://github.com/hlang-tech/hlang

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

- 包体积（解压后）：562 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：2 个
- 首次发布：2026-11-01T04:16:55.502Z
- 最新版本发布：2026-11-01T05:50:27.719Z
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

Lumen编辑器的无头核心：图形模型、可逆命令、验证、诊断和IGraph序列化。没有React，就没有DOM。

## 安装

```sh
npm install @hlang-org/editor-core
```

也可以使用：`pnpm add @hlang-org/editor-core`、`yarn add @hlang-org/editor-core`、`bun add @hlang-org/editor-core`

## README

![hlang editor-core](https://raw.githubusercontent.com/hlang-tech/hlang/main/media/brand/packages/editor-core.png)

# @hlang-org editor-core

Lumen的无头核心，hlang视觉编辑器。它保存正在编辑的图，仅通过可逆命令更改图，验证连接，报告编辑时诊断，并序列化到 `IGraph`． 它的公共API中没有React，没有DOM，也没有RxJS，所以它可以在任何JavaScript环境和普通单元测试中运行。

[![npm](https://img.shields.io/npm/v/@hlang-org/editor-core?color=c8ccd4&labelColor=0f1114)](https://www.npmjs.com/package/@hlang-org/editor-core) [![license](https://img.shields.io/npm/l/@hlang-org/editor-core?color=c8ccd4&labelColor=0f1114)](https://github.com/hlang-tech/hlang/blob/main/LICENSE)

> **状态:** 0.X，在积极发展中。API可以在任何小版本中更改。

## 安装

```sh
npm install @hlang-org/editor-core
```

相同的构建发布为 `@hlang-tech/editor-core`。ESM和CommonJS的构建带有类型声明。

## 使用

```ts
import { createEditorCore, AddNodeCommand, ConnectCommand } from '@hlang-org/editor-core';
import type { NodeDescriptor } from '@hlang-org/editor-core';

const DTO = { name: 'DTO', kind: 'interface' } as const;
const numbers: NodeDescriptor = {
  code: 'numbers',
  kind: 'R',
  displayName: 'Numbers',
  group: 'sources',
  ports: [
    { id: 'out', direction: 'O', name: 'out', dataType: DTO, isError: false },
    { id: '@node/error', direction: 'O', name: 'error', dataType: DTO, isError: true },
  ],
  defaultParams: { count: 3 },
  runtimeResource: 'my-nodes/numbers',
};

const core = createEditorCore();
core.registry.register(numbers);

const node = core.registry.createNode('numbers', { x: 0, y: 0 });
core.commands.execute(new AddNodeCommand(node));
core.history.undo();
core.history.redo();

const graph = core.serialization.toIGraph(core.model); // IGraph
```

### 运行图形

传递一个图形运行器以启用执行。 `InterpreterGraphRunner` 使用 [`@hlang-org/interpreter`](https://www.npmjs.com/package/@hlang-org/interpreter)：

```ts
import { Flow } from '@hlang-org/runtime';
import { NodeRegistry } from '@hlang-org/interpreter';
import { createEditorCore, InterpreterGraphRunner } from '@hlang-org/editor-core';

const runtimeNodes = new NodeRegistry().register('numbers', Numbers);
const core = createEditorCore({ graphRunner: new InterpreterGraphRunner(runtimeNodes, () => new Flow()) });

const handle = core.execution?.run(core.model);
handle?.dispose();
```

## 编辑核心

`createEditorCore(options?)` 返回一个 `EditorCore` 有了这些服务：

| 成员 | 责任 |
| --- | --- |
| `model` | 正在编辑的图：节点，边，位置，参数。 |
| `commands` | 改变模式的唯一方法。 `execute(command)` 验证、应用并记录命令。 |
| `history` | `undo()`， `redo()`， `canUndo()`， `canRedo()`, `transact(label, fn)` 将命令分组到一个步骤中。 |
| `selection` | 选定的节点和边。不是序列化。 |
| `viewState` | 每个节点的隐藏和锁定标志。不是序列化。 |
| `registry` | 节点描述符(`code`，类型，端口，默认参数)和 `createNode`. |
| `validator` | 连接规则：输出到输入，无自连接，无重复，兼容端口类型。允许转换周期。 |
| `diagnostics` | 编辑时的问题，在更改时重新计算。 |
| `serialization` | `toIGraph(model)` 和 `fromIGraph(graph)`. |
| `events` | 类型化事件总线： `nodeAdded`， `nodeRemoved`， `nodeChanged`， `edgeAdded`， `edgeRemoved`， `selectionChanged`， `viewStateChanged`， `historyChanged`. |
| `execution` | 出现时 `graphRunner` 供应。 |

选项: `idGenerator` （确定性id，用于测试）和 `graphRunner`.

### 命令

`AddNodeCommand`， `RemoveNodeCommand` （也删除和恢复相关边）， `ConnectCommand`， `DisconnectCommand`， `MoveNodeCommand`， `UpdateParamsCommand`， `RenameNodeCommand`， `SetHiddenCommand`， `SetLockedCommand`． 每个命令都有一个逆命令，因此每个编辑都可以撤消。被拒绝的命令返回 `{ ok: false, error }` 并且没有记录。

### 诊断

| 代码 | 严重程度 | 意义 |
| --- | --- | --- |
| `bad-connection` | 错误 | 一条边打破了一条连接规则。 |
| `no-source-root` | 错误 | 图有节点，但没有可读节点运行。 |
| `unregistered-code` | 错误 | 一个节点的 `code` 不在注册表中。 |
| `type-mismatch` | 警告 | 边缘连接不兼容的端口类型。 |
| `dead-source` | 警告 | 可读输出不提供任何内容。 |
| `dangling-input` | 警告 | 没有连接Transform输入。 |
| `sink-no-upstream` | 警告 | 未连接可写输入。 |

### 公用事业公司

-   `cloneNodesWithEdges` 复制选区及其内部边缘，用于复制和粘贴。
-   `planInsertOnEdge` 和 `distanceToSegment` 支持将节点放到边缘上。
-   `GraphTopology`， `TopologyIndex`， `layoutLayered`, `layoutGrouped` 分析连接组件并计算分层布局。

### 依赖注入

服务是通过一个小的依赖注入容器解析的，采用VS Code (`createDecorator`， `ServiceCollection`， `InstantiationService`）. 它没有运行时依赖项，也不需要 `reflect-metadata`。使用它来替换自定义容器中的服务。

## 相关的包

-   [`@hlang-org/editor-react`](https://www.npmjs.com/package/@hlang-org/editor-react)：这个核心的React Flow绑定。
-   [`@hlang-org/editor-ui`](https://www.npmjs.com/package/@hlang-org/editor-ui)：流明设计系统。

来源和文件： [github.com/hlang-tech/hlang](https://github.com/hlang-tech/hlang).

## 许可证

麻省理工学院

## 常见问题

### @hlang-org/editor-core 是什么？

Lumen编辑器的无头核心：图形模型、可逆命令、验证、诊断和IGraph序列化。没有React，就没有DOM。

### 如何安装 @hlang-org/editor-core？

在项目目录运行 npm install @hlang-org/editor-core，或使用 pnpm add / yarn add / bun add。

### @hlang-org/editor-core 支持 TypeScript 吗？

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

### @hlang-org/editor-core 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @hlang-org/editor-core 需要什么版本的 Node\.js？

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

### @hlang-org/editor-core 可以商用吗？

@hlang-org/editor-core 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @hlang-org/editor-core 还在维护吗？

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