graph-viewer

图查看器

适用场景

用户希望在 Dune 应用中嵌入 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	Suggested version	Purpose
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 的引用。