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
+30 -16
View File
@@ -20,7 +20,7 @@ pub struct Button<'a> {
pub role: Role,
}
impl<'a> Button<'a> {
/// 构造本类型并初始化其状态;资源建立和默认字段以函数体为准。
/// 创建默认启用、未选中的普通按钮描述,借用 label 而不分配文本。
pub fn new(label: &'a str) -> Self {
Self {
label,
@@ -29,17 +29,17 @@ impl<'a> Button<'a> {
role: Role::Button,
}
}
/// 设置当前控件描述的选择、启用或角色信息,供后续绘制和目标登记使用。
/// 按 builder 风格设置选中状态,返回描述供链式调用。
pub fn selected(mut self, value: bool) -> Self {
self.selected = value;
self
}
/// 设置当前控件描述的选择、启用或角色信息,供后续绘制和目标登记使用。
/// 设置启用状态,影响外观和目标的可激活资格。
pub fn enabled(mut self, value: bool) -> Self {
self.enabled = value;
self
}
/// 设置当前控件描述的选择、启用或角色信息,供后续绘制和目标登记使用。
/// 设置控件语义角色,影响焦点资格、光标及 Tab 底线等外观。
pub fn role(mut self, value: Role) -> Self {
self.role = value;
self
@@ -51,10 +51,11 @@ pub struct Ui<A> {
pub list: DisplayList,
pub targets: Vec<Target<A>>,
pub theme: Theme,
// 绘制使用跨帧交互状态的本轮副本,只查询 visual/captured;事件处理器在外部更新权威状态。
interaction: Interaction,
}
impl<A: Hash> Ui<A> {
/// 构造本类型并初始化其状态;资源建立和默认字段以函数体为准。
/// 建立空显示列表和目标集合,保存本轮主题与交互状态快照。
pub fn new(theme: Theme, interaction: Interaction) -> Self {
Self {
list: DisplayList::default(),
@@ -63,7 +64,7 @@ impl<A: Hash> Ui<A> {
interaction,
}
}
/// 使用当前主题绘制控件填充、轮廓或文字原语。
/// 追加无圆角填充矩形命令;不注册交互目标。
pub fn fill(&mut self, r: Rect, color: Color) {
self.list.push(DrawCommand::FillRoundedRect {
rect: r,
@@ -71,9 +72,10 @@ impl<A: Hash> Ui<A> {
color,
});
}
/// 使用当前主题绘制控件填充、轮廓或文字原语。
/// 追加向内收缩的圆角描边,使传入矩形作为控件外边界。
fn outline(&mut self, r: Rect, color: Color, width: f32) {
self.list.push(DrawCommand::StrokeRoundedRect {
// 描边以路径中心为基准,向内缩半个线宽,使描边整体尽量位于传入矩形内;尺寸钳非负。
rect: Rect::new(
r.x + width / 2.0,
r.y + width / 2.0,
@@ -85,7 +87,7 @@ impl<A: Hash> Ui<A> {
color,
});
}
/// 使用当前主题绘制控件填充、轮廓或文字原语。
/// 追加等宽或界面字体文字命令;调用方负责裁剪与可用宽度。
pub fn label(&mut self, x: f32, y: f32, value: &str, color: Color, code: bool) {
self.list.push(DrawCommand::Text {
origin: Point::new(x, y),
@@ -112,6 +114,7 @@ impl<A: Hash> Ui<A> {
selected: bool,
enabled: bool,
) -> VisualState {
// 先取得上帧输入对应的视觉状态,再登记本帧目标;绘制本身不触发 action。
let response = self.interaction.visual(id, selected, enabled);
self.targets.push(Target {
id,
@@ -122,8 +125,9 @@ impl<A: Hash> Ui<A> {
});
response
}
/// 绘制对应宿主管理控件,并使用同一矩形注册命中/捕获所需的交互信息。
/// 按视觉状态绘制控件背景和焦点轮廓;本方法不注册目标。
fn surface(&mut self, rect: Rect, s: VisualState, base: Option<Color>) {
// 背景优先级为禁用、按下、悬停、选中、默认;焦点轮廓单独绘制,可与选中同时存在。
let color = if !s.enabled {
base
} else if s.pressed {
@@ -142,8 +146,9 @@ impl<A: Hash> Ui<A> {
self.outline(rect, self.theme.accent, 1.5);
}
}
/// 绘制对应宿主管理控件,并使用同一矩形注册命中/捕获所需的交互信息。
/// 登记按钮目标,绘制状态背景、裁剪后的标签及可选 Tab 底线,返回组合视觉状态。
pub fn button(&mut self, rect: Rect, action: A, button: Button<'_>) -> VisualState {
// 默认以 action 哈希为稳定身份;同一帧多个独立控件若 action 完全相同会共享身份,调用方需合理区分。
let id = WidgetId::new(&action);
let s = self.register(
id,
@@ -155,6 +160,7 @@ impl<A: Hash> Ui<A> {
);
self.surface(rect, s, None);
self.list.push(DrawCommand::PushClip(rect));
// 扣掉左右各 8 的内边距后按真实字体截断,并用 PushClip 保证文字和标签底线不越出按钮。
let label = text::fit(
button.label,
(rect.width - 16.0).max(0.0),
@@ -175,6 +181,7 @@ impl<A: Hash> Ui<A> {
},
false,
);
// 仅 Tab 角色在选中时显示底部强调线,普通按钮选中只走 surface 背景。
if s.selected && button.role == Role::Tab {
self.fill(
Rect::new(rect.x, rect.y + rect.height - 2.0, rect.width, 2.0),
@@ -184,7 +191,7 @@ impl<A: Hash> Ui<A> {
self.list.push(DrawCommand::PopClip);
s
}
/// 绘制对应宿主管理控件,并使用同一矩形注册命中/捕获所需的交互信息。
/// 登记文本输入角色并绘制背景和焦点/悬停描边,不负责实际文本与光标。
pub fn text_field(&mut self, rect: Rect, action: A, focused: bool) {
let s = self.register(
WidgetId::new(&action),
@@ -194,6 +201,7 @@ impl<A: Hash> Ui<A> {
false,
true,
);
// 文本框固定白底,外部 focused 或键盘焦点都使用强调色描边,悬停次之。
self.surface(rect, s, Some(theme::BG));
self.outline(
rect,
@@ -208,7 +216,8 @@ impl<A: Hash> Ui<A> {
);
}
/// A terminal prompt shares its surface with output; its caret is the focus cue.
/// 绘制对应宿主管理控件,并使用同一矩形注册命中/捕获所需的交互信息。
/// 只登记无边框终端输入的交互区域,外观由调用方绘制。
// 终端输入与输出共享背景,只注册文本输入命中区,不绘制框线或文字,光标由 Console 负责。
pub fn inline_input(&mut self, rect: Rect, action: A) {
self.register(
WidgetId::new(&action),
@@ -219,7 +228,8 @@ impl<A: Hash> Ui<A> {
true,
);
}
/// 绘制对应宿主管理控件,并使用同一矩形注册命中/捕获所需的交互信息。
/// 分别接受行背景区域和可见命中区域,登记行选择并绘制其状态背景。
// 行背景可绘制完整行,但 hit 可裁到可见部分;不要把裁剪区外的行注册成可点击区域。
pub fn row(&mut self, paint: Rect, hit: Rect, action: A, selected: bool) {
let s = self.register(
WidgetId::new(&action),
@@ -231,7 +241,7 @@ impl<A: Hash> Ui<A> {
);
self.surface(paint, s, None);
}
/// 绘制对应宿主管理控件,并使用同一矩形注册命中/捕获所需的交互信息。
/// 登记色块目标,绘制按压变暗、外圈及选中勾号。
pub fn swatch(&mut self, rect: Rect, action: A, color: Color, selected: bool) {
let s = self.register(
WidgetId::new(&action),
@@ -241,6 +251,7 @@ impl<A: Hash> Ui<A> {
selected,
true,
);
// 滚动条手柄捕获时保持强调色,悬停使用混色,其余用中性底色;实际偏移换算由调用方处理。
self.fill(
rect,
if s.pressed {
@@ -249,6 +260,7 @@ impl<A: Hash> Ui<A> {
color
},
);
// 色块在交互或选中时增加外圈;按下变暗且加粗,选中再绘制勾号。
if s.hovered || s.focused || selected {
self.outline(
Rect::new(
@@ -269,8 +281,9 @@ impl<A: Hash> Ui<A> {
self.label(rect.x + 10.0, rect.y + 6.0, "✓", theme::BG, false);
}
}
/// 绘制对应宿主管理控件,并使用同一矩形注册命中/捕获所需的交互信息。
/// 登记扩大的拖动命中区,绘制捕获/悬停强调线。
pub fn splitter(&mut self, rect: Rect, id: WidgetId, axis: Axis) {
// 分隔线命中区四边扩展 3,提高细线可拖动性;真实绘制线宽与命中区域独立。
let hit = Rect::new(
rect.x - 3.0,
rect.y - 3.0,
@@ -278,6 +291,7 @@ impl<A: Hash> Ui<A> {
rect.height + 6.0,
);
let mut s = self.register(id, hit, Role::Splitter(axis), None, false, true);
// 分隔条捕获后即使拖出命中区仍显示按压态,不采用普通按钮“拖出取消外观”的规则。
s.pressed |= self.interaction.captured(id);
let color = if s.pressed || s.hovered {
self.theme.accent
@@ -294,7 +308,7 @@ impl<A: Hash> Ui<A> {
};
self.fill(line, color);
}
/// 绘制对应宿主管理控件,并使用同一矩形注册命中/捕获所需的交互信息。
/// 登记滚动手柄目标并绘制其状态颜色,偏移和拖动倍率由外部维护。
pub fn scrollbar(&mut self, rect: Rect, id: WidgetId, axis: Axis) {
let mut s = self.register(id, rect, Role::Scrollbar(axis), None, false, true);
s.pressed |= self.interaction.captured(id);