bb41709ce8
- 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.
181 lines
4.6 KiB
Markdown
181 lines
4.6 KiB
Markdown
# 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
|
|
|
|
```mermaid
|
|
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](./image-preview.md).
|
|
|
|
#### StatusBar
|
|
|
|
- Displays Python code execution results
|
|
- Can show both text and image results
|
|
|
|
## Tool System
|
|
|
|
CodeBlockView uses a hook-based tool system:
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```mermaid
|
|
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.
|