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| {