one
d05d1309ca
* refactor(CodeBlockView): generalize tool and preview Generalize code tool to action tool - CodeTool -> ActionTool - usePreviewTools -> useImagePreview - rename code tool classname from icon to tool-icon Generalize preview - move image preview components to Preview dir - simplify file names * refactor(useImageTools): simplify implementation, add pan * refactor(Preview): move image tools to floating toolbar * refactor: add enableDrag, enable zooming for SvgPreview * test: add tests for preview components * feat(Preview): add download buttons to dropdown * refactor(Preview): remove setTools from preview, improve SvgPreview * refactor: add useTemporaryValue * test: add tests for hooks * test: add tests for CodeToolButton and CodeToolbar * refactor(PreviewTool): add a setting item to enable preview tools * test: update snapshot * refactor: extract more code tools to hooks, add tests * refactor: extract tools from CodeEditor and CodeViewer * test: add tests for new tool hooks * refactor(CodeEditor): change collapsible to expanded, change wrappable to unwrapped * refactor: migrate codePreview to codeViewer * docs: CodeBlockView * refactor: add custom file icons, center the reset button * refactor: improve code quality * refactor: improve migration by deprecating codePreview * refactor: improve PlantUml and svgToCanvas * fix: plantuml style * test: fix tests * fix: button icon * refactor(SvgPreview): debounce rendering * feat(PreviewTool): add a dialog tool * fix: remove isValidPlantUML, improve plantuml rendering * refactor: extract shadow dom renderer * refactor: improve plantuml error messages * test: add tests for ImageToolbar and ImageToolButton * refactor: add ImagePreviewLayout to simplify layout and tests * refactor: add useDebouncedRender, update docs * chore: clean up unused props * refactor: clean transformation before copy/download/preview * refactor: update migrate version * refactor: style refactoring and fixes - show header background in split view - fix status bar radius - reset special view transformation on theme change - fix wrap tool icon - add a divider to split view - improve split view toggling (switch back to previous view) - revert copy tool to separate tools - fix top border radius for special views * refactor: move GraphvizPreview to shadow DOM - use renderString - keep renderSvgInShadowHost api consistent with others * fix: tests, icons, deleted files * refactor: use ResetIcon in ImageToolbar * test: remove unnecessary tests * fix: min height for special preview * fix: update migrate
196 lines
4.7 KiB
Markdown
196 lines
4.7 KiB
Markdown
# 图像预览组件
|
|
|
|
## 概述
|
|
|
|
图像预览组件是 Cherry Studio 中用于渲染和显示各种图表和图像格式的专用组件集合。它们为不同预览类型提供一致的用户体验，具有共享的加载状态、错误处理和交互控制功能。
|
|
|
|
## 支持格式
|
|
|
|
- **Mermaid**: 交互式图表和流程图
|
|
- **PlantUML**: UML 图表和系统架构
|
|
- **SVG**: 可缩放矢量图形
|
|
- **Graphviz/DOT**: 图形可视化和网络图表
|
|
|
|
## 架构
|
|
|
|
```mermaid
|
|
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:**
|
|
|
|
```typescript
|
|
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 文档](./CodeBlockView-zh.md)。
|