integrate-file-viewer

用途

本技能用于在 Dune 应用中集成 CogniteFileViewer 组件，以便预览 CDF（Cognite Data Fusion）中的文件，包括 PDF、图片、文本以及 Office 文档。它替代了手动接入 react-pdf 或自行搭建文件预览逻辑的做法。

主要能力

CogniteFileViewer 支持以下文件类型：

PDF：.pdf，支持翻页、缩放、平移、图表标注叠加。
Office 文档：Word、PowerPoint、Excel、ODS、ODP、ODT、RTF、TSV，通过 CDF Document Preview API 转换为 PDF 后按 PDF 方式渲染。
图片：JPEG、PNG、WebP、SVG、TIFF，支持缩放、平移、旋转。
文本：.txt、.csv、.json，以预格式化文本渲染。
其他类型：回退到 renderUnsupported。

组件内置缩放、平移和触摸手势处理。支持受控的分页（page、onPageChange、onDocumentLoad）、缩放（zoom、onZoomChange、minZoom、maxZoom）、平移（panOffset、onPanChange）、适配模式（fitMode：'width' 或 'page'）、旋转（rotation：0/90/180/270）。图表标注功能仅对 instanceId 来源启用，支持 showAnnotations、onAnnotationClick、onAnnotationHover 以及自定义提示 renderAnnotationTooltip。还支持自定义叠加层 renderOverlay（可用于 SVG 路径、高亮、绘图），以及自定义加载、错误和不支持类型的渲染器。

使用方式

集成需按顺序完成以下步骤：

了解应用：阅读 package.json（检测包管理器与现有依赖）、vite.config.ts（了解 Vite 配置）以及要添加查看器的组件文件。
安装依赖：
- pnpm：pnpm add "github:cognitedata/dune-industrial-components#semver:*" react-pdf
- npm：npm install "github:cognitedata/dune-industrial-components#semver:*" react-pdf
- yarn：yarn add "github:cognitedata/dune-industrial-components#semver:*" react-pdf pdfjs-dist 作为 react-pdf 的依赖会以正确版本一并安装，不要单独安装。
配置 PDF.js worker：在使用 CogniteFileViewer 的同一文件中添加：
```
import { pdfjs } from 'react-pdf';
pdfjs.GlobalWorkerOptions.workerSrc = new URL(
  'pdfjs-dist/build/pdf.worker.min.mjs',
  import.meta.url,
).toString();
```
pnpm 用户：pnpm 的严格链接可能导致浏览器无法解析 pdfjs-dist，可将 pdfjs-dist 添加为直接依赖（pnpm add pdfjs-dist），或在 .npmrc 中添加 public-hoist-pattern[]=pdfjs-dist。
配置 Vite：在 vite.config.ts 中添加 optimizeDeps.exclude: ['pdfjs-dist']，防止 Vite 预打包 pdfjs-dist 而破坏 worker。

使用组件：

import { CogniteFileViewer } from '@cognite/dune-industrial-components/file-viewer';
import { useDune } from '@cognite/dune';
const { sdk } = useDune();

最小用法：

<CogniteFileViewer
  source={{ type: 'internalId', id: file.id }}
  client={sdk}
  style={{ width: '100%', height: '600px' }}
/>

组件需要明确的高度，否则会塌缩为零。

文件来源支持三种类型：instanceId（数据建模文件，可启用标注）、internalId（CDF 内部 ID）、url（直接 URL）。优先使用 instanceId，因为它是唯一能启用图表标注叠加的来源类型。通过 sdk.files.list() 列出文件时，先检查 file.instanceId。

适用场景

适用于需要在 Dune 应用中展示 CDF 文件预览的场景，尤其是需要查看 PDF、图片、文本或 Office 文档，并可能需要图表标注交互（如 P&ID 图）的工业应用。

限制与注意事项

组件需要明确高度，否则会塌缩为零。
切换文件时组件不会自动重置页码、缩放和旋转，需自行处理。
onDocumentLoad 仅对 PDF 触发，分页 UI 应在 numPages > 0 时渲染。
标注仅对 instanceId 来源且文件在 CDF 中有 CogniteDiagramAnnotation 边时显示。
不要单独安装 pdfjs-dist，以免版本不匹配。
桌面端平移为中键拖拽，左键保留给标注点击和文本选择。
Ctrl/Cmd + 滚轮缩放、双指捏合缩放和双指拖拽平移均内置，无需配置。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项