@gravity-ui/graph

中文文档
1.13.1发布于 2026/11/06MITTypeScriptESM + CJS近 30 天下载 2.4万

现代图编辑器组件

中文使用文档
文档目录15 节
  1. 动机
  2. 如何运作
  3. 安装
  4. 使用量
  5. 反应示例
  6. 香草 Java 脚本示例
  7. 现场实例
  8. 文档
  9. 目录
  10. 许可证
  11. 对于人工智能特工
  12. 何时使用
  13. 不使用时
  14. 常见陷阱
  15. AI代理的文件

@gravity-ui/graph ## 页面存档备份,存于互联网档案馆 npm package Release storybook

0.x至1.x的迁移指南

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

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

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

preview graph.

动机

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

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

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

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

如何运作

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

  1. 在低缩放水平上,所有东西都用 Canvas 来表现
  2. 当放大到详细视图时 GraphCanvas 组件 :
    • 跟踪相机视图和比例变化
    • 计算在当前视图端口可见的块( 带有平滑滚动的粘贴)
    • 仅针对可见块重现组件
    • 滚动或缩放时自动更新列表
    • 缩放时删除反射组件
// Example of React components rendering
const MyGraph = () => {
  return (
    <GraphCanvas
      graph={graph}
      renderBlock={(graph, block) => (
        <MyCustomBlockComponent
          graph={graph}
          block={block}
        />
      )}
    />
  );
};

故事书

安装

npm install @gravity-ui/graph

使用量

反应示例

详细反应组件文档

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 脚本示例

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 });

现场实例

文档

目录

  1. 系统

  2. 构成部分

  3. 渲染

  4. 块和连接

  5. 测试

许可证

根据麻省理工学院的许可证分发。 见 自由主义 详细情况.

对于人工智能特工

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

何时使用

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

不使用时

  • 绘制数字数据序列(行/条/散图),使用 @gravity-ui/charts 或者说 @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 共发布 71 个版本,首次发布于 2024/08/28;过去 12 个月发布了 34 个版本。

版本发布日期距今
1.13.1latest2026/11/0610 天前
1.13.02026/11/0314 天前
1.12.22026/10/021 个月前
1.12.12026/09/231 个月前
1.12.02026/09/211 个月前
1.11.32026/07/164 个月前

关于 @gravity-ui/graph 的常见问题

@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 和提交记录判断。