Files

fullex bb41709ce8 docs: update docs directory structure

- Updated links in CONTRIBUTING.md and README.md to point to the correct Chinese documentation paths.
- Removed outdated files including the English and Chinese versions of the branching strategy, contributing guide, and test plan documents.
- Cleaned up references to non-existent documentation in the project structure to streamline the contributor experience.

2025-11-26 13:17:01 +08:00

4.4 KiB

Raw Permalink Blame History

CodeBlockView 组件结构说明

概述

CodeBlockView 是 Cherry Studio 中用于显示和操作代码块的核心组件。它支持多种视图模式和特殊语言的可视化预览，提供丰富的交互工具。

组件结构

graph TD
    A[CodeBlockView] --> B[CodeToolbar]
    A --> C[SourceView]
    A --> D[SpecialView]
    A --> E[StatusBar]

    B --> F[CodeToolButton]

    C --> G[CodeEditor / CodeViewer]

    D --> H[MermaidPreview]
    D --> I[PlantUmlPreview]
    D --> J[SvgPreview]
    D --> K[GraphvizPreview]

    F --> L[useCopyTool]
    F --> M[useDownloadTool]
    F --> N[useViewSourceTool]
    F --> O[useSplitViewTool]
    F --> P[useRunTool]
    F --> Q[useExpandTool]
    F --> R[useWrapTool]
    F --> S[useSaveTool]

核心概念

视图类型

preview: 预览视图，非源代码的是特殊视图
edit: 编辑视图

视图模式

source: 源代码视图模式
special: 特殊视图模式（Mermaid、PlantUML、SVG）
split: 分屏模式（源代码和特殊视图并排显示）

特殊视图语言

mermaid
plantuml
svg
dot
graphviz

组件详细说明

CodeBlockView 主组件

主要负责：

管理视图模式状态
协调源代码视图和特殊视图的显示
管理工具栏工具
处理代码执行状态

子组件

CodeToolbar 工具栏

显示在代码块右上角的工具栏
包含核心(core)和快捷(quick)两类工具
根据上下文动态显示相关工具

CodeEditor/CodeViewer 源代码视图

可编辑的代码编辑器或只读的代码查看器
根据设置决定使用哪个组件
支持多种编程语言高亮

特殊视图组件

MermaidPreview: Mermaid 图表预览
PlantUmlPreview: PlantUML 图表预览
SvgPreview: SVG 图像预览
GraphvizPreview: Graphviz 图表预览

所有特殊视图组件共享通用架构，以确保一致的用户体验和功能。有关这些组件及其实现的详细信息，请参阅图像预览组件文档。

StatusBar 状态栏

显示 Python 代码执行结果
可显示文本和图像结果

工具系统

CodeBlockView 使用基于 hooks 的工具系统：

graph TD
    A[CodeBlockView] --> B[useCopyTool]
    A --> C[useDownloadTool]
    A --> D[useViewSourceTool]
    A --> E[useSplitViewTool]
    A --> F[useRunTool]
    A --> G[useExpandTool]
    A --> H[useWrapTool]
    A --> I[useSaveTool]

    B --> J[ToolManager]
    C --> J
    D --> J
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J

    J --> K[CodeToolbar]

每个工具 hook 负责注册特定功能的工具按钮到工具管理器，工具管理器再将这些工具传递给 CodeToolbar 组件进行渲染。

工具类型

core: 核心工具，始终显示在工具栏
quick: 快捷工具，当数量大于1时通过下拉菜单显示

工具列表

复制(copy): 复制代码或图像
下载(download): 下载代码或图像
查看源码(view-source): 在特殊视图和源码视图间切换
分屏(split-view): 切换分屏模式
运行(run): 运行 Python 代码
展开/折叠(expand): 控制代码块的展开/折叠
换行(wrap): 控制代码的自动换行
保存(save): 保存编辑的代码

状态管理

CodeBlockView 通过 React hooks 管理以下状态：

viewMode: 当前视图模式 ('source' | 'special' | 'split')
isRunning: Python 代码执行状态
executionResult: Python 代码执行结果
tools: 工具栏工具列表
expandOverride/unwrapOverride: 用户展开/换行的覆盖设置
sourceScrollHeight: 源代码视图滚动高度

交互流程

sequenceDiagram
    participant U as User
    participant CB as CodeBlockView
    participant CT as CodeToolbar
    participant SV as SpecialView
    participant SE as SourceEditor

    U->>CB: 查看代码块
    CB->>CB: 初始化状态
    CB->>CT: 注册工具
    CB->>SV: 渲染特殊视图(如果适用)
    CB->>SE: 渲染源码视图
    U->>CT: 点击工具按钮
    CT->>CB: 触发工具回调
    CB->>CB: 更新状态
    CB->>CT: 重新注册工具(如果需要)

特殊处理

HTML 代码块

HTML 代码块会被特殊处理，使用 HtmlArtifactsCard 组件显示。

Python 代码执行

支持执行 Python 代码并显示结果，使用 Pyodide 在浏览器中运行 Python 代码。

4.4 KiB Raw Permalink Blame History Unescape Escape