cherry-studio/docs/zh/references/components/image-preview.md

图像预览组件

概述

图像预览组件是 Cherry Studio 中用于渲染和显示各种图表和图像格式的专用组件集合。它们为不同预览类型提供一致的用户体验，具有共享的加载状态、错误处理和交互控制功能。

支持格式

• Mermaid: 交互式图表和流程图
• PlantUML: UML 图表和系统架构
• SVG: 可缩放矢量图形
• Graphviz/DOT: 图形可视化和网络图表

架构

graph TD
    A[MermaidPreview] --> D[ImagePreviewLayout]
    B[PlantUmlPreview] --> D
    C[SvgPreview] --> D
    E[GraphvizPreview] --> D

    D --> F[ImageToolbar]
    D --> G[useDebouncedRender]

    F --> H[平移控制]
    F --> I[缩放控制]
    F --> J[重置功能]
    F --> K[对话框控制]

    G --> L[防抖渲染]
    G --> M[错误处理]
    G --> N[加载状态]
    G --> O[依赖管理]

核心组件

ImagePreviewLayout 图像预览布局

为所有图像预览组件提供基础的通用布局包装器。

功能特性:

• 加载状态管理: 在渲染期间显示加载动画
• 错误显示: 渲染失败时显示错误信息
• 工具栏集成: 启用时有条件地渲染 ImageToolbar
• 容器管理: 使用一致的样式包装预览内容
• 响应式设计: 适应不同的容器尺寸

属性:

• children: 要显示的预览内容
• loading: 指示内容是否正在渲染的布尔值
• error: 渲染失败时显示的错误信息
• enableToolbar: 是否显示交互式工具栏
• imageRef: 用于图像操作的容器元素引用

ImageToolbar 图像工具栏

提供图像操作控制的交互式工具栏组件。

功能特性:

• 平移控制: 4方向平移按钮（上、下、左、右）
• 缩放控制: 放大/缩小功能，支持可配置的增量
• 重置功能: 恢复原始平移和缩放状态
• 对话框控制: 在展开对话框中打开预览
• 无障碍设计: 完整的键盘导航和屏幕阅读器支持

布局:

• 3x3 网格布局，位于预览右下角
• 响应式按钮尺寸
• 所有控件的工具提示支持

useDebouncedRender Hook 防抖渲染钩子

用于管理预览渲染的专用 React Hook，具有性能优化功能。

功能特性:

• 防抖渲染: 防止内容快速变化时的过度重新渲染（默认 300ms 延迟）
• 自动依赖管理: 处理渲染和条件函数的依赖项
• 错误处理: 捕获和管理渲染错误，提供详细的错误信息
• 加载状态: 跟踪渲染进度并自动更新状态
• 条件渲染: 支持预渲染条件检查
• 手动控制: 提供触发、取消和状态管理功能

API:

const { containerRef, error, isLoading, triggerRender, cancelRender, clearError, setLoading } = useDebouncedRender(
  value,
  renderFunction,
  options
)

选项:

• debounceDelay: 自定义防抖时间
• shouldRender: 条件渲染逻辑函数

组件实现

MermaidPreview Mermaid 预览

渲染 Mermaid 图表，具有可见性检测的特殊处理。

特殊功能:

• 渲染前语法验证
• 可见性检测以处理折叠的容器
• 边缘情况的 SVG 坐标修复
• 与 mermaid.js 库集成

PlantUmlPreview PlantUML 预览

使用在线 PlantUML 服务器渲染 PlantUML 图表。

特殊功能:

• 网络错误处理和重试逻辑
• 使用 deflate 压缩的图表编码
• 支持明/暗主题
• 服务器状态监控

SvgPreview SVG 预览

使用 Shadow DOM 隔离渲染 SVG 内容。

特殊功能:

• Shadow DOM 渲染实现样式隔离
• 直接 SVG 内容注入
• 最小化处理开销
• 跨浏览器兼容性

GraphvizPreview Graphviz 预览

使用 viz.js 库渲染 Graphviz/DOT 图表。

特殊功能:

• 使用 viz.js 进行客户端渲染
• viz.js 库的懒加载
• SVG 元素生成
• 内存高效处理

共享功能

错误处理

所有预览组件提供一致的错误处理：

• 网络错误（连接失败）
• 语法错误（无效的图表代码）
• 服务器错误（外部服务失败）
• 渲染错误（库失败）

加载状态

所有组件的标准化加载指示器：

• 处理期间的动画
• 长时间操作的进度反馈
• 状态间的平滑过渡

交互控制

通用交互模式：

• 平移和缩放功能
• 重置到原始视图
• 全屏对话框模式
• 键盘无障碍访问

性能优化

• 防抖渲染以防止过度更新
• 重型库的懒加载
• 大型图表的内存管理
• 高效的重新渲染策略

与 CodeBlockView 的集成

图像预览组件与 CodeBlockView 无缝集成：

• 基于语言标签的自动格式检测
• 一致的工具栏集成
• 共享状态管理
• 响应式布局适应

有关整体 CodeBlockView 架构的更多信息，请参阅 CodeBlockView 文档。