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
+43 -3
View File
@@ -104,7 +104,7 @@ pub struct Workspace {
active: usize,
}
impl Workspace {
/// 构造本类型并初始化其状态;资源建立和默认字段以函数体为准。
/// 为 Console/Sources/Network/Settings 各创建一份独立状态,共享事件循环代理,初始选择 Console。
pub fn new(proxy: winit::event_loop::EventLoopProxy<AppEvent>) -> Self {
let states = [Tab::Console, Tab::Sources, Tab::Network, Tab::Settings].map(|tab| {
DeveloperToolsState {
@@ -123,6 +123,7 @@ impl Workspace {
Some("Settings") => 3,
_ => 0,
};
// 每个工具保留自己的文本/滚动/选择,强调色在切换时从旧活动页复制;切走先 blur 解除捕获与输入法状态。
let accent = self.states[self.active].accent;
if next != self.active {
self.states[self.active].blur();
@@ -160,7 +161,9 @@ pub struct DeveloperToolsState {
pub selected_node_id: Option<String>,
pub focus: Option<Focus>,
pub input: String,
// Console 光标是 UTF-8 字节位置,移动和删除按 grapheme 边界维护,不用字符下标直接切字符串。
pub cursor: usize,
// 输入框表示全选状态,Sources 则结合 SourceSelection 表示全选;并非通用起止字节范围。
pub selection: bool,
pub preedit: String,
pub filter: String,
@@ -170,6 +173,7 @@ pub struct DeveloperToolsState {
tree_width: f32,
network_fraction: f32,
scroll: [Scroll; 5],
// 各 Region 独立保存行文本指纹与最大宽度,颜色/选择改变无需重测,文本改变才失效。
widths: [Option<(u64, f32)>; 5],
reveal_input: bool,
console_stamp: u64,
@@ -177,10 +181,12 @@ pub struct DeveloperToolsState {
cloud: bool,
follow: bool,
selected_request: Option<u64>,
// 清屏水位只隐藏旧记录,与共享 ActivityLog 的实际淘汰分开;Network 有独立水位。
console_after: u64,
network_after: u64,
history: Vec<String>,
history_index: Option<usize>,
// 首次进入历史导航前保存当前未提交输入,向下越过最新历史后恢复此草稿。
draft: String,
}
impl Default for DeveloperToolsState {
@@ -237,6 +243,7 @@ pub struct DeveloperToolsLayout {
impl DeveloperToolsLayout {
/// 将工具局部绘制/交互布局平移到实际窗口位置。
pub fn translate(&mut self, dx: f32, dy: f32) {
// 绘制列表已由外层按设备像素平移,这里所有命中矩形和文字原点都按逻辑单位同步移动。
self.panel.x += dx;
self.panel.y += dy;
for target in &mut self.widgets {
@@ -278,6 +285,7 @@ struct ConsoleInputLayout {
impl DeveloperToolsState {
/// 用最新完整源文档更新工具投影,维护 Sources 与 Console 历史的一致性。
pub fn document_updated(&mut self, doc: &RenderDocument) {
// 已选 AST ID 在新文档不存在时回退根;有效选择继续保留,不按行号盲目关联另一份代码。
if self
.selected_node_id
.as_deref()
@@ -325,6 +333,7 @@ impl DeveloperToolsState {
if !self.open || !layout.panel.contains(p) {
return;
}
// 鼠标重新定位输入目标时结束旧预编辑显示,避免把输入法组合文本残留到另一控件。
self.preedit.clear();
self.pointer = p;
self.interaction.pointer_moved(p, &layout.widgets);
@@ -332,6 +341,7 @@ impl DeveloperToolsState {
self.focus = None;
if let Some((area, origin, lines)) = &layout.source
&& area.contains(p)
// 只有未被滚动条/分隔条等控件命中时才开始源码拖选,管理控件优先于文字区域。
&& target.is_none()
{
self.focus = Some(Focus::Source);
@@ -354,6 +364,7 @@ impl DeveloperToolsState {
self.drag = Some(Drag::Scroll(*region, *h, *ratio));
}
}
// 文本框按下立即取得编辑焦点/定位光标;普通按钮动作仍等 release 确认同一启用目标。
Role::TextField => self.activate(target.action, layout, p, activity),
_ => {}
}
@@ -375,6 +386,7 @@ impl DeveloperToolsState {
if f == Focus::Input
&& let Some(input) = layout.input
{
// 根据本帧输入原点和固定行高定位行,逐字素测量字节结束位置决定插入点,不能按等宽字符数量切中文。
let row = (((p.y - input.origin.y) / ROW).floor().max(0.0) as usize)
.min(self.input.split('\n').count() - 1);
let mut start = 0;
@@ -405,6 +417,7 @@ impl DeveloperToolsState {
self.reveal_cursor();
}
}
// 清屏只更新水位/滚动,不删除 VM 全局对象;ResetSession 才向 API 请求清会话。
Some(Action::ClearConsole) => {
self.console_after = activity.lock().unwrap().records.back().map_or(0, |r| r.id);
self.scroll[Region::Transcript as usize] = Scroll::default();
@@ -431,6 +444,7 @@ impl DeveloperToolsState {
self.scroll[Region::Source as usize].x = 0.0;
self.scroll[Region::Source as usize].y = line.saturating_sub(1) as f32 * ROW;
}
// 在 Console 选外部请求标题可切 Network 并清筛选,让目标记录可见;详情滚动回顶部。
Some(Action::Request(id)) => {
self.selected_request = Some(id);
if self.tab == Tab::Console {
@@ -473,6 +487,7 @@ impl DeveloperToolsState {
event::ElementState,
keyboard::{Key, NamedKey},
};
// 输入法正在组合时不抢 Enter/Space 等控件键盘激活,避免确认候选被误触发按钮。
if !self.open || !self.preedit.is_empty() {
return false;
}
@@ -482,6 +497,7 @@ impl DeveloperToolsState {
}
return true;
}
// Console 输入内普通 Tab 插四空格;Shift+Tab 或其他焦点的 Tab 走控件循环导航。
if event.logical_key == Key::Named(NamedKey::Tab)
&& (self.focus != Some(Focus::Input) || shift)
{
@@ -509,6 +525,7 @@ impl DeveloperToolsState {
)
{
if event.state == ElementState::Pressed {
// 控件只在非自动重复按下时捕获,抬起时返回动作,避免长按 Enter 重复提交控制操作。
if !event.repeat {
self.interaction.key_press(&layout.widgets);
}
@@ -533,6 +550,7 @@ impl DeveloperToolsState {
if self.source_selection.dragging
&& let Some((area, origin, lines)) = &layout.source
{
// 源码拖选越出视口时每次指针移动增加/减少一行滚动;不是单独定时器持续自动滚动。
if p.y < area.y || p.y > area.y + area.height - 9.0 {
let direction = if p.y < area.y { -ROW } else { ROW };
self.scroll[Region::Source as usize].y =
@@ -551,6 +569,7 @@ impl DeveloperToolsState {
/ (layout.panel.height - 114.0).max(1.0))
.clamp(0.2, 0.8)
}
// 手柄位移乘 Painter 保存的 content/travel 倍率转成内容偏移;手动滚动 transcript 会关闭自动 Follow。
Some(Drag::Scroll(r, h, ratio)) => {
let s = &mut self.scroll[r as usize];
if h {
@@ -567,6 +586,7 @@ impl DeveloperToolsState {
}
/// 将滚轮作用到当前工具的可滚动区域,钳制本工具偏移。
pub fn wheel(&mut self, layout: &DeveloperToolsLayout, p: Point, dx: f32, dy: f32) {
// 滚轮寻找最前景包含点的 Region,只钳下限;上限在下一轮绘制根据最新内容范围统一钳制。
if let Some((_, r, _, _)) = layout
.regions
.iter()
@@ -585,6 +605,7 @@ impl DeveloperToolsState {
pub fn insert(&mut self, value: &str) {
match self.focus {
Some(Focus::Input) => {
// 先检查当前输入+新文本字节总量,再处理全选替换;因此大输入全选后粘贴仍按此保守上限检查。
if self.input.len() + value.len() > 1_048_576 {
self.input_error = "Input exceeds 1 MiB".into();
return;
@@ -596,6 +617,7 @@ impl DeveloperToolsState {
}
self.input.insert_str(self.cursor, value);
self.cursor += value.len();
// 编辑历史条目后退出历史导航,当前输入成为新的可提交文本;光标使用插入文本实际 UTF-8 字节数推进。
self.history_index = None;
self.reveal_cursor();
}
@@ -605,6 +627,7 @@ impl DeveloperToolsState {
self.selection = false;
}
self.filter
// Filter 每次插入最多200个无控制字符;这是单次输入限制,不是累计字符串长度上限。
.extend(value.chars().filter(|c| !c.is_control()).take(200));
self.scroll[Region::Requests as usize].y = 0.0;
}
@@ -616,6 +639,7 @@ impl DeveloperToolsState {
self.custom.extend(
value
.chars()
// 颜色输入仅保留 hex/# 字符,每次最多7个;真正六位格式在 Enter 应用时验证。
.filter(|c| c.is_ascii_hexdigit() || *c == '#')
.take(7),
);
@@ -624,6 +648,7 @@ impl DeveloperToolsState {
}
}
/// 调整输入区滚动位置,让当前光标保持在可见范围内。
// 只设置下一帧 reveal 标记,具体滚动到可见范围由 Console build 在测量光标位置后完成。
pub(crate) fn reveal_cursor(&mut self) {
self.reveal_input = true;
}
@@ -644,6 +669,7 @@ impl DeveloperToolsState {
}
/// 取得当前工具文本选择内容,供复制命令使用。
pub fn selected_text(&self) -> String {
// 源码支持任意拖选区间或全选;其他三个文本框当前只支持整框全选复制。
if self.focus == Some(Focus::Source) {
return self.source_selection.text(self.selection);
}
@@ -674,6 +700,7 @@ impl DeveloperToolsState {
}
return;
}
// 应用主题时解析六位 RGB 并调整过亮强调色,失败保留原主题并写输入错误。
if self.focus == Some(Focus::Custom) && *key == Enter {
let hex = self.custom.trim_start_matches('#');
if hex.len() == 6
@@ -724,6 +751,7 @@ impl DeveloperToolsState {
.grapheme_indices(true)
.next_back()
.map_or(0, |(i, _)| i);
// Backspace 删除前一完整字素;Delete 删除后一完整字素,组合音标和 emoji 不会拆成半个可见字符。
self.input.replace_range(n..self.cursor, "");
self.cursor = n;
} else if *key == Delete && self.cursor < self.input.len() {
@@ -776,10 +804,12 @@ impl DeveloperToolsState {
};
self.selection = false;
}
// command+上下或单行输入进入历史,普通多行上下则按字素列定位相邻行,两种导航职责分开。
ArrowUp | ArrowDown if command || !self.input.contains('\n') => {
if self.history.is_empty() {
return;
}
// 仅首次进入历史保存草稿,连续翻旧记录不会把历史内容覆盖原草稿。
if self.history_index.is_none() {
self.draft = self.input.clone();
}
@@ -797,6 +827,7 @@ impl DeveloperToolsState {
}
ArrowUp | ArrowDown => {
let start = self.input[..self.cursor].rfind('\n').map_or(0, |i| i + 1);
// 多行垂直导航保持字素列数,不保持像素 x;目标行较短时自然停到行尾。
let col = self.input[start..self.cursor].graphemes(true).count();
let target = if *key == ArrowUp {
if start == 0 {
@@ -828,11 +859,12 @@ impl DeveloperToolsState {
}
self.reveal_cursor();
}
/// 初始化内置工具对应的页面和展示状态,避免重复建立同一组工具。
/// 在线程中经本地 REPL 请求打开指定内置工具,页面复用/创建由 VM 的 developerTools 实现负责。
pub fn initialize_tools(&mut self, name: &str) {
let name = name.to_owned();
let proxy = self.proxy.clone();
thread::spawn(move || {
// 用调试字符串转义名称生成 Endor 文本,再经本地 REPL 执行;实际工具白名单由宿主能力验证。
let source = format!("ui.developerTools({name:?})");
let send = || -> std::io::Result<()> {
let mut stream = TcpStream::connect_timeout(
@@ -875,6 +907,8 @@ impl DeveloperToolsState {
self.input.clone()
};
let proxy = self.proxy.clone();
// 后台仅发送一次当前输入或 DELETE 重置;源通过正文传递,传输失败带回原 source 让 GUI 恢复输入。
// 线程成功启动不等于源执行成功,HTTP 结果由 ActivityLog 在 Console 展示。
let spawned=thread::Builder::new().name("tessera-console-client".into()).spawn(move||{
let send=||->std::io::Result<()> {
let mut stream=TcpStream::connect_timeout(&"127.0.0.1:4737".parse().unwrap(),Duration::from_secs(2))?;
@@ -886,6 +920,7 @@ impl DeveloperToolsState {
if let Err(error)=send()&&let Some(proxy)=proxy{let _=proxy.send_event(AppEvent::ConsoleFailed{message:error.to_string(),source});}
});
match spawned {
// 发送线程启动成功才清输入并加入最多80条历史;之后若网络失败由 ConsoleFailed 反馈,不能把清框当执行成功。
Ok(_) => {
if !reset {
self.history.push(self.input.clone());
@@ -906,7 +941,7 @@ impl DeveloperToolsState {
}
}
/// 根据当前输入构造本模块的派生结果,具体的验证与资源边界见函数内步骤。
/// 按当前工具生成设备比例显示列表与逻辑坐标命中布局,绘制后校正跨帧焦点和捕获。
pub fn build(
width: u32,
height: u32,
@@ -918,6 +953,7 @@ pub fn build(
if !state.open {
return (Default::default(), Default::default());
}
// 布局和命中统一用逻辑像素,最后仅显示列表按设备 scale 转换,返回 layout 仍为逻辑坐标。
let width = width as f32 / scale;
let height = height as f32 / scale;
let w = width;
@@ -946,6 +982,7 @@ pub fn build(
MUTED,
false,
);
// 锁内只克隆最多80条活动记录,接下来的文字排版/测量不持日志锁,HTTP worker 可继续更新。
let records = activity
.lock()
.unwrap()
@@ -985,6 +1022,7 @@ pub fn build(
);
// Splitters must be above toolbars, pane backgrounds and status bars for their
// whole length. Register them last so their hit priority matches their paint order.
// 分隔条最后绘制/注册,命中优先级与可见叠放相同,细线扩展命中区不会被后画的背景遮住。
for (rect, kind) in p.layout.splits.clone().into_iter().rev() {
p.ui.splitter(
rect,
@@ -996,6 +1034,7 @@ pub fn build(
);
}
p.ui.list.push(DrawCommand::PopClip);
// 把本管理 UI 当前使用的矩形、文字、裁剪、描边逐一转设备比例,几何与文字样式同倍率缩放。
let mut scaled = DisplayList::default();
for cmd in p.ui.list.commands() {
let rect =
@@ -1037,6 +1076,7 @@ pub fn build(
});
}
p.layout.widgets = p.ui.targets;
// 根据新目标集合清理失效焦点/捕获,若视觉状态变化要求再绘一帧,避免控件消失后保持旧按压外观。
state.repaint = state.interaction.reconcile(&p.layout.widgets);
(scaled, p.layout)
}