# @gravity-ui/graph 中文文档

规范地址：https://npmcn.com/package/%40gravity-ui/graph/

版本：1\.13\.1
npm 元数据更新时间：2026-11-06T11:16:24.980Z
中文译文更新时间：2026-11-16T23:52:20.968Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gravity-ui/graph
原文对照：https://npmcn.com/package/%40gravity-ui/graph/?lang=original
项目主页：https://github.com/gravity-ui/graph#readme
源码仓库：https://github.com/gravity-ui/graph

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

- 包体积（解压后）：1.4 MB，355 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react ^17\.0\.0 \|\| ^18\.0\.0，react-dom ^17\.0\.0 \|\| ^18\.0\.0
- 首次发布：2024-08-28T14:53:47.503Z
- 最新版本发布：2026-11-06T11:16:24.721Z
- 近 30 天下载量：23567（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：71（近 12 个月 34 个）

## 中文简介

现代图编辑器组件

## 安装

```sh
npm install @gravity-ui/graph
```

也可以使用：`pnpm add @gravity-ui/graph`、`yarn add @gravity-ui/graph`、`bun add @gravity-ui/graph`

## README

# @gravity-ui/graph ## 页面存档备份,存于互联网档案馆 [![npm package](https://img.shields.io/npm/v/@gravity-ui/graph)](https://www.npmjs.com/package/@gravity-ui/graph) [![Release](https://img.shields.io/github/actions/workflow/status/gravity-ui/graph/release.yml?branch=main&label=Release)](https://github.com/gravity-ui/graph/actions/workflows/release.yml?query=branch:main) [![storybook](https://img.shields.io/badge/Storybook-deployed-ff4685)](https://preview.gravity-ui.com/graph/)

> [0.x至1.x的迁移指南](https://npmcn.com/package/%40gravity-ui/graph/docs/migration-guides/v0-to-v1.md)

一个融合了两个世界中最好的图可视化库:

-   查看全图时显示高性能的相册
-   HTML/React 用于放大时丰富的交互

不能再在表现和互动之间做出选择了。 适合大型图表、流程图和节点编辑器.

![preview graph.](https://npmcn.com/package/%40gravity-ui/graph/docs/_static/graph_preview.png)

## 动机

现代的网络应用往往需要复杂的可视化和交互性,但现有的解决方案通常侧重于单一渲染技术:

-   **帆布** 为复杂图形提供高性能,但文本处理和互动有限.
-   **HTML 数据源** 对界面来说是方便的,但对复杂的图形或大量元素来说效率较低.

@ gravity-ui/ graph 通过基于缩放级别在 Canvas 和 HTML 之间自动切换来解决这个问题 :

-   **缩小**: 高效渲染全图的用相机
-   **中缩放**: 显示具有基本交互作用的示意图视图
-   **缩放**: 切换到 HTML/React 组件用于丰富的交互

## 如何运作

库使用智能渲染系统,自动管理Canvas和React组件之间的过渡:

1.  在低缩放水平上,所有东西都用 Canvas 来表现
2.  当放大到详细视图时 `GraphCanvas` 组件 :
    -   跟踪相机视图和比例变化
    -   计算在当前视图端口可见的块( 带有平滑滚动的粘贴)
    -   仅针对可见块重现组件
    -   滚动或缩放时自动更新列表
    -   缩放时删除反射组件

```typescript
// Example of React components rendering
const MyGraph = () => {
  return (
    <GraphCanvas
      graph={graph}
      renderBlock={(graph, block) => (
        <MyCustomBlockComponent
          graph={graph}
          block={block}
        />
      )}
    />
  );
};
```

[故事书](https://preview.gravity-ui.com/graph/)

## 安装

```bash
npm install @gravity-ui/graph
```

## 使用量

### 反应示例

[详细反应组件文档](https://npmcn.com/package/%40gravity-ui/graph/docs/react/usage.md)

```typescript
import React, { useEffect } from "react";
import type { Graph, TBlock } from "@gravity-ui/graph";
import { EAnchorType, GraphState } from "@gravity-ui/graph";
import { GraphCanvas, GraphBlock, useGraph } from "@gravity-ui/graph/react";

const config = {};

export function GraphEditor() {
  const { graph, setEntities, start } = useGraph(config);

  useEffect(() => {
    setEntities({
      blocks: [
        {
          is: "block-action",
          id: "action_1",
          x: -100,
          y: -450,
          width: 126,
          height: 126,
          selected: true,
          name: "Block #1",
          anchors: [
            {
              id: "out1",
              blockId: "action_1",
              type: EAnchorType.OUT,
              index: 0,
            },
          ],
        },
        {
          id: "action_2",
          is: "block-action",
          x: 253,
          y: 176,
          width: 126,
          height: 126,
          selected: false,
          name: "Block #2",
          anchors: [
            {
              id: "in1",
              blockId: "action_2",
              type: EAnchorType.IN,
              index: 0,
            },
          ],
        },
      ],
      connections: [
        {
          sourceBlockId: "action_1",
          sourceAnchorId: "out1",
          targetBlockId: "action_2",
          targetAnchorId: "in1",
        },
      ],
    });
  }, [setEntities]);

  const renderBlockFn = (graph: Graph, block: TBlock) => {
    return (
      <GraphBlock graph={graph} block={block}>
        {block.id}
      </GraphBlock>
    );
  };

  return (
    <GraphCanvas
      graph={graph}
      renderBlock={renderBlockFn}
      onStateChanged={({ state }) => {
        if (state === GraphState.ATTACHED) {
          start();
          graph.zoomTo("center", { padding: 300 });
        }
      }}
    />
  );
}

```

### 香草 Java 脚本示例

```javascript
import { Graph } from "@gravity-ui/graph";

// Create container element
const container = document.createElement('div');
container.style.width = '100vw';
container.style.height = '100vh';
container.style.overflow = 'hidden';
document.body.appendChild(container);

// Initialize graph with configuration
const graph = new Graph({
    configurationName: "example",
    blocks: [],
    connections: [],
    settings: {
        canDragCamera: true,
        canZoomCamera: true,
        useBezierConnections: true,
        showConnectionArrows: true
    }
}, container);

// Add blocks and connections
graph.setEntities({
    blocks: [
        {
            is: "block-action",
            id: "block1",
            x: 100,
            y: 100,
            width: 120,
            height: 120,
            name: "Block #1",
            anchors: [
                {
                    id: "out1",
                    blockId: "block1",
                    type: EAnchorType.OUT,
                    index: 0
                }
            ]
        },
        {
            is: "block-action",
            id: "block2",
            x: 300,
            y: 300,
            width: 120,
            height: 120,
            name: "Block #2",
            anchors: [
                {
                    id: "in1",
                    blockId: "block2",
                    type: EAnchorType.IN,
                    index: 0
                }
            ]
        }
    ],
    connections: [
        {
            sourceBlockId: "block1",
            sourceAnchorId: "out1",
            targetBlockId: "block2",
            targetAnchorId: "in1"
        }
    ]
});

// Start rendering
graph.start();

// Center the view
graph.zoomTo("center", { padding: 100 });
```

## 现场实例

-   [基本实例](https://preview.gravity-ui.com/graph/?path=/story/stories-main-grapheditor--hundred-blocks)
-   [大型实例](https://preview.gravity-ui.com/graph/?path=/story/stories-main-grapheditor--five-thousands-blocks)
-   [自定义块视图](https://preview.gravity-ui.com/graph/?path=/story/stories-main-grapheditor--custom-schematic-block)
-   [贝塞尔连接](https://preview.gravity-ui.com/graph/?path=/story/stories-main-grapheditor--one-bezier-connection)
-   [连接定制](https://preview.gravity-ui.com/graph/?path=/story/api-updateconnection--default)

## 文档

### 目录

1.  系统
    
    -   [组成部分生命周期](https://npmcn.com/package/%40gravity-ui/graph/docs/system/component-lifecycle.md)
    -   [活动](https://npmcn.com/package/%40gravity-ui/graph/docs/system/events.md)
    -   [图表设置](https://npmcn.com/package/%40gravity-ui/graph/docs/system/graph-settings.md)
    -   [公共 API](https://npmcn.com/package/%40gravity-ui/graph/docs/system/public_api.md)
    -   [调度系统](https://npmcn.com/package/%40gravity-ui/graph/docs/system/scheduler-system.md)
2.  构成部分
    
    -   [Canvas 图形组件](https://npmcn.com/package/%40gravity-ui/graph/docs/components/canvas-graph-component.md)
    -   [块组件](https://npmcn.com/package/%40gravity-ui/graph/docs/components/block-component.md)
    -   [锁定](https://npmcn.com/package/%40gravity-ui/graph/docs/components/anchors.md)
3.  渲染
    
    -   [招标机制](https://npmcn.com/package/%40gravity-ui/graph/docs/rendering/rendering-mechanism.md)
    -   [层](https://npmcn.com/package/%40gravity-ui/graph/docs/rendering/layers.md)
4.  块和连接
    
    -   [块组](https://npmcn.com/package/%40gravity-ui/graph/docs/blocks/groups.md)
    -   [Canvas 连接系统](https://npmcn.com/package/%40gravity-ui/graph/docs/connections/canvas-connection-system.md)
5.  测试
    
    -   [剧作家页面对象](https://npmcn.com/package/%40gravity-ui/graph/docs/testing/playwright.md)

## 许可证

根据麻省理工学院的许可证分发。 见 [自由主义](https://npmcn.com/package/%40gravity-ui/graph/LICENSE) 详细情况.

## 对于人工智能特工

一个基于节点的图的混合Canvas/React图编辑器——它可以达到建立流程图,节点编辑器,或者大型交互式图,Canvas在低缩放时给出性能,而React组件在缩放时给出丰富的交互性.

### 何时使用

-   以节点为主的编辑器(流程图,管线,视觉构建器),有上百/千个节点和连接.
-   混合渲染:用于全图概览的 Canvas,用于高缩放时在取景口所可见的块的回放组件.
-   香草JS或反应消费者——核心 `Graph` 类为框架不可知; `@gravity-ui/graph/react` 提供反应约束.

### 不使用时

-   绘制数字数据序列(行/条/散图),使用 [`@gravity-ui/charts`](https://gravity-ui.com/charts) 或者说 [`@gravity-ui/yagr`](https://github.com/gravity-ui/yagr) ——图是节点/尖端图编辑器,不是数据图表.
-   对于一个静态,非可编辑且节点不多的图,如果没有Canvas/React Viewport机器,SVG或更简单的图 lib可能就足够了.

### 常见陷阱

-   **迷幻导入 `GraphEditor`** 反应组件是 `GraphCanvas`, (中文(简体) ), `GraphBlock`,则 `useGraph` 钩子,从 `@gravity-ui/graph/react`;核心类是 `Graph` 从 `@gravity-ui/graph`。 。 。 .
-   **调用图形方法 `ATTACHED` 状态** - 打电话 `start()`编号 :`zoomTo(...)` 内部 `onStateChanged` 回调时 `state === GraphState.ATTACHED`而不是上马.
-   **忘记 `setEntities`** —— 说 `useGraph` 返回时 `graph`, (中文(简体) ), `setEntities`, (中文(简体) ), `start`; 数据仅出现在后面 `setEntities({blocks, connections})`。 。 。 .
-   **混合锚类型** – 连接必须使用匹配来引用已存在的锚标识 `EAnchorType` (单位:千美元)`IN`编号 :`OUT`在源头和目标块.

## AI代理的文件

安装版本的可代理读取文档位于 `node_modules/@gravity-ui/graph/build/docs/INDEX.md`。 。 。 .

## 常见问题

### @gravity-ui/graph 是什么？

现代图编辑器组件

### 如何安装 @gravity-ui/graph？

在项目目录运行 npm install @gravity-ui/graph，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^17\.0\.0 \|\| ^18\.0\.0）、react-dom（^17\.0\.0 \|\| ^18\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gravity-ui/graph 支持 TypeScript 吗？

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

### @gravity-ui/graph 支持 ESM 还是 CommonJS？

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

### @gravity-ui/graph 可以商用吗？

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

### @gravity-ui/graph 的下载量有多少？

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

### @gravity-ui/graph 还在维护吗？

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

