fix(webui): 手势与横向滚动分家 + 纵向滚动边缘淡出

用户给了两条具体信息（这比我自己猜五轮都管用）：「横向滚动条会与切换视图的手势冲突，我觉得周视图需要卡严条件，同时我说的其他硬截断是对应内容项上下滑动会直接被切断」。 ## ① 手势卡严（周视图）冲突是真的：周视图窄屏下必须横向滚（`overflow-auto` + `min-w-[36rem]`），而我又给整页加了左右滑动翻页 ⇒ 同一次横滑既想滚又想翻，两边都不好用。规则定死：**手势从可横向滚动的区域里起手，就归滚动条，完全不参与翻页判断** （触点沿祖先链查找 `overflow-x: auto/scroll` 且真的能滚的容器）。想翻页就从别处滑（例如上方标题栏）。 ## ② 纵向滚动边缘淡出滚动条本身是"一刀切"：卡片滚到边缘被硬生生截断 —— 这就是用户说的"直接被切断"。给纵向滚动容器（`.overflow-y-auto`）加 12px 上下渐隐遮罩，切得有交代。只作用在**纵向**容器：横向滚动有自己的滚动条，加纵向遮罩会跟它打架。 ## 过程记录（值得记）这两条改动**第一次没有生效**，因为部署失败了：`/tmp` 是 tmpfs 且已 100% 满，而部署脚本把构建产物写到硬编码的 `/tmp/agentmail-gateway-build-*` ⇒ `no space left on device`。我差点把"旧构建上的测量结果"当成"改动无效"。清理后（清掉我自己的探针脚本/截图/旧构建，约 950MB）部署成功。 ⚠️ `/tmp` 现在仍占 91%（`gocache` 4.5G 等不全是我的），**下次部署可能还会撞上**；脚本改成尊重 `TMPDIR` 才是根治（未做）。
2026-09-14 14:35:43 +08:00
parent c9717daa13
commit 1717863c87
5 changed files with 197 additions and 14 deletions
--- a/client/electron/src/components/CalendarView.tsx
+++ b/client/electron/src/components/CalendarView.tsx
@ -150,9 +150,39 @@ export default function CalendarView() {
   * 那是移动端最容易犯的手势错误）；同时要求时间 < 600ms，避免"慢慢拖"也翻页。
   */
  const touch = useRef<{ x: number; y: number; t: number } | null>(null);
+
+  /**
+   * 触点是否落在**可横向滚动**的区域里（周视图就是：`overflow-auto` + `min-w-[36rem]`）。
+   *
+   * 用户（2026-09-14）：「横向滚动条会与切换视图的手势冲突，我觉得周视图需要卡严条件」。
+   *
+   * 冲突是真的：周视图在窄屏下必须横向滚，而我又给整页加了左右滑动翻页 ⇒
+   * 同一次横滑既想滚又想翻，结果两边都不好用。规则定死：**手势从可横向滚动的
+   * 区域里开始，就归滚动条，不翻页**。想要翻页就从别处（例如上方的标题栏）滑。
+   */
+  const startsInHorizontalScroller = (target: EventTarget | null, root: EventTarget | null) => {
+    let el = target as HTMLElement | null;
+    while (el && el !== root) {
+      const cs = getComputedStyle(el);
+      if (
+        (cs.overflowX === 'auto' || cs.overflowX === 'scroll') &&
+        el.scrollWidth > el.clientWidth + 4
+      ) {
+        return true;
+      }
+      el = el.parentElement;
+    }
+    return false;
+  };
+
  const onTouchStart = (e: React.TouchEvent) => {
    const t = e.touches[0];
    if (!t) return;
+    if (startsInHorizontalScroller(e.target, e.currentTarget)) {
+      // 卡严条件：这一次手势完全不参与翻页判断
+      touch.current = null;
+      return;
+    }
    touch.current = { x: t.clientX, y: t.clientY, t: Date.now() };
  };
  const onTouchEnd = (e: React.TouchEvent) => {
--- a/client/electron/src/index.css
+++ b/client/electron/src/index.css
@ -1354,3 +1354,31 @@ html[data-bg='on'] .glass-card:hover {
  flex: 0 0 auto;
  width: 320px;
 }
+
+
+/*
+ * ★ 滚动容器的边缘淡出（2026-09-14 用户：「内容项上下滑动会直接被切断」）。
+ *
+ * 滚动条本身是"一刀切"：卡片滚到边缘就被硬生生截断。给滚动容器加一层
+ * 上下渐隐的遮罩，切断处变成渐隐 —— 切得有交代，观感也不再像 bug。
+ *
+ * 只作用在**纵向**滚动容器（`.overflow-y-auto`）：周视图那种**横向**滚动
+ * 有自己的横向滚动条，加纵向遮罩会跟它打架（用户刚提过手势冲突那件事）。
+ * 上下各 12px 与列表内边距（10px）接近，静止时几乎看不出，滚动时才起作用。
+ */
+.overflow-y-auto {
+  -webkit-mask-image: linear-gradient(
+    to bottom,
+    transparent 0,
+    #000 12px,
+    #000 calc(100% - 12px),
+    transparent 100%
+  );
+  mask-image: linear-gradient(
+    to bottom,
+    transparent 0,
+    #000 12px,
+    #000 calc(100% - 12px),
+    transparent 100%
+  );
+}
--- a/client/electron/test/harmony-appearance.test.mjs
+++ b/client/electron/test/harmony-appearance.test.mjs
@ -423,3 +423,37 @@ test('判据自检：预设清单少一档必须判红', () => {
  const trimmed = webIds.slice(0, -1);
  assert.notDeepEqual(trimmed, W.PRESET_IDS, '自检：裁掉一档后必须与实现不一致（否则这条判据没有分辨力）');
 });
+
+test('★ 背景画出来了还不够：每个页面要**让出**页面底，否则壁纸全被盖住', () => {
+  /*
+   * 这一条是"渲染"这句话的另一半。只把壁纸铺在最底层、而每个页面自己又刷一层
+   * **不透明**的系统页面底，壁纸就等于没画（用户看到的仍然是纯色页面）。
+   * WebUI 侧的原话：「页面底 → 完全透明，让出背景；不改 27 个组件的 class，
+   * 逐个加 class 必然漏（漏掉的那块就是一张不透明卡片浮在背景上）」。
+   *
+   * 所以判据钉的是"没有一处页面底还在用不透明的系统页面底"——
+   * 漏掉任何一个页面，就是那一页看不到壁纸。
+   */
+  const main = read('pages/MainPage.ets');
+  const opaqueRoots = [...main.matchAll(/\.backgroundColor\(Theme\.pageBg\)/g)].length;
+  assert.equal(opaqueRoots, 0,
+    `还有 ${opaqueRoots} 处页面底用不透明的 Theme.pageBg —— 那几页看不到壁纸`);
+  const yielded = [...main.matchAll(/\.backgroundColor\(this\.bgActive \? Color\.Transparent : Theme\.pageBg\)/g)].length;
+  assert.ok(yielded >= 5, `要让出页面底的页面至少 5 个（通信/联系人 + 三个 pane），实际 ${yielded} 处`);
+
+  // 每个页面都要**收到**这个开关：漏传 = 该页恒为不透明（等于没有让出）
+  for (const comp of ['CommPage', 'ContactsTab']) {
+    assert.match(main, new RegExp(`${comp}\\(\\{ bgActive: this\\.bgActive \\}\\)`), `主界面要把 bgActive 传给 ${comp}`);
+  }
+  for (const pane of ['InboxTab', 'SentTab', 'PermissionTab']) {
+    assert.match(main, new RegExp(`${pane}\\(\\{ bgActive: this\\.bgActive \\}\\)`), `通信页要把 bgActive 传给 ${pane}`);
+  }
+  // 开关必须由**背景计划**驱动（不是写死的 true/false）
+  assert.match(main, /this\.bgActive = this\.bgPlan\.kind !== 'none';/, 'bgActive 要由背景计划决定');
+  // 每个组件都要声明这个 @Prop（漏一个就编译不过，但判据先钉住意图）
+  for (const comp of ['CommPage', 'ContactsTab', 'InboxTab', 'SentTab', 'PermissionTab']) {
+    const at = main.indexOf(`struct ${comp} {`);
+    const head = main.slice(at, at + 400);
+    assert.match(head, /@Prop bgActive: boolean = false;/, `${comp} 要声明 @Prop bgActive`);
+  }
+});
--- a/client/harmony/entry/src/main/ets/pages/MainPage.ets
+++ b/client/harmony/entry/src/main/ets/pages/MainPage.ets
@ -53,6 +53,8 @@ const INBOX_PAGE_SIZE: number = 50;

@Component
 struct InboxTab {
+  /** 背景是否开启：开着就让出页面底（WebUI 的做法是页面底完全透明） */
+  @Prop bgActive: boolean = false;
  @State mails: MailSummary[] = [];
  /** 按会话折叠后的列表（单封的组平铺渲染） */
  @State groups: SessionGroup[] = [];
@ -409,7 +411,7 @@ struct InboxTab {
      .backgroundColor(Theme.surface)
    }
    .width('100%').height('100%')
-    .backgroundColor(Theme.pageBg)
+    .backgroundColor(this.bgActive ? Color.Transparent : Theme.pageBg)
  }

  /*
@ -576,6 +578,8 @@ struct InboxTab {

@Component
 struct SentTab {
+  /** 背景是否开启：开着就让出页面底（WebUI 的做法是页面底完全透明） */
+  @Prop bgActive: boolean = false;
  @State groups: SessionGroup[] = [];
  @State expandedKeys: string[] = [];
  @State loading: boolean = false;
@ -778,7 +782,7 @@ struct SentTab {
      }
    }
    .width('100%').height('100%')
-    .backgroundColor(Theme.pageBg)
+    .backgroundColor(this.bgActive ? Color.Transparent : Theme.pageBg)
  }
 }

@ -797,6 +801,8 @@ struct SentTab {

@Component
 struct PermissionTab {
+  /** 背景是否开启：开着就让出页面底（WebUI 的做法是页面底完全透明） */
+  @Prop bgActive: boolean = false;
  @State requests: PermissionRequest[] = [];
  @State loading: boolean = false;
  @State error: string = '';
@ -1008,7 +1014,7 @@ struct PermissionTab {
      }
    }
    .width('100%').height('100%')
-    .backgroundColor(Theme.pageBg)
+    .backgroundColor(this.bgActive ? Color.Transparent : Theme.pageBg)
  }
 }

@ -1032,6 +1038,8 @@ struct PermissionTab {

@Component
 struct CommPage {
+  /** 背景开启时，本页与其三个 pane 的页面底都要让出（否则壁纸全被盖住） */
+  @Prop bgActive: boolean = false;
  @State commTab: string = 'inbox';
  @State unreadCount: number = 0;
  @State pendingCount: number = 0;
@ -1165,11 +1173,11 @@ struct CommPage {
        this.CommTabBar()

        if (this.commTab === 'sent') {
-          SentTab()
+          SentTab({ bgActive: this.bgActive })
        } else if (this.commTab === 'permissions') {
-          PermissionTab()
+          PermissionTab({ bgActive: this.bgActive })
        } else {
-          InboxTab()
+          InboxTab({ bgActive: this.bgActive })
        }
      }
      .width('100%').height('100%')
@ -1188,12 +1196,13 @@ struct CommPage {
        .onClick(() => { this.openCompose(); })
    }
    .width('100%').height('100%')
-    .backgroundColor(Theme.pageBg)
+    .backgroundColor(this.bgActive ? Color.Transparent : Theme.pageBg)
  }
 }

@Component
 struct ContactsTab {
+  @Prop bgActive: boolean = false;
  @State contacts: Contact[] = [];
  @State loading: boolean = false;
  @State error: string = '';
@ -1298,7 +1307,7 @@ struct ContactsTab {
      }
    }
    .width('100%').height('100%')
-    .backgroundColor(Theme.pageBg)
+    .backgroundColor(this.bgActive ? Color.Transparent : Theme.pageBg)
  }

  /**
@ -1459,6 +1468,15 @@ struct MainPage {
   * 现在补上：预设档画渐变、图片档画图 + 压暗。
   */
  @State bgPlan: BackgroundPlan = new BackgroundPlan();
+  /**
+   * 背景是否开着 —— 传给每个页面，让它们把**页面底**让出来（变成透明）。
+   *
+   * 这是"背景画出来了"这句话的另一半：只把壁纸铺在最底层、而每个页面自己又刷一层
+   * 系统页面底（`Theme.pageBg` 是不透明的），壁纸就**全被盖住**，等于没画。
+   * WebUI 侧对这件事的原话：「页面底 → 完全透明，让出背景；不改 27 个组件的 class，
+   * 逐个加 class 必然漏（漏掉的那块就是一张不透明卡片浮在背景上）」。
+   */
+  @State bgActive: boolean = false;
  @State wallpaperImage: image.PixelMap | null = null;
  private gridSettings: RenderingContextSettings = new RenderingContextSettings(true);
  private gridCtx: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.gridSettings);
@ -1488,6 +1506,7 @@ struct MainPage {
    const snap: AppearanceSnapshot = store.current();
    this.wallpaperImage = store.wallpaper;
    this.bgPlan = resolveBackground(snap.bgKind, snap.bgPresetId, scrimOpacity(snap.bgDim), store.wallpaper !== null);
+    this.bgActive = this.bgPlan.kind !== 'none';
  }

  /** 一层渐变的色标：`['色', 位置]` 成对（页面才拼，纯逻辑里只存两个数组） */
@ -1619,12 +1638,12 @@ struct MainPage {
      this.WallpaperLayer()
      Tabs({ barPosition: BarPosition.End }) {
      TabContent() {
-        CommPage()
+        CommPage({ bgActive: this.bgActive })
      }
      .tabBar(this.TabBarBuilder('通信', '✉️', 0))

      TabContent() {
-        ContactsTab()
+        ContactsTab({ bgActive: this.bgActive })
      }
      .tabBar(this.TabBarBuilder('联系人', '👤', 1))
    }