docs: explain sidebar and native window coordination

This commit is contained in:
2026-11-12 19:22:21 +08:00
parent d8dc24da26
commit b95912d840
2 changed files with 77 additions and 1 deletions
+20 -1
View File
@@ -15,12 +15,14 @@ use crate::{
// 展开侧栏固定逻辑宽度;实际设备像素比例由后续显示列表缩放处理。
pub const WIDTH: f32 = 256.0;
// 顶部标题/原生按钮区域高度,app 的拖窗判断和 native_chrome 的系统按钮对齐共同使用。
pub const HEADER: f32 = 40.0;
// macOS 标题行预留原生三键安全区域,其他平台无需这段横向留白。
pub const CONTROLS: f32 = if cfg!(target_os = "macos") { 86.0 } else { 0.0 };
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
/// 侧栏释放激活后要执行的管理动作,绘制本身只登记它。
// app::sidebar_action 执行这些已确认动作;页面 ID 来自本窗口的 Tab 投影,不是 VM 对象引用。
pub enum Action {
Toggle,
NewPage,
@@ -32,14 +34,17 @@ pub enum Action {
/// 侧栏开合、控件交互和本帧目标集合,决定实际占用页面宽度。
pub struct State {
pub open: bool,
// 跨帧保存悬停、键盘焦点和按下捕获;目标矩形则由每次 draw 重建。
pub interaction: Interaction,
// 最近绘制帧的逻辑命中集合,app 的指针及键盘事件使用,与显示列表保持同帧。
pub targets: Vec<Target<Action>>,
// 只滚动普通页面列表,顶部工具入口、折叠按钮和底部工作区标签保持固定。
pub scroll: f32,
}
impl Default for State {
/// 建立类型约定的初始值,供尚未发布或尚未交互的状态使用。
/// 建立默认展开的侧栏,交互目标等第一次 draw 时按实际页面重建。
// TesseraApp 初始化时创建,默认展开、列表在起点,尚未绘制时没有交互目标。
fn default() -> Self {
Self {
open: true,
@@ -52,11 +57,13 @@ impl Default for State {
impl State {
/// 返回展开侧栏占据的逻辑宽度,折叠时页面收回这部分空间。
// scene 合成页面时用作横向偏移,app 发布布局视口时从窗口逻辑宽度扣除;折叠值为零。
pub fn left(&self) -> f32 {
if self.open { WIDTH } else { 0.0 }
}
/// 判断指针是否落入宿主侧栏/展开按钮区域,保护页面输入边界。
// app 路由页面指针、滚轮和键盘焦点时调用,判断宿主占用区而非只判断是否命中某个按钮。
pub fn covers(&self, point: Point) -> bool {
// 展开时整个侧栏横向带均拦截页面输入,y 的窗口有效范围由外层事件入口保证。
// 折叠时只覆盖顶部三键安全区与展开按钮,不继续挡住左侧整列页面。
@@ -68,6 +75,7 @@ impl State {
}
/// 绘制工具入口、页面列表和展开控制,同时登记稳定的交互目标。
// scene::build_scene 最后调用以覆盖宿主侧栏;height 为逻辑高度,返回命令由外层再统一乘设备 scale。
pub fn draw(
&mut self,
tabs: &[Tab],
@@ -76,6 +84,7 @@ impl State {
) -> DisplayList {
// 每帧重新生成控件目标与显示列表,保留 Interaction 的稳定身份状态,而不是复用上帧屏幕矩形。
let mut ui = Ui::new(Theme::new(accent), self.interaction.clone());
// 只有展开态铺侧栏背景,折叠态不画整列底色,让业务页面能使用原侧栏区域。
if self.open {
ui.fill(Rect::new(0.0, 0.0, WIDTH, height), theme::BAR);
}
@@ -86,6 +95,7 @@ impl State {
CONTROLS + 4.0
};
// Draw a sidebar icon with primitives so its shape does not depend on fonts.
// 展开按钮无文字标签,下面用描边和竖线组合图标;按钮矩形仍负责稳定 Toggle 命中。
ui.button(
Rect::new(toggle_x, 6.0, 30.0, 28.0),
Action::Toggle,
@@ -105,6 +115,7 @@ impl State {
Action::NewPage,
Button::new("+ 新建页面"),
);
// 四个固定工具入口不随页面列表滚动,name 作为 Action 参数,label 只是显示文字。
for (index, (name, label)) in [
("Console", "Console"),
("Sources", "Sources"),
@@ -125,6 +136,7 @@ impl State {
);
}
ui.label(20.0, 303.0, "页面", theme::MUTED, false);
// 普通页面可滚区域从固定工具区下方开始,底部为工作区标签留白;极矮窗口面积钳到零。
let area = Rect::new(8.0, 333.0, WIDTH - 16.0, (height - 383.0).max(0.0));
// 开发工具已由固定入口展示,因此页面列表仅收集普通页,保持原注册表顺序。
let pages: Vec<_> = tabs
@@ -136,10 +148,13 @@ impl State {
.scroll
.clamp(0.0, (pages.len() as f32 * 36.0 - area.height).max(0.0));
ui.list.push(DrawCommand::PushClip(area));
// 页面行按注册表顺序排,先减 scroll 得到本帧 y,再检查整行是否可见。
for (index, tab) in pages.into_iter().enumerate() {
// 每行步长 36、按钮高度 32,空出的 4 单位间距同样属于滚动内容节奏。
let y = area.y + index as f32 * 36.0 - self.scroll;
// Register only fully visible rows: paint clipping must match input.
// 当前实现完全跳过部分可见行,绘制与注册都不发生;Clip 仍保护其他原语不溢出列表区域。
// 部分可见行整行跳过,既不产生切页按钮也不产生关闭按钮,防止不可见片段仍可激活。
if y < area.y || y + 32.0 > area.y + area.height {
continue;
}
@@ -149,12 +164,14 @@ impl State {
Action::Activate(tab.id),
Button::new(&tab.title).selected(tab.active),
);
// 关闭按钮与整行激活按钮使用不同 Action,避免点关闭同时触发切页。
ui.button(
Rect::new(WIDTH - 40.0, y, 28.0, 32.0),
Action::Close(tab.id),
Button::new("×"),
);
}
// 列表结束先恢复 clip,底部工作区标签保持固定位置且不继承页面列表裁剪。
ui.list.push(DrawCommand::PopClip);
ui.label(20.0, height - 32.0, "本地工作区", theme::MUTED, false);
}
@@ -171,9 +188,11 @@ mod tests {
#[test]
/// 先展开绘制再折叠重绘,检查交互目标只剩 Toggle、页面左侧让宽归零,其他区域不再拦截指针。
fn collapsing_removes_every_host_target_except_the_toggle() {
// 以生产默认展开状态建立初始目标,再折叠重建,验证目标清理而不是只验证绘制列表变短。
let mut sidebar = State::default();
sidebar.draw(&[], 800.0, theme::PALETTE[0]);
assert!(sidebar.targets.len() > 1);
// 第二次 draw 必须移除旧工具/页面目标,Interaction 也应对新集合重新校正捕获。
sidebar.open = false;
sidebar.draw(&[], 800.0, theme::PALETTE[0]);
// 折叠后仅保留 Toggle,且页面不再让出左宽;顶部按钮区域之外的指针不被侧栏拦截。