cherry-studio/docs/technical/CodeBlockView-en.md

CodeBlockView Component Structure

Overview

CodeBlockView is the core component in Cherry Studio for displaying and manipulating code blocks. It supports multiple view modes and visual previews for special languages, providing rich interactive tools.

Component Structure

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]

Core Concepts

View Types

• preview: Preview view, where non-source code is displayed as special views
• edit: Edit view

View Modes

• source: Source code view mode
• special: Special view mode (Mermaid, PlantUML, SVG)
• split: Split view mode (source code and special view displayed side by side)

Special View Languages

• mermaid
• plantuml
• svg
• dot
• graphviz

Component Details

CodeBlockView Main Component

Main responsibilities:

1. Managing view mode state
2. Coordinating the display of source code view and special view
3. Managing toolbar tools
4. Handling code execution state

Subcomponents

CodeToolbar

• Toolbar displayed at the top-right corner of the code block
• Contains core and quick tools
• Dynamically displays relevant tools based on context

CodeEditor/CodeViewer Source View

• Editable code editor or read-only code viewer
• Uses either component based on settings
• Supports syntax highlighting for multiple programming languages

Special View Components

• MermaidPreview: Mermaid diagram preview
• PlantUmlPreview: PlantUML diagram preview
• SvgPreview: SVG image preview
• GraphvizPreview: Graphviz diagram preview

All special view components share a common architecture for consistent user experience and functionality. For detailed information about these components and their implementation, see Image Preview Components Documentation.

StatusBar

• Displays Python code execution results
• Can show both text and image results

Tool System

CodeBlockView uses a hook-based tool system:

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]

Each tool hook is responsible for registering specific function tool buttons to the tool manager, which then passes these tools to the CodeToolbar component for rendering.

Tool Types

• core: Core tools, always displayed in the toolbar
• quick: Quick tools, displayed in a dropdown menu when there are more than one

Tool List

1. Copy: Copy code or image
2. Download: Download code or image
3. View Source: Switch between special view and source code view
4. Split View: Toggle split view mode
5. Run: Run Python code
6. Expand/Collapse: Control code block expansion/collapse
7. Wrap: Control automatic line wrapping
8. Save: Save edited code

State Management

CodeBlockView manages the following states through React hooks:

1. viewMode: Current view mode ('source' | 'special' | 'split')
2. isRunning: Python code execution status
3. executionResult: Python code execution result
4. tools: Toolbar tool list
5. expandOverride/unwrapOverride: User override settings for expand/wrap
6. sourceScrollHeight: Source code view scroll height

Interaction Flow

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

    U->>CB: View code block
    CB->>CB: Initialize state
    CB->>CT: Register tools
    CB->>SV: Render special view (if applicable)
    CB->>SE: Render source view
    U->>CT: Click tool button
    CT->>CB: Trigger tool callback
    CB->>CB: Update state
    CB->>CT: Re-register tools (if needed)

Special Handling

HTML Code Blocks

HTML code blocks are specially handled using the HtmlArtifactsCard component.

Python Code Execution

Supports executing Python code and displaying results using Pyodide to run Python code in the browser.