docs: 逐模块细化中文逻辑注释并覆盖测试与示例
This commit is contained in:
@@ -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),
|
||||
|
||||
Reference in New Issue
Block a user