docs: 逐模块细化中文逻辑注释并覆盖测试与示例

This commit is contained in:
2026-11-12 10:31:35 +08:00
parent d29a1be329
commit cd23e70db1
123 changed files with 2664 additions and 249 deletions
+17 -1
View File
@@ -3,7 +3,7 @@
//!
use super::*;
/// 根据当前输入构造本模块的派生结果,具体的验证与资源边界见函数内步骤。
/// 将有界 HTTP 活动、当前编辑输入和输入法预编辑投影为 Console 显示行与命中布局,并按需滚动到光标。
pub(super) fn build(
p: &mut Painter,
state: &mut DeveloperToolsState,
@@ -12,6 +12,7 @@ pub(super) fn build(
) {
let x = viewport.x;
let w = viewport.width;
// 此工具页使用其既定标题栏/底栏布局坐标,输出区与输入区共享下方 transcript 滚动面板。
let bottom = viewport.height - 22.0;
p.fill(Rect::new(x, 32.0, w, 30.0), BAR);
@@ -44,7 +45,9 @@ pub(super) fn build(
if w > 520.0 {
p.label(x + 309.0, 39.0, "app.main · live objects", MUTED, false);
}
// 先把活动记录投影成显示行,再把当前输入附在末尾;不会在绘制函数中提交或执行程序。
let mut lines = Vec::new();
// console_after 是清屏水位,只展示其后会改变程序状态的请求;原生 /events 输入不刷入 Console。
for r in records.iter().filter(|r| {
r.id > state.console_after
&& (r.method == "PUT" || r.method == "POST" || r.method == "DELETE")
@@ -63,6 +66,7 @@ pub(super) fn build(
} else {
"CLEAR DOCUMENT"
};
// Console 自己发起的 REPL 请求省略冗余标题和 HTTP 状态行,外部请求保留来源与诊断入口。
let local = r.origin == "Console" && r.path.ends_with("/repl") && r.method == "POST";
if !local {
let mut title = Line::new(
@@ -73,6 +77,7 @@ pub(super) fn build(
title.action = Some(Action::Request(r.id));
lines.push(title);
}
// 请求正文逐行展示,首行 > 提示符、续行两个空格;保留源码换行而不执行文本。
for (i, line) in r.request.split('\n').enumerate() {
lines.push(Line::new(
format!("{}{line}", if i == 0 { "> " } else { " " }),
@@ -84,6 +89,7 @@ pub(super) fn build(
} else {
OK
};
// 未完成请求显示 Executing,完成后才解析响应;HTTP 4xx/5xx 使用错误颜色。
if let Some(status) = r.status {
if !local {
lines.push(Line::new(
@@ -107,6 +113,7 @@ pub(super) fn build(
);
}
use std::hash::{Hash, Hasher};
// 只对输出行文本求 stamp,用来判断 Follow 是否需要跳到底部;当前编辑输入不参与输出变化检测。
let mut hash = std::collections::hash_map::DefaultHasher::new();
for line in &lines {
line.value.hash(&mut hash);
@@ -114,8 +121,10 @@ pub(super) fn build(
let stamp = hash.finish();
let output_changed = stamp != state.console_stamp;
state.console_stamp = stamp;
// 记录输入开始的行号,后续光标和点击区域都需加上 transcript 输出行偏移。
let first_input = lines.len();
let area = Rect::new(x + 4.0, 63.0, w - 5.0, (bottom - 88.0).max(1.0));
// 输入法 preedit 只插入显示副本,不提交到实际 input;只有输入框持焦点时展示组合文本。
let mut input = state.input.clone();
if state.focus == Some(Focus::Input) {
input.insert_str(state.cursor, &state.preedit);
@@ -126,13 +135,16 @@ pub(super) fn build(
lines.push(line);
}
let prefix = text::measure("> ", TextStyle::code()).width;
// cursor 是输入字符串的字节边界,由编辑逻辑维护;通过换行计数定位行,再用真实字体宽度计算列位置。
let before = &state.input[..state.cursor];
let row = before.matches('\n').count() as f32;
let column = before.rsplit('\n').next().unwrap_or("");
let caret_x =
prefix + text::measure(&format!("{column}{}", state.preedit), TextStyle::code()).width;
let caret_y = (first_input as f32 + row) * ROW;
// 新输出触发 Follow,但显式 reveal_input 优先,避免执行后或编辑时光标被自动滚动隐藏。
let follow = state.follow && output_changed && !state.reveal_input;
// 把现有滚动量钳入“光标可见”的允许范围,而非每次将光标强制居中;横向预留 24 单位空间。
if state.reveal_input {
let s = &mut state.scroll[Region::Transcript as usize];
s.y = s.y.clamp(
@@ -148,6 +160,7 @@ pub(super) fn build(
area.x + 8.0 + prefix - scroll.x,
area.y + 5.0 + first_input as f32 * ROW - scroll.y,
);
// 保存最终滚动后的输入原点与视口,供后续鼠标定位复用,不能仅凭字符数估算点击位置。
p.layout.input = Some(ConsoleInputLayout {
viewport: area,
origin,
@@ -155,6 +168,7 @@ pub(super) fn build(
let input_top = origin.y.max(area.y);
let input_bottom =
(origin.y + state.input.split('\n').count() as f32 * ROW).min(area.y + area.height - 9.0);
// 仅为仍可见的输入片段注册文本输入命中区,扣除滚动条空间,避免历史输出区误抢输入焦点。
if input_bottom > input_top {
p.ui.inline_input(
Rect::new(
@@ -166,6 +180,7 @@ pub(super) fn build(
Action::Focus(Focus::Input),
);
}
// 光标单独绘制并限制在文本视口内,不能穿过滚动条或工具页边缘;随后配对 PopClip。
if state.focus == Some(Focus::Input) {
p.ui.list.push(DrawCommand::PushClip(Rect::new(
area.x,
@@ -184,6 +199,7 @@ pub(super) fn build(
);
p.ui.list.push(DrawCommand::PopClip);
}
// 底部无输入错误时展示快捷键,有错则复用同一位置显示错误文本及错误颜色。
p.label(
x + 10.0,
bottom - 23.0,
+8 -1
View File
@@ -3,7 +3,7 @@
//!
use super::*;
/// 根据当前输入构造本模块的派生结果,具体的验证与资源边界见函数内步骤。
/// 将本进程 HTTP 活动投影为可筛选请求列表和独立滚动详情,并生成选择/分隔条命中区域。
pub(super) fn build(
p: &mut Painter,
state: &mut DeveloperToolsState,
@@ -50,10 +50,13 @@ pub(super) fn build(
MUTED,
true,
);
// 上下区分隔位置取自工具状态比例,拖动只改变显示分配,不改变记录本身。
let divider = 92.0 + (bottom - 92.0) * state.network_fraction;
// 对方法、路径和状态的组合字符串做大小写不敏感子串匹配;未响应记录可用 pending 搜索。
let filter = state.filter.to_lowercase();
let visible = records
.iter()
// 清屏按 ID 水位隐藏旧记录,不删除共享 ActivityLog,Console 仍可独立展示同一条请求。
.filter(|r| r.id > state.network_after)
.filter(|r| {
format!(
@@ -82,10 +85,12 @@ pub(super) fn build(
TEXT
},
);
// 请求 ID 是选择身份,不依赖筛选后行号;点击行仅生成 Request 动作,不重新发送 HTTP。
l.selected = state.selected_request == Some(r.id);
l.action = Some(Action::Request(r.id));
lines.push(l);
}
// 空列表可能来自无记录、清屏或过滤无匹配,统一展示本进程 API 的捕获范围提示。
if lines.is_empty() {
lines.push(Line::new(
"No matching requests. Listening to Tessera's local API.",
@@ -100,6 +105,7 @@ pub(super) fn build(
false,
);
p.split(Rect::new(x + 1.0, divider, w - 2.0, 1.0), Split::Network);
// 详情从完整保留记录中查找,因此筛选隐藏某行后可继续查看已选详情;记录淘汰后才回提示。
let selected = records
.iter()
.find(|r| Some(r.id) == state.selected_request);
@@ -113,6 +119,7 @@ pub(super) fn build(
MUTED,
);
}
// 请求列表与详情使用不同 Region,各自维护滚动量,避免切换详情影响列表定位。
p.lines(
Rect::new(x + 1.0, divider + 5.0, w - 2.0, bottom - divider - 5.0),
Region::Details,
+29 -9
View File
@@ -9,16 +9,17 @@ pub(super) struct Painter {
pub(super) layout: DeveloperToolsLayout,
}
impl Painter {
/// 绘制对应管理界面原语,并按控件需要同步登记命中和滚动区域。
/// 向宿主显示列表追加填充矩形,不登记点击或滚动目标。
pub(super) fn fill(&mut self, r: Rect, c: Color) {
self.ui.fill(r, c);
}
/// 绘制对应管理界面原语,并按控件需要同步登记命中和滚动区域。
/// 绘制工具文字,code 选择等宽风格;不在此处截断文本或登记目标。
pub(super) fn label(&mut self, x: f32, y: f32, value: &str, c: Color, code: bool) {
self.ui.label(x, y, value, c, code);
}
/// 绘制对应管理界面原语,并按控件需要同步登记命中和滚动区域。
/// 创建普通或切换按钮,active 作为选中状态参与外观。
pub(super) fn button(&mut self, r: Rect, label: &str, action: Action, active: bool) {
// Follow 与数据源切换使用 Toggle 语义,其余动作使用普通按钮角色;身份仍由 action 决定。
let role = match action {
Action::Follow | Action::Snapshot | Action::Cloud => Role::Toggle,
_ => Role::Button,
@@ -26,17 +27,18 @@ impl Painter {
self.ui
.button(r, action, Button::new(label).selected(active).role(role));
}
/// 绘制对应管理界面原语,并按控件需要同步登记命中和滚动区域。
/// 创建带启用条件的按钮,禁用项仍可显示但不能激活动作。
pub(super) fn enabled_button(&mut self, r: Rect, label: &str, action: Action, enabled: bool) {
self.ui
.button(r, action, Button::new(label).enabled(enabled));
}
/// 绘制对应管理界面原语,并按控件需要同步登记命中和滚动区域。
/// 记录待在最终覆盖层绘制的分隔条及其拖动类别,此处不立即画线。
pub(super) fn split(&mut self, r: Rect, kind: Split) {
// Paint and register splitters after all pane content, in one overlay pass.
// 此处只记录分隔条布局,外层最后统一覆盖绘制/注册,保证线条与命中目标位于内容之上。
self.layout.splits.push((r, kind));
}
/// 绘制对应管理界面原语,并按控件需要同步登记命中和滚动区域。
/// 测量并缓存完整行宽,钳制滚动,仅绘制可见行,同时登记区域、选择和两轴滚动条。
pub(super) fn lines(
&mut self,
area: Rect,
@@ -45,17 +47,20 @@ impl Painter {
state: &mut DeveloperToolsState,
follow: bool,
) {
// 按固定行高估计完整内容高度并预留上下边距,不仅按当前可见行计算。
let content_h = lines.len() as f32 * ROW + 12.0;
use std::hash::{Hash, Hasher};
let mut hash = std::collections::hash_map::DefaultHasher::new();
for line in lines {
line.value.hash(&mut hash);
}
// 宽度缓存只依赖行文本指纹,颜色/选择变化无需重新测量;文字样式在此固定为 code。
let fingerprint = hash.finish();
let cache = &mut state.widths[region as usize];
let content_w = match *cache {
Some((previous, width)) if previous == fingerprint => width,
_ => {
// 失配时测量所有行的最大宽度并加边距;后面虽然只画可见行,横向范围仍反映完整内容。
let width = lines
.iter()
.map(|line| text::measure(&line.value, TextStyle::code()).width + 20.0)
@@ -65,18 +70,21 @@ impl Painter {
}
};
let s = &mut state.scroll[region as usize];
// Follow 跳到内容末端;否则只钳掉内容缩短后越界的旧偏移,保留用户当前阅读位置。
s.y = if follow {
(content_h - area.height + 12.0).max(0.0)
} else {
s.y.clamp(0.0, (content_h - area.height + 12.0).max(0.0))
};
s.x = s.x.clamp(0.0, (content_w - area.width + 12.0).max(0.0));
// 裁剪扣掉右/下 9 单位滚动条空间,避免行文字覆盖滚动手柄。
self.ui.list.push(DrawCommand::PushClip(Rect::new(
area.x,
area.y,
(area.width - 9.0).max(0.0),
(area.height - 9.0).max(0.0),
)));
// 源码行前七字符为显示行号与间隔,选择数据去掉这段;输入法/Console 编辑使用其他状态。
if region == Region::Source {
let values = lines
.iter()
@@ -92,6 +100,7 @@ impl Painter {
values,
));
}
// 按滚动量只遍历可见行,并多取两行覆盖边缘部分行;完整文本仍保留供测量和复制。
let first = (s.y / ROW).floor() as usize;
let count = (area.height / ROW).ceil() as usize + 2;
for (i, line) in lines.iter().enumerate().skip(first).take(count) {
@@ -109,6 +118,7 @@ impl Painter {
if let Some(action) = &line.action {
let top = y.max(area.y);
let bottom = (y + ROW).min(area.y + area.height - 9.0);
// 部分可见行只注册可见矩形,避免裁剪虽隐藏图形、交互区域却仍延伸到面板之外。
if bottom > top {
self.ui.row(
paint,
@@ -120,6 +130,7 @@ impl Painter {
} else if line.selected {
self.fill(paint, self.ui.theme.soft());
}
// 源码字素选区单独叠加高亮;行选择与文字选择共存,位置由去掉行号后的 origin 计算。
if region == Region::Source
&& let Some((_, origin, values)) = &self.layout.source
&& let Some((left, right)) = state.source_selection.span(
@@ -136,13 +147,14 @@ impl Painter {
self.label(area.x + 8.0 - s.x, y, &line.value, line.color, true);
}
self.ui.list.push(DrawCommand::PopClip);
// 记录完整内容范围给滚轮/拖动逻辑,再在裁剪弹出后绘制两轴滚动条,避免手柄被内容裁剪掉。
self.layout
.regions
.push((area, region, content_w, content_h));
self.scrollbar(area, region, false, s.y, content_h);
self.scrollbar(area, region, true, s.x, content_w);
}
/// 绘制对应管理界面原语,并按控件需要同步登记命中和滚动区域。
/// 按内容/视口比例绘制单轴滚动手柄,并登记拖动到内容位移的换算倍率。
pub(super) fn scrollbar(
&mut self,
r: Rect,
@@ -151,13 +163,16 @@ impl Painter {
offset: f32,
content: f32,
) {
// h 统一复用横纵轴公式;先扣除另一轴手柄占用,内容不溢出或视口无面积时不创建滚动条。
let viewport = if h { r.width } else { r.height } - 10.0;
if content <= viewport || viewport <= 0.0 {
return;
}
// 手柄按 viewport/content 比例缩放,至少 24 且不大于轨道;travel 和 maximum 至少 1 防止除零。
let length = (viewport * viewport / content).max(24.0).min(viewport);
let travel = (viewport - length).max(1.0);
let maximum = (content - viewport).max(1.0);
// 内容偏移归一化后映射到手柄可移动距离;两者并非一比一像素关系。
let position = (offset / maximum).clamp(0.0, 1.0) * travel;
let track = if h {
Rect::new(r.x, r.y + r.height - 8.0, viewport, 8.0)
@@ -177,6 +192,7 @@ impl Painter {
);
self.layout
.thumbs
// 保存每单位手柄拖动对应的内容位移倍率,事件处理可直接反算滚动量。
.push((thumb, region, h, maximum / travel));
}
}
@@ -196,7 +212,7 @@ pub(super) enum Divider {
Neutral,
}
impl Line {
/// 构造本类型并初始化其状态;资源建立和默认字段以函数体为准。
/// 创建默认无分隔线、未选中且无点击动作的显示行。
pub(super) fn new(value: impl Into<String>, color: Color) -> Self {
Self {
value: value.into(),
@@ -207,7 +223,7 @@ impl Line {
}
}
}
/// 按行绘制工具文本,返回后续布局需要的占用范围。
/// 将文本按换行分成显示行并展开 Tab,追加到 out;不直接绘制,也不返回布局范围。
pub(super) fn multiline(out: &mut Vec<Line>, value: &str, color: Color) {
out.extend(
value
@@ -218,7 +234,9 @@ pub(super) fn multiline(out: &mut Vec<Line>, value: &str, color: Color) {
}
/// 把一条 Console 结果投影为可滚动、可选择的文字画面。
pub(super) fn console_result(out: &mut Vec<Line>, body: &str, color: Color) {
// 响应若为 JSON,按 reset、value、diagnostics、error、revision 优先提取可读结果;不满足时退回原文。
if let Ok(value) = serde_json::from_str::<serde_json::Value>(body) {
// 先显示 REPL 是否发布新页面或仅保留内存状态,再显示实际结果/诊断,避免把成功执行等同于重绘。
if value["execution"] == "repl" {
out.push(Line::new(
if value["rendered"] == true {
@@ -281,6 +299,7 @@ pub(super) fn console_result(out: &mut Vec<Line>, body: &str, color: Color) {
}
/// 将代码层次展开为工具可绘制的行数据,保留节点与源范围关联。
pub(super) fn flatten<'a>(node: &'a CodeNode, depth: usize, out: &mut Vec<(usize, &'a CodeNode)>) {
// 先序展开保持 AST 子节点顺序,depth 供显示缩进;借用原节点而不复制整棵树。
out.push((depth, node));
for child in &node.children {
flatten(child, depth + 1, out);
@@ -303,6 +322,7 @@ pub(super) fn request_details(out: &mut Vec<Line>, r: &Exchange) {
),
TEXT,
);
// 固定次序展示请求头、请求正文、响应头、响应正文;这里只消费已经截断的观察记录。
for (title, body) in [
("REQUEST HEADERS", &r.request_headers),
("REQUEST BODY", &r.request),
+13 -1
View File
@@ -12,13 +12,15 @@ use unicode_segmentation::UnicodeSegmentation;
/// 行文本、锚点与选择端点,既供鼠标拖选也供键盘导航使用。
pub(super) struct SourceSelection {
lines: Vec<String>,
// 端点是 (行号, UTF-8 字节偏移),字节位置始终由完整字素边界产生,不用字符数直接切片。
anchor: (usize, usize),
end: (usize, usize),
pub dragging: bool,
}
impl SourceSelection {
/// 替换可选择文本行,并把旧选择限制在新文本仍有效的位置。
/// 同步展示文本;内容变化时重置选择和拖动,内容完全相同时保留原选区。
pub fn set_lines(&mut self, lines: &[String]) {
// 文本变化时重置两端与拖选状态;当前实现不是把旧选区钳到新文本,避免对应内容已经改变。
if self.lines != lines {
self.lines = lines.to_vec();
self.anchor = (0, 0);
@@ -28,6 +30,7 @@ impl SourceSelection {
}
/// 把工具指针位置换算成合法行号与文本字符边界。
fn locate(p: Point, origin: Point, lines: &[String]) -> (usize, usize) {
// 按固定行高求行号,向上下界钳制;空文本通过 saturating_sub 与后续 get 安全返回原点。
let row = (((p.y - origin.y) / super::ROW).floor().max(0.0) as usize)
.min(lines.len().saturating_sub(1));
let Some(line) = lines.get(row) else {
@@ -35,6 +38,7 @@ impl SourceSelection {
};
let x = (p.x - origin.x).max(0.0);
let mut byte = line.len();
// 逐个字素测量左右边界,以中点决定插入位置,点击超过行尾则保留 byte=line.len()。
for (i, g) in line.grapheme_indices(true) {
let left = text::measure(&line[..i], TextStyle::code()).width;
let right = text::measure(&line[..i + g.len()], TextStyle::code()).width;
@@ -47,6 +51,7 @@ impl SourceSelection {
}
/// 在指针位置建立文本选择锚点,开始一次拖动选择。
pub fn begin(&mut self, p: Point, origin: Point, lines: &[String]) {
// 调用方提供的 lines 与当前展示一致;开始拖动先折叠旧选择,后续 extend 只移动活动端。
self.anchor = Self::locate(p, origin, lines);
self.end = self.anchor;
self.dragging = true;
@@ -66,6 +71,7 @@ impl SourceSelection {
let (mut row, mut byte) = self.end;
let line = self.lines.get(row)?;
match key {
// 水平移动按字素跨越,组合音标和 emoji 视作整体;到行边界后跨到相邻行的末尾/开头。
ArrowLeft => {
if byte > 0 {
byte = line[..byte]
@@ -85,6 +91,7 @@ impl SourceSelection {
byte = 0;
}
}
// 垂直移动保持的是字素列数,不是像素 x;目标行较短时取尽其字素,落到行尾。
ArrowUp | ArrowDown => {
let col = line[..byte].graphemes(true).count();
row = if *key == ArrowUp {
@@ -98,6 +105,7 @@ impl SourceSelection {
.map(str::len)
.sum();
}
// 普通 Home/End 选本行边界,command 修饰时转到整个文本首/末行。
Home => {
if command {
row = 0;
@@ -113,6 +121,7 @@ impl SourceSelection {
_ => return None,
}
self.end = (row, byte);
// 未按 Shift 时同步锚点以折叠选区;按 Shift 则仅移动 end,保持原锚点扩展选择。
if !shift {
self.anchor = self.end;
}
@@ -129,6 +138,7 @@ impl SourceSelection {
),
);
}
// 元组字典序先比行号再比字节位置,统一处理从后向前拖选与从前向后拖选。
(self.anchor.min(self.end), self.anchor.max(self.end))
}
/// 拼接当前选择范围内的实际文本,保持多行换行与 UTF-8 边界。
@@ -139,6 +149,7 @@ impl SourceSelection {
.enumerate()
.filter(|(i, _)| *i >= a.0 && *i <= b.0)
.map(|(i, line)| {
// 首尾行只取选中片段,中间行取完整文本;用安全 get 防止不一致范围导致切片 panic。
let start = if i == a.0 { a.1 } else { 0 };
let end = if i == b.0 { b.1 } else { line.len() };
line.get(start..end).unwrap_or("").to_owned()
@@ -149,6 +160,7 @@ impl SourceSelection {
/// 取得某行的可见选择片段,供高亮绘制复用。
pub fn span(&self, row: usize, all: bool, lines: &[String]) -> Option<(f32, f32)> {
let (a, b) = self.range(all);
// 未选中的行或折叠选择不画高亮;有选择时返回两个真实字体测量的横向位置,不是宽度值。
if row < a.0 || row > b.0 || a == b {
return None;
}
+5 -1
View File
@@ -3,7 +3,7 @@
//!
use super::*;
/// 根据当前输入构造本模块的派生结果,具体的验证与资源边界见函数内步骤。
/// 绘制强调色候选、自定义颜色编辑框及主题预览;实际应用和错误校验由输入动作处理。
pub(super) fn build(p: &mut Painter, state: &mut DeveloperToolsState, viewport: Rect) {
let x = viewport.x;
let w = viewport.width;
@@ -16,6 +16,7 @@ pub(super) fn build(p: &mut Painter, state: &mut DeveloperToolsState, viewport:
MUTED,
false,
);
// 色块动作携带调色板索引,绘制仅比较当前 accent 标记选中;实际修改由统一动作处理器执行。
for (i, color) in PALETTE.iter().enumerate() {
let r = Rect::new(x + 24.0 + i as f32 * 44.0, 122.0, 32.0, 32.0);
p.ui.swatch(r, Action::Theme(i), *color, *color == state.accent);
@@ -27,6 +28,7 @@ pub(super) fn build(p: &mut Painter, state: &mut DeveloperToolsState, viewport:
MUTED,
false,
);
// 自定义颜色框显示尚未应用的编辑文本;聚焦只改变外观和输入接收位置,不在这里解析 hex。
let custom = Rect::new(x + 24.0, 204.0, 200.0, 32.0);
p.ui.text_field(
custom,
@@ -49,11 +51,13 @@ pub(super) fn build(p: &mut Painter, state: &mut DeveloperToolsState, viewport:
true,
);
// 校验错误由输入处理路径写入,设置页只显示;错误不会在每次重绘时重复执行或清除。
if !state.input_error.is_empty() {
p.label(x + 24.0, 245.0, &state.input_error, ERROR, false);
}
p.fill(Rect::new(x + 24.0, 285.0, w - 48.0, 1.0), BORDER);
p.label(x + 24.0, 305.0, "Theme preview", TEXT, false);
// 预览复用当前强调色和标准成功色,让用户看到主题如何影响执行分隔线;示例文字不送入 VM。
p.fill(Rect::new(x + 24.0, 340.0, w - 48.0, 2.0), state.accent);
p.label(x + 32.0, 353.0, "› \"Hello\"", TEXT, true);
p.label(x + 32.0, 380.0, "‹ \"Hello\"", OK, true);
+13 -1
View File
@@ -3,7 +3,7 @@
//!
use super::*;
/// 根据当前输入构造本模块的派生结果,具体的验证与资源边界见函数内步骤。
/// 根据云文件/当前快照模式构建左右两栏,展示文件或 AST 选择,并生成只读源码行和跳转动作。
pub(super) fn build(
p: &mut Painter,
state: &mut DeveloperToolsState,
@@ -12,6 +12,7 @@ pub(super) fn build(
) {
let x = viewport.x;
let w = viewport.width;
// width 在本函数表示右边界坐标,w 才是视口宽度;用于计算右侧源码区域和按钮位置。
let width = viewport.x + viewport.width;
let bottom = viewport.height - 22.0;
@@ -28,6 +29,7 @@ pub(super) fn build(
Action::Cloud,
state.cloud,
);
// 两种数据源分开投影:云模式用 provider 的 files/opened,快照模式只读已发布文档 source/root。
if state.cloud {
p.button(
Rect::new(width - 92.0, 32.0, 88.0, 29.0),
@@ -35,6 +37,7 @@ pub(super) fn build(
Action::CloudRefresh,
false,
);
// 树宽至少 120,通常为右侧内容保留 180;窄窗口仍保持树最小宽,交由绘制裁剪处理。
let tree = state.tree_width.clamp(120.0, (w - 180.0).max(120.0));
let code_x = x + tree + 2.0;
p.label(x + 10.0, 69.0, "CLOUD FILES", MUTED, false);
@@ -44,6 +47,7 @@ pub(super) fn build(
.iter()
.map(|file| {
let mut l = Line::new(&file.path, TEXT);
// 动作传递 provider 的不透明文件 ID,显示路径不参与本地磁盘读取或代码执行。
l.action = Some(Action::CloudOpen(file.id.clone()));
l
})
@@ -57,6 +61,7 @@ pub(super) fn build(
);
p.split(Rect::new(x + tree, 63.0, 1.0, bottom - 63.0), Split::Tree);
let mut source_lines = Vec::new();
// 成功打开的云文本逐行加显示行号;这里不替换 doc.source,也不触发程序热重载。
if let Some(source) = &state.cloud_sources.opened {
p.label(code_x + 10.0, 69.0, &source.path, MUTED, false);
for (i, line) in source.code.split('\n').enumerate() {
@@ -69,6 +74,7 @@ pub(super) fn build(
MUTED,
);
}
// provider 错误附在当前源码下方;即使读取失败仍可展示上次成功打开的内容。
if !state.cloud_sources.error.is_empty() {
source_lines.push(Line::new(&state.cloud_sources.error, ERROR));
}
@@ -91,6 +97,7 @@ pub(super) fn build(
if doc
.root
.as_ref()
// REPL 文档展示为交互记录,普通脚本展示为 app.main.endor;仅改变标题,不合成另一份源码。
.is_some_and(|root| root.kind == "repl-session")
{
"Console transcript"
@@ -105,6 +112,7 @@ pub(super) fn build(
let mut tree_lines = Vec::new();
if let Some(root) = &doc.root {
let mut flat = Vec::new();
// 将发布 AST 展平成带深度的行;行动作保存节点稳定 ID 与起始行,用于选择并跳到对应代码。
flatten(root, 0, &mut flat);
for (depth, n) in flat {
let mut l = Line::new(format!("{}{} {}", " ".repeat(depth), n.kind, n.name), TEXT);
@@ -123,23 +131,27 @@ pub(super) fn build(
false,
);
p.split(Rect::new(x + tree, 63.0, 1.0, bottom - 63.0), Split::Tree);
// 每次重绘按当前文档查节点,旧选择 ID 若已不存在则不高亮,避免沿用旧 AST 行范围。
let selected = state
.selected_node_id
.as_deref()
.and_then(|id| doc.node(id));
let code_lines = doc
.source
// 仅显示投影统一 CRLF 并把 Tab 展开为四空格;原始文档文本保持不变。
.replace("\r\n", "\n")
.split('\n')
.enumerate()
.map(|(i, s)| {
let mut l = Line::new(format!("{:>5} {}", i + 1, s.replace('\t', " ")), TEXT);
// i 是零基行号,AST 行号是一基;条件等价于 start_line <= i+1 <= end_line。
l.selected = selected.is_some_and(|n| i + 1 >= n.start_line && i < n.end_line);
l
})
.collect::<Vec<_>>();
p.lines(
Rect::new(code_x, 92.0, width - code_x, bottom - 92.0),
// 源码区与 AST 树各自保存滚动位置,选择节点并不把树文本误当作源码内容。
Region::Source,
&code_lines,
state,