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
+16 -1
View File
@@ -9,8 +9,9 @@ use std::hash::{Hash, Hasher};
/// 由语义 key 生成的稳定控件身份,跨帧移动和文字变化不应改变它。
pub struct WidgetId(u64);
impl WidgetId {
/// 构造本类型并初始化其状态;资源建立和默认字段以函数体为准。
/// 对调用方语义 key 求哈希,生成不随控件位置或标签变化的跨帧 WidgetId;相同 key 会得到同一身份。
pub fn new(key: impl Hash) -> Self {
// 语义 key 哈希为会话内身份;不依赖布局坐标,但调用方仍需避免重复 key,哈希并非全局唯一保证。
let mut hash = std::collections::hash_map::DefaultHasher::new();
key.hash(&mut hash);
Self(hash.finish())
@@ -37,6 +38,7 @@ pub enum Role {
impl Role {
/// 判断控件角色是否可以接受键盘焦点。
fn focusable(self) -> bool {
// 行用于指针选择,分隔条/滚动条用于拖动,这三类不加入键盘 Tab 焦点循环。
!matches!(self, Self::Splitter(_) | Self::Scrollbar(_) | Self::Row)
}
}
@@ -77,15 +79,19 @@ pub struct VisualState {
pub struct Interaction {
pointer: Option<Point>,
hovered: Option<WidgetId>,
// 按下时捕获的控件;即使指针移动到别处,也保留原身份直到释放或取消。
pointer_active: Option<WidgetId>,
// 键盘按下时的焦点身份;释放时再次匹配,避免焦点已变却激活新控件。
key_active: Option<WidgetId>,
focused: Option<WidgetId>,
// 区分键盘导航和鼠标获得焦点,visual 仅为键盘来源显示焦点外观。
keyboard_focus: bool,
}
impl Interaction {
/// 按逆绘制顺序选择指针处的管理控件,避免重叠控件同时激活。
pub fn hit<'a, A>(&self, targets: &'a [Target<A>]) -> Option<&'a Target<A>> {
let p = self.pointer?;
// 几何命中包含禁用控件,因此上层禁用项会挡住下层项;是否允许操作由 press/cursor 分别判断。
targets.iter().rev().find(|t| t.rect.contains(p))
}
/// 更新指针与悬停目标,但不在移动时直接触发点击。
@@ -95,11 +101,13 @@ impl Interaction {
}
/// 清除离开窗口后的指针/悬停状态。
pub fn pointer_left(&mut self) {
// 离开窗口只清位置和悬停,保留捕获身份供外层拖动流程使用;完整失焦由 blur 处理。
self.pointer = None;
self.hovered = None;
}
/// 捕获启用控件的稳定身份,并按角色更新键盘焦点。
pub fn press<A: Clone>(&mut self, targets: &[Target<A>]) -> Option<Target<A>> {
// 鼠标按下撤销旧键盘激活并关闭键盘焦点外观;点空白或不可聚焦角色会清除 focused。
self.key_active = None;
self.keyboard_focus = false;
let target = self.hit(targets).filter(|t| t.enabled).cloned();
@@ -109,6 +117,7 @@ impl Interaction {
}
/// 只有释放时仍处于原启用目标内才返回 action,拖出后释放不触发。
pub fn release<A: Clone>(&mut self, targets: &[Target<A>]) -> Option<A> {
// take 先消费捕获,保证同一次按下最多激活一次;TextField 不走按钮 release action。
let active = self.pointer_active.take()?;
self.hit(targets)
.filter(|t| t.enabled && t.id == active && t.role != Role::TextField)
@@ -134,6 +143,7 @@ impl Interaction {
self.focused,
self.key_active,
);
// 重建 UI 后必须仍存在且启用才保留焦点/捕获;hover 则依据当前指针重新命中,包含禁用项。
let exists = |id| targets.iter().any(|t| t.id == id && t.enabled);
self.focused = self.focused.filter(|id| exists(*id));
self.pointer_active = self.pointer_active.filter(|id| exists(*id));
@@ -155,6 +165,7 @@ impl Interaction {
}
/// 沿启用且可聚焦的目标循环导航,支持正向与反向遍历。
pub fn focus_next<A: Clone>(&mut self, targets: &[Target<A>], back: bool) -> Option<Target<A>> {
// 键盘导航先取消未完成按压,避免切换焦点后补发旧激活;候选顺序沿本帧目标顺序。
self.cancel();
self.keyboard_focus = true;
let candidates = targets
@@ -166,6 +177,7 @@ impl Interaction {
return None;
}
let current = candidates.iter().position(|t| Some(t.id) == self.focused);
// 有当前焦点时环绕前进/后退;无有效焦点时正向选首项、反向选末项。
let index = match current {
Some(i) if back => (i + candidates.len() - 1) % candidates.len(),
Some(i) => (i + 1) % candidates.len(),
@@ -185,6 +197,7 @@ impl Interaction {
}
/// 结束键盘激活并按有效控件身份返回操作。
pub fn key_release<A: Clone>(&mut self, targets: &[Target<A>]) -> Option<A> {
// 只有释放时仍聚焦相同启用目标才返回动作;take 防止重复 key-up 重复激活。
let active = self.key_active.take()?;
self.focused(targets)
.filter(|t| t.id == active)
@@ -192,6 +205,7 @@ impl Interaction {
}
/// 组合悬停、按下、焦点、选中和启用状态,供控件选择正确样式。
pub fn visual(&self, id: WidgetId, selected: bool, enabled: bool) -> VisualState {
// 禁用控件不显示交互状态;指针按压需仍悬停才显示 pressed,拖出后保留捕获但取消按下外观。
let hovered = enabled && self.hovered == Some(id);
VisualState {
hovered,
@@ -208,6 +222,7 @@ impl Interaction {
}
/// 按命中角色选择系统光标,例如文本、分隔条或可点击按钮。
pub fn cursor<A>(&self, targets: &[Target<A>]) -> Cursor {
// 拖动分隔条/滚动条时优先沿用捕获目标的光标,避免指针跨过其他控件导致拖动光标跳变。
let target = self
.pointer_active
.and_then(|id| {
+5 -2
View File
@@ -1,9 +1,12 @@
//! 宿主管理控件的共享组件入口。主题、绘制原语和跨帧交互状态分离,用户 Endor 页面不依赖这里的控件树。
//!
//! Tessera's host management widgets. No Endor AST, VM, UiNode or ui_bridge dependency.
//! Shares only low-level drawing, font shaping and geometry with guest content.
//! 此模块不依赖 Endor AST、VM、UiNode 或 ui_bridge;只复用底层绘图、字体塑形和几何。
// 跨帧保存 hover/press/focus,管理命中目标、键盘导航与控件视觉状态。
mod interaction;
// 提供管理界面统一的颜色、尺寸和排版常量,避免各工具各自定义主题。
pub mod theme;
// 把控件状态转换为显示列表和交互目标;本模块不承担用户源程序的执行。
mod widgets;
// 向上层隐藏内部文件布局,统一导出交互状态与控件类型。
pub use interaction::{Axis, Cursor, Interaction, Role, Target, VisualState, WidgetId};
pub use widgets::{Button, Ui};
+10 -4
View File
@@ -1,6 +1,7 @@
//! 宿主控件的颜色与状态调色。根据背景、强调色和交互状态生成可读颜色,不改变业务状态。
//!
use crate::display_list::Color;
// 宿主管理界面的白色基础背景;这些常量不会修改业务页面自己的颜色。
pub const BG: Color = Color::rgb(255, 255, 255);
// A visibly separate chrome layer against the warm, near-white content canvas.
pub const BAR: Color = Color::rgb(230, 233, 237);
@@ -9,6 +10,7 @@ pub const TEXT: Color = Color::rgb(35, 42, 53);
pub const MUTED: Color = Color::rgb(103, 114, 130);
pub const ERROR: Color = Color::rgb(175, 42, 49);
pub const OK: Color = Color::rgb(31, 121, 80);
// 供设置页选择的六个强调色候选;Theme::new 还会按可读性规则调整传入颜色。
pub const PALETTE: [Color; 6] = [
Color::rgb(22, 113, 213),
Color::rgb(0, 132, 143),
@@ -23,27 +25,29 @@ pub struct Theme {
pub accent: Color,
}
impl Theme {
/// 构造本类型并初始化其状态;资源建立和默认字段以函数体为准。
/// 保存经过亮度限制的强调色,所有控件状态色都从该色与管理界面背景混合得到。
pub fn new(accent: Color) -> Self {
// 构造时统一压低过亮强调色,之后 hover/pressed 等样式都从调整后的 accent 派生。
Self {
accent: readable_accent(accent),
}
}
/// 从当前主题生成对应交互状态颜色,保持控件在状态变化时的视觉一致性。
/// 以 10% 强调色混合背景,得到未悬停的柔和选中底色。
pub fn soft(self) -> Color {
mix(BG, self.accent, 0.10)
}
/// 从当前主题生成对应交互状态颜色,保持控件在状态变化时的视觉一致性。
/// 以 17% 强调色混合背景,得到比 soft 更明显的悬停底色。
pub fn hover(self) -> Color {
mix(BG, self.accent, 0.17)
}
/// 从当前主题生成对应交互状态颜色,保持控件在状态变化时的视觉一致性。
/// 以 29% 强调色混合背景,增强按下状态;混色输出始终不透明。
pub fn pressed(self) -> Color {
mix(BG, self.accent, 0.29)
}
}
/// 按比例混合颜色通道,作为状态颜色的基础运算。
pub fn mix(a: Color, b: Color, amount: f32) -> Color {
// 逐 RGB 通道线性插值并四舍五入,amount 钳到 [0,1];结果使用 rgb,输出 alpha 固定为 255。
let channel =
|a: u8, b: u8| (a as f32 + (b as f32 - a as f32) * amount.clamp(0.0, 1.0)).round() as u8;
Color::rgb(
@@ -54,6 +58,8 @@ pub fn mix(a: Color, b: Color, amount: f32) -> Color {
}
/// 根据背景选择可读的强调色,供选中与焦点状态使用。
pub fn readable_accent(mut c: Color) -> Color {
// 用 299/587/114 加权亮度做简单阈值判断,过亮时每轮各通道乘 0.94 变暗。
// 这是启发式规则,不是对任意背景执行通用对比度求解。
while (c.red as u32 * 299 + c.green as u32 * 587 + c.blue as u32 * 114) / 1000 > 155 {
c = Color::rgb(
(c.red as f32 * 0.94) as u8,
+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);