docs: 记录极简页分组切换手势(README)+ 交互类改动的真实输入验证要求(AGENTS)

README 新增「极简页分组切换(点击 / 滑动 / 键盘)」:四种输入、判定阈值、clamp 边界、
只对页框内元素做动画、页签行跟随(含实测数字 1306 > 828)、防误触、以及
"接 Dashy DOM 契约、类名变化会静默失效 + data-navi-swipe 自检"这一限制。
AGENTS §5 补充:交互类改动必须用真实输入(CDP 触摸注入/真实鼠标/wheel deltaX)验证,
断言"切换真的发生"而非"监听器已挂载"——本项目实测踩过事件全到达但被自建拦截器吞掉的坑。
This commit is contained in:
HomeDash Bot
2026-09-12 22:10:05 +08:00
parent 86aced0c4a
commit ba22d3a1de
2 changed files with 33 additions and 0 deletions

View File

@ -253,6 +253,14 @@ printf '已配置域名=%s 未知域名=%s healthz=%s schema=%s 跳转=%s\n' "$T
| schema | `200` | 镜像过旧(不含新接口),或前缀打成 `/api/` |
| HTTP→HTTPS 跳转 | `302` | 跳转端口/开关配置问题 |
**交互类改动必须用真实输入验证,不能只查属性**(例如 `/minimal` 的左右滑动切换分组):
用 CDP 注入触摸(`Emulation.setTouchEmulationEnabled` + `Input.dispatchTouchEvent`)、
真实鼠标 `mouse.down/move/up`、`mouse.wheel(deltaX, 0)`;断言"切换真的发生"
(读 `.minimal-headings-row > .minimal-section-heading.headings` 中 `.selected` 的下标变化),
并要求 `<html>` 上 `data-navi-swipe="on"`、`pageerror` 为 0。
只断言"事件到了 / 监听器挂了"**不算通过** —— 本项目实测踩过:事件全都到达,
但自建拦截器把自己的切换 click 吞了,表现为"滑了没反应"。
附加(有数据时):
```bash

View File

@ -472,6 +472,31 @@ NAVI_HOST=user@host NAVI_SSH_PASS='<密码>' bash deploy/zd-host.sh v54
- **可达性状态点已关闭**(`statusCheck: false`):统一入口下探测会命中登录 302,结论不可信,
因此不显示而不是显示错的
### 极简页分组切换(点击 / 滑动 / 键盘)
`/minimal` 的分组(页签)除点击外,还支持左右滑动切换。四种输入:
| 输入 | 操作 | 实现 |
| --- | --- | --- |
| 触屏 | 在内容区左右滑动 | `pointerdown/move/up` |
| 触控板 | 双指横滑 | `wheel` 的 `deltaX` 累积(每次手势只切一次) |
| 鼠标 | 按住左键横向拖动 | `pointerdown/move/up` |
| 键盘 | `←` / `→` | 不在输入框内、无弹窗时生效 |
- **判定**:横移 ≥ 56px 且 `|dx| > 1.5|dy|` 才切换;先判出 `|dy| > |dx|` 则直接让给竖向滚动
- **边界**:到第一个/最后一个分组即停(clamp),只给一次轻微回弹提示
- **动画**:只对**页框内的元素**(`.minimal-section-inner.selected > *`)淡出淡入;
页签行与框体本身不动。`prefers-reduced-motion` 下不做动画。用 keyframes 而非 transition,
避免覆盖卡片自带的 `transition: all`
- **页签行跟随**:切换后把选中页签滚进可视区。页签行本身可横向滚动
(实测 8 个分组宽 1306px > 可视 828px),不跟随的话选中项会跑到视口外,看起来像"没切换"
- **防误触**:横拖超过 20px 后吞掉紧随的一次 click,避免误开卡片链接;
手势起点若落在可横向滚动的容器或输入框内,直接放行不接管
- **实现契约**:接的是 Dashy 的 DOM —— `.minimal-headings-row > .minimal-section-heading.headings`,
当前项带 `.selected`,切换 = 对该元素派发一次真实 click。
**Dashy 升级若改类名会静默失效**;加载时匹配不到标签会在 `<html>` 上写
`data-navi-swipe="unavailable"`(可编程检查,不刷控制台)
### 回滚
- 容器:`docker start portal-nginx portal-auth` + 把 `navi` 换回 bridge 版本(镜像 `homedash:ui-*` 均在)