graph-viewer

图查看器

适用场景

用户希望在 Flows 应用中嵌入 CDF 数据模型的交互式图，其中包含节点、直接关系、边和反向关系。

静态图表、纯数据流可视化或非 CDF 图表不适用此技能。

前提条件

• 应用由 @cognite/dune 的 <DuneProvider> 包装，因此 useDune() 会返回经过身份验证的 SDK。
• 目标数据模型存在于 CDF 中，并且你知道其 space、externalId 和 version。
• 应用使用 React 18+ 和 TypeScript。

集成工作流

按顺序执行以下步骤。遵循目标仓库的惯例，不要自行另创模式。

1. 检查目标应用。 阅读 package.json，并查看现有文件夹结构（例如 src/features/*、src/components/*、@/* 等路径别名）。

2. 使用应用的包管理器（npm、pnpm、yarn 等）安装缺失的依赖项。有关用途和建议版本，请参阅下方的依赖项表。沿用应用已固定的 React 版本，不要升级；如果仓库已固定了其他版本，优先使用仓库中的版本，而非此处的建议版本。

3. 将代码包复制到应用中。 将 skills/graph-viewer/code/ 中的每个文件复制到应用本地的功能文件夹中，例如：

   src/features/graph-viewer/
   

   如果仓库采用了不同的功能/组件布局或别名，请参照其结构。

4. 从本地文件夹导入，不要从 @skills/... 导入。使用常见的 @/* 别名时：

   import { useGraphViewer } from "@/features/graph-viewer";
   

5. 在具有明确尺寸的容器中渲染 GraphCanvas（必须设置高度，见下方的最简示例）。

6. 运行类型检查和构建（tsc --noEmit、npm run build 等），并修复复制代码引入的路径或类型问题。

最简示例

import { useGraphViewer } from "@/features/graph-viewer";

export function GraphPanel() {
  const { GraphCanvas, isLoading, error } = useGraphViewer({
    dataModel: { space: "my-space", externalId: "my-data-model", version: "1" },
    instance: { space: "my-instance-space", externalId: "pump-001" },
  });

  if (isLoading) return <div>Loading graph…</div>;
  if (error) return <div>Error: {error}</div>;

  return <GraphCanvas className="h-[600px] w-full" />;
}

依赖项

建议版本反映了本文撰写时发布的最新主版本。它们仅供参考；如果目标应用已固定其他版本，请以应用中的版本为准。

Package	建议版本	用途
react	^18.2.0	UI 框架（同级依赖；沿用应用的版本）
@cognite/sdk	^10.10.0	CDF API 客户端（实例、数据模型）
@cognite/dune	^2.1.0	通过 useDune() 提供经过身份验证的 SDK
reagraph	^4.30.8	WebGL 图渲染引擎
lucide-react	^1.14.0	节点类型图例使用的图标集

安装示例（使用 npm；请根据应用的包管理器调整）：

npm install @cognite/sdk@^10.10.0 @cognite/dune@^2.1.0 reagraph@^4.30.8 lucide-react@^1.14.0

CDF 成本与性能

展开图可能会发起大量 CDF 请求，尤其是在处理反向关系时。对于较大或不熟悉的数据模型，请谨慎操作：

• 将 whitelistedRelationProps 设为应用实际需要遍历的少数几个属性。
• 降低 initialConnectionLimit（这是每次展开时获取连接数的硬性上限）。
• 降低 maxNodes，以限制内存中的 LRU 缓冲区。
• 仅为应用必须展示的关系声明 coreReverseQueries；每个条目都会在每次展开时增加一次查询。

coreReverseQueries 中的元组会考虑版本： [space, viewExternalId, viewVersion, propertyName, isList]。

高级参考

有关完整的配置表、返回值文档、布局、主题和更丰富的示例，请阅读 code/README.md。

有关实现细节，请检查 code/ 下的源文件。

验证清单

• 应用已由 <DuneProvider> 封装。
• 已将 skills/graph-viewer/code/ 中的所有文件复制到应用本地文件夹。
• 导入指向应用本地文件夹（例如 @/features/graph-viewer），而非 @skills/...。
• package.json 中包含 @cognite/dune、@cognite/sdk、reagraph 和 lucide-react。
• 渲染 <GraphCanvas> 的容器已显式设置高度。
• tsc --noEmit 和应用的构建均通过。
• 未引入任何对 dune-industrial-components 的引用。