docs: explain Tessera modules and execution flows in Chinese

2026-11-11 23:36:03 +08:00
parent 4c3fc8b5dd
commit 1fedd21d3c
77 changed files with 1418 additions and 0 deletions
@@ -1,3 +1,7 @@
+//! Console/Sources/Network/Settings 的宿主交互协调与绘制状态。
+//! 工具标签有独立焦点、滚动和文本选择状态；源程序与结果来自当前发布文档，提交动作通过本地 API 进入 worker。
+//! 输入法预编辑、光标、选择和控件捕获分别处理，避免把界面操作直接当成业务模型写入。
+//!
 //! Native developer workspace. Coordinates and scroll offsets are logical pixels.
 use crate::{
    activity::{Activity, Exchange},
@@ -32,6 +36,7 @@ use selection::SourceSelection;
 const ROW: f32 = 19.0;

 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
+/// 当前管理工具种类，决定使用 Console/Sources/Network/Settings 哪份状态。
 pub enum Tab {
    #[default]
    Console,
@@ -40,6 +45,7 @@ pub enum Tab {
    Settings,
 }
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+/// 管理面板中可区分的输入/列表/详情区域。
 pub enum Region {
    Transcript = 0,
    Tree,
@@ -48,11 +54,13 @@ pub enum Region {
    Details,
 }
 #[derive(Clone, Copy, Debug, Default)]
+/// 工具区域保留的滚动偏移与内容范围。
 struct Scroll {
    x: f32,
    y: f32,
 }
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+/// 当前工具内接受键盘输入的目标类别。
 pub enum Focus {
    Source,
    Input,
@@ -60,6 +68,7 @@ pub enum Focus {
    Custom,
 }
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
+/// 工具控件激活后执行的管理动作，避免在绘制时产生业务副作用。
 pub enum Action {
    ClearConsole,
    ClearNetwork,
@@ -75,11 +84,13 @@ pub enum Action {
    Theme(usize),
 }
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+/// 工具画面分隔布局的可调整方向/区域。
 pub enum Split {
    Tree,
    Network,
 }
 #[derive(Clone, Copy, Debug)]
+/// 正在捕获的工具拖动操作，移动时保持原目标。
 enum Drag {
    Split(Split),
    Scroll(Region, bool, f32),
@@ -87,11 +98,13 @@ enum Drag {

 /// Each workspace keeps its own input, focus, selection, scroll and request state.
 /// Only appearance and the window-level launcher are shared.
+/// 多工具页的状态拥有者，切换时保存/恢复当前页数据。
 pub struct Workspace {
    states: [DeveloperToolsState; 4],
    active: usize,
 }
 impl Workspace {
+    /// 构造本类型并初始化其状态；资源建立和默认字段以函数体为准。
    pub fn new(proxy: winit::event_loop::EventLoopProxy<AppEvent>) -> Self {
        let states = [Tab::Console, Tab::Sources, Tab::Network, Tab::Settings].map(|tab| {
            DeveloperToolsState {
@@ -102,6 +115,7 @@ impl Workspace {
        });
        Self { states, active: 0 }
    }
+    /// 选择一个工具页并恢复它各自保留的输入、焦点和滚动状态。
    pub fn select(&mut self, name: Option<&str>) {
        let next = match name {
            Some("Sources") => 1,
@@ -120,17 +134,20 @@ impl Workspace {
 }
 impl std::ops::Deref for Workspace {
    type Target = DeveloperToolsState;
+    /// 将包装类型的只读访问转交给内部当前上下文。
    fn deref(&self) -> &Self::Target {
        &self.states[self.active]
    }
 }
 impl std::ops::DerefMut for Workspace {
+    /// 将包装类型的可变访问转交给内部当前上下文。
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.states[self.active]
    }
 }

 #[derive(Debug)]
+/// 一份工具页面的输入、选择、滚动、焦点和显示配置。
 pub struct DeveloperToolsState {
    pub open: bool,
    pointer: Point,
@@ -167,6 +184,7 @@ pub struct DeveloperToolsState {
    draft: String,
 }
 impl Default for DeveloperToolsState {
+    /// 建立类型约定的初始值，供尚未发布或尚未交互的状态使用。
    fn default() -> Self {
        Self {
            open: false,
@@ -206,6 +224,7 @@ impl Default for DeveloperToolsState {
    }
 }
 #[derive(Clone, Debug, Default)]
+/// 本帧工具面板与子区域的几何，用于绘制和原生事件命中。
 pub struct DeveloperToolsLayout {
    pub panel: Rect,
    pub widgets: Vec<Target<Action>>,
@@ -216,6 +235,7 @@ pub struct DeveloperToolsLayout {
    source: Option<(Rect, Point, Vec<String>)>,
 }
 impl DeveloperToolsLayout {
+    /// 将工具局部绘制/交互布局平移到实际窗口位置。
    pub fn translate(&mut self, dx: f32, dy: f32) {
        self.panel.x += dx;
        self.panel.y += dy;
@@ -250,11 +270,13 @@ impl DeveloperToolsLayout {
    }
 }
 #[derive(Clone, Copy, Debug)]
+/// Console 文字输入、光标与可见范围的本帧排版。
 struct ConsoleInputLayout {
    viewport: Rect,
    origin: Point,
 }
 impl DeveloperToolsState {
+    /// 用最新完整源文档更新工具投影，维护 Sources 与 Console 历史的一致性。
    pub fn document_updated(&mut self, doc: &RenderDocument) {
        if self
            .selected_node_id
@@ -264,6 +286,7 @@ impl DeveloperToolsState {
            self.selected_node_id = doc.root.as_ref().map(|n| n.id.clone());
        }
    }
+    /// 根据当前工具命中区域选择文本、拖动或默认系统光标。
    pub fn cursor_kind(&self, layout: &DeveloperToolsLayout) -> winit::window::CursorIcon {
        use winit::window::CursorIcon;
        if !self.open {
@@ -286,15 +309,18 @@ impl DeveloperToolsState {
            Cursor::Disabled => CursorIcon::NotAllowed,
        }
    }
+    /// 清理指针或焦点离开后的悬停/捕获状态，避免按下状态残留。
    pub fn pointer_left(&mut self) {
        self.interaction.pointer_left();
    }
+    /// 清理指针或焦点离开后的悬停/捕获状态，避免按下状态残留。
    pub fn blur(&mut self) {
        self.interaction.blur();
        self.drag = None;
        self.focus = None;
        self.preedit.clear();
    }
+    /// 记录按下时的控件或文本选择目标，为释放激活和拖动保留捕获。
    pub fn press(&mut self, layout: &DeveloperToolsLayout, p: Point, activity: &Activity) {
        if !self.open || !layout.panel.contains(p) {
            return;
@@ -333,6 +359,7 @@ impl DeveloperToolsState {
            }
        }
    }
+    /// 执行已确认激活的管理控件动作，区分工具切换、源码操作和设置。
    fn activate(
        &mut self,
        action: Option<Action>,
@@ -423,6 +450,7 @@ impl DeveloperToolsState {
            None => {}
        }
    }
+    /// 结束捕获并按同一目标/启用条件决定是否执行操作。
    pub fn release(&mut self, layout: &DeveloperToolsLayout, p: Point, activity: &Activity) {
        self.pointer = p;
        self.interaction.pointer_moved(p, &layout.widgets);
@@ -433,6 +461,7 @@ impl DeveloperToolsState {
            self.activate(action, layout, p, activity);
        }
    }
+    /// 按工具控件焦点处理 Tab、确认等管理键盘交互。
    pub fn keyboard_control(
        &mut self,
        event: &winit::event::KeyEvent,
@@ -491,6 +520,7 @@ impl DeveloperToolsState {
        }
        false
    }
+    /// 更新工具内悬停、拖动、选择或分隔条位置。
    pub fn move_pointer(
        &mut self,
        p: Point,
@@ -535,6 +565,7 @@ impl DeveloperToolsState {
            None => {}
        }
    }
+    /// 将滚轮作用到当前工具的可滚动区域，钳制本工具偏移。
    pub fn wheel(&mut self, layout: &DeveloperToolsLayout, p: Point, dx: f32, dy: f32) {
        if let Some((_, r, _, _)) = layout
            .regions
@@ -550,6 +581,7 @@ impl DeveloperToolsState {
            }
        }
    }
+    /// 在当前选择/光标处插入输入文本，并更新光标与可见范围。
    pub fn insert(&mut self, value: &str) {
        match self.focus {
            Some(Focus::Input) => {
@@ -591,9 +623,11 @@ impl DeveloperToolsState {
            Some(Focus::Source) | None => {}
        }
    }
+    /// 调整输入区滚动位置，让当前光标保持在可见范围内。
    pub(crate) fn reveal_cursor(&mut self) {
        self.reveal_input = true;
    }
+    /// 返回输入法候选窗应跟随的逻辑光标位置。
    pub fn ime_position(&self, layout: &DeveloperToolsLayout) -> Point {
        if let Some(input) = layout.input {
            let before = &self.input[..self.cursor];
@@ -608,6 +642,7 @@ impl DeveloperToolsState {
        }
        Point::new(layout.panel.x + 20.0, 60.0)
    }
+    /// 取得当前工具文本选择内容，供复制命令使用。
    pub fn selected_text(&self) -> String {
        if self.focus == Some(Focus::Source) {
            return self.source_selection.text(self.selection);
@@ -622,6 +657,7 @@ impl DeveloperToolsState {
            Some(Focus::Source) | None => String::new(),
        }
    }
+    /// 处理编辑键和导航键，维护 UTF-8 光标/选择边界。
    pub fn key(&mut self, key: &winit::keyboard::NamedKey, shift: bool, command: bool) {
        use winit::keyboard::NamedKey::*;
        if *key == Escape {
@@ -792,6 +828,7 @@ impl DeveloperToolsState {
        }
        self.reveal_cursor();
    }
+    /// 初始化内置工具对应的页面和展示状态，避免重复建立同一组工具。
    pub fn initialize_tools(&mut self, name: &str) {
        let name = name.to_owned();
        let proxy = self.proxy.clone();
@@ -823,9 +860,11 @@ impl DeveloperToolsState {
            }
        });
    }
+    /// 把当前工具输入按所选模式提交给本地 API，并异步反馈结果。
    fn submit(&mut self) {
        self.submit_console(false);
    }
+    /// 提交 Console 输入到持久运行时，而不是把全部历史重新执行一遍。
    fn submit_console(&mut self, reset: bool) {
        if !reset && self.input.trim().is_empty() {
            return;
@@ -867,6 +906,7 @@ impl DeveloperToolsState {
    }
 }

+/// 根据当前输入构造本模块的派生结果，具体的验证与资源边界见函数内步骤。
 pub fn build(
    width: u32,
    height: u32,