From 01e38db7245dd47a411e0419d1545474bad58257 Mon Sep 17 00:00:00 2001 From: Jokul Date: Sat, 8 Aug 2026 19:45:12 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=B7=A6=E9=94=AE=E5=BC=B9=E7=AA=97?= =?UTF-8?q?=E9=87=8D=E6=96=B0=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 重新设计 NetworkPopup 布局结构，采用通透分区方案： 去掉自绘卡片背景，用分隔线+留白划分区域，速度数字放大为视觉锚点。 适配用户字体颜色、网卡类型图标，预留 fontScale 字号缩放扩展点。 --- .../specs/2026-08-08-popup-redesign-design.md | 268 ++++++++++++++++++ 1 file changed, 268 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-08-popup-redesign-design.md diff --git a/docs/superpowers/specs/2026-08-08-popup-redesign-design.md b/docs/superpowers/specs/2026-08-08-popup-redesign-design.md new file mode 100644 index 0000000..427ed25 --- /dev/null +++ b/docs/superpowers/specs/2026-08-08-popup-redesign-design.md @@ -0,0 +1,268 @@ +# 左键弹窗重新设计 + +> 日期：2026-08-08 +> 状态：已批准，待制定实现计划 +> 涉及文件：`NetworkPopup.qml`、`NetCommon.qml`、`SettingsWindow.qml`、`networkview.qml` + +## 背景与问题 + +当前左键弹窗（`NetworkPopup.qml`）存在以下设计问题（基于截图分析 + 代码阅读）： + +1. **深色模式下文字对比度极低**：卡片背景 `cardBackground` 仅 6% 透明度，在 PanelPopup 自动提供的毛玻璃上几乎不可见，导致区域"糊"在一起，且遮挡了原生通透感。 +2. **IPv6 地址拥挤**：长 IPv6 地址撑满接口信息卡片，破坏平衡。 +3. **底部 chip 未选中态过弱**：未选中 chip 用 `cardBackground` 填充几乎不可见，缺乏交互暗示。 +4. **箭头图标风格不统一**：速度区用圆形底色块 + 文本箭头，累计区用纯文本箭头。 +5. **冗余标题**：弹窗本身就是网络监控，标题"网络速度监控"浪费空间且字号小发闷。 +6. **字号层次不足**：速度数值 18px 不够突出，与标签层次差距小。 + +### 关键技术发现（librarian 研究） + +`PanelPopup`（dde-shell 源码实测）已自动提供： +- **毛玻璃背景**（`enableBlurWindow: true`，透明度跟随系统外观设置） +- **圆角**（跟随系统 `windowRadius`，fallback 4px） +- **阴影**（偏移 `(0, 25)`，深色 50% 黑 / 浅色 20% 黑） + +官方参考（`PanelPluginPage.qml`）：内容区宽度 330px，内边距 10px，元素间距 10px。DTK 字号表 T3=24px、T6=14px、T7=13px、T8=12px。 + +**结论：弹窗内不应自绘背景卡片，应让 PanelPopup 的毛玻璃直接透出，用分隔线 + 留白划分区域。** + +## 设计目标 + +- 重新设计布局结构（非仅视觉微调） +- 速度与接口信息并重（用户第一眼需求） +- Deepin 原生风格（毛玻璃通透、DTK 字号、系统调色板） +- 适配用户配置：字体颜色、网卡类型图标、预留字号缩放 + +## 设计方案 + +选定方案 A：**通透分区，速度为锚点**。去掉所有自绘卡片背景，用分隔线 + 留白划分区域，速度数字放大为视觉锚点。 + +### 第 1 节：整体布局结构 + +**容器调整**（`networkview.qml`）： +- `PanelPopup` 宽度从 360 -> **330px**（对齐官方 `PanelPluginPage` 参考值） +- 高度从固定 320 -> **跟随内容**（预估约 230px，若 PanelPopup 不支持自动高度则 fallback 固定 230） +- padding 从 16 -> **12px**，区域间 spacing 12 -> **10px** + +**纵向布局**（4 个分区 + 3 条分隔线，自上而下）： + +``` +┌───────────────────────────────┐ +│ 接口信息区 (次要) │ 行1: ∿ wlp3s0 · 192.168.3.83 +│ │ 行2: IPv6 截断显示 + tooltip +│ ───────────────────────────── │ ← 分隔线1 +│ 速度区 (锚点, 最大视觉权重) │ ↓ 4.11 KB/s ↑ 3.55 KB/s +│ ───────────────────────────── │ ← 分隔线2 +│ 累计流量区 (紧凑) │ 总计 ↓ 4.85 GB ↑ 134 MB +│ ───────────────────────────── │ ← 分隔线3 +│ 接口切换 chip 区 │ [enp2s0] [wlp3s0] [Meta] +└───────────────────────────────┘ +``` + +**关键变化**： +- 去掉冗余标题"网络速度监控" +- 移除所有自绘卡片 `Rectangle` 背景填充，毛玻璃直接透出 +- 分隔线用 `cardBorder` 色（0.10 透明度）1px 横线，替代原来的卡片边界 + +### 第 2 节：配色与字体层次 + +保留 `NetCommon.qml` 的颜色定义和格式化函数不变（networkview.qml 和 TrafficChartWindow 共享），仅改 `NetworkPopup.qml` 内的使用方式。 + +| 元素 | 颜色 | 字号(DTK) | 字重 | +|---|---|---|---| +| 接口名 `wlp3s0` | `primaryText`(用户色或0.95) | T7(13px) | Normal | +| 接口类型图标 `∿` | `tertiaryText`(0.65) | T8(12px) | Normal | +| IPv4 地址 | `secondaryText`(0.80) | T7(13px) | Normal | +| IPv6 地址 | `tertiaryText`(0.65) | T8(12px) | Normal | +| 下载/上传标签 `下载` | `secondaryText`(0.80) | T8(12px) | Normal | +| **速度数值** `4.11` | **蓝/绿强调色**(下载带阈值变色) | **T3(24px)** | **Bold** | +| 速度单位 `KB/s` | 强调色(同数值) | T7(13px) | Normal | +| `总计` 标签 | `tertiaryText`(0.65) | T8(12px) | Normal | +| 累计数值 | `primaryText`(用户色或0.95) | T7(13px) | Normal | +| 累计箭头 `↓↑` | 蓝/绿强调色 | T8(12px) | Bold | +| chip 选中文字 | white | T8(12px) | Bold | +| chip 未选中文字 | `primaryText`(用户色或0.95) | T8(12px) | Normal | +| 分隔线 | `cardBorder`(0.10) | - | - | + +**关键变化**： +1. 速度数字从 18px -> 24px(T3)，成为绝对视觉锚点 +2. 箭头图标统一为文本符号（去掉速度区的 32x32 圆形底色块），速度区和累计区风格一致 +3. 速度数值和单位拆分显示：`4.11` 大号粗体 + `KB/s` 小号 +4. 下载值保留阈值变色逻辑（>10MB/s 红、>1MB/s 橙、否则蓝），上传固定绿 + +### 第 3 节：各分区内部布局细节 + +#### 3.1 接口信息区（顶部） + +``` +│ ∿ wlp3s0 · 192.168.3.83 │ 行1: 类型图标 + 接口名 + 中点 + IPv4 +│ IPv6 2408:823c:9c12:a69:...:3 │ 行2: IPv6 截断显示 +``` + +- 行1：接口类型图标 + 接口名 + `·` + IPv4，用 `secondaryText`/`tertiaryText`，T7 13px +- 行2：`IPv6` 标签 + 地址。地址超长时截断显示，末尾加 `…`，hover 显示完整地址 tooltip +- 整体水平居中，垂直间距 4px +- 无 IPv6 时只显示行1 + +#### 3.2 速度区（锚点） + +``` +│ ↓ 4.11 KB/s ↑ 3.55 KB/s │ +``` + +- 双栏等宽，中间无竖线（靠留白区分） +- 每栏内部布局： + ``` + 下载 (T8 12px, secondaryText, 居中) + ↓ 4.11 KB/s (↓+数值 T3 24px Bold 强调色, KB/s T7 13px) + ``` +- 下载/上传标签在上方居中小字，下方是箭头 + 大号数值 + 小号单位 + +#### 3.3 累计流量区 + +``` +│ 总计 ↓ 4.85 GB ↑ 134 MB │ +``` + +- 单行紧凑，水平居中 +- `总计` 标签 tertiaryText，箭头蓝/绿强调色 Bold，数值 primaryText + +#### 3.4 接口切换 chip 区 + +``` +│ [enp2s0] [wlp3s0] [Meta] │ +``` + +- chip 样式重做： + - **选中态**：蓝色填充背景 `accentBlue` + 白字 + 蓝色边框（保持不变） + - **未选中态**：**透明背景** + `cardBorder` 边框 + primaryText 文字（原来是 cardBackground 填充几乎不可见） + - hover：边框变 `accentBlue`，文字变 `accentBlue` +- 宽度逻辑、滚动逻辑、`scrollToActiveChip`、`sortedInterfaces`、`Connections` 全部保留不变 + +#### 3.5 分隔线 + +- 3 条横线，分别在：接口区下方、速度区下方、累计区下方 +- 颜色 `cardBorder`(0.10 透明度)，高度 1px，撑满 padding 内宽度 + +### 第 4 节：错误态与尺寸约束 + +#### 4.1 未检测到接口的占位态 + +``` +┌───────────────────────────────┐ +│ ⚠ │ (T1 40px, tertiaryText) +│ 未检测到网络接口 │ (T6 14px, secondaryText) +└───────────────────────────────┘ +``` + +- 去掉卡片背景填充，直接在毛玻璃上居中 +- 警告图标从 24px -> 40px(T1)，更醒目 +- 占位态时不显示分隔线、速度区、累计区、chip 区 + +#### 4.2 尺寸与高度自适应 + +- 宽度固定 330px（`networkview.qml` 的 `PanelPopup` 设置） +- 高度跟随内容（预估约 230px）。各分区预估高度： + - 接口区：~40px（两行） + - 分隔线：1px + 上下 10px spacing + - 速度区：~60px（标签 + 大号数值） + - 累计区：~30px + - chip 区：40px + - padding 上下各 12px + - 合计：~213px +- 若 PanelPopup 不支持自动高度，fallback 为固定 `height: 230` + +### 第 5 节：可配置适配 + +#### 5.1 字体颜色适配（仅主要文字跟随用户色） + +`NetworkPopup.qml` 新增属性覆盖： + +```qml +// 用户自定义字体色（来自 C++ 后端 applet.textColor，持久化到 settings.ini） +// 非空时覆盖 primaryText，空串时回退到 DTK 调色板派生（保持自适应） +readonly property string userTextColor: applet ? applet.textColor : "" +readonly property color primaryText: userTextColor.length > 0 + ? Qt.rgba(userTextColor.r, userTextColor.g, userTextColor.b, 0.95) + : common.primaryText +``` + +**跟随范围**（用 `popup.primaryText` 的元素）： +- 接口名 `wlp3s0` +- 速度数值 `4.11`（注意：下载值有阈值变色逻辑，用户色不覆盖蓝/橙/红阈值色，仅覆盖"未超阈值"时的回退色） +- 累计数值 `4.85 GB` +- chip 未选中文字 + +**不跟随**（仍从 `common` 取 DTK 派生）： +- `secondaryText`（IPv4、标签） +- `tertiaryText`（IPv6、总计标签） +- 蓝绿强调色（下载/上传箭头、chip 选中态） + +> 用户选了红色时，弹窗的接口名、数值、chip 文字变红，但标签和辅助信息仍保持系统主题色，层次不崩。 + +#### 5.2 网卡类型图标（接口信息区） + +**提取公共函数**：将 `SettingsWindow.qml` 中的 `interfaceIcon(name)` 和 `interfaceDescription(name)` 提取到 `NetCommon.qml`，消除重复定义。 + +**弹窗接口信息区布局更新**： +- 接口名前加类型图标，与设置窗口列表的图标一致 +- 图标颜色 `tertiaryText`（次要，不抢速度区焦点） +- 图标字号 T8(12px)，与接口名行对齐 + +#### 5.3 字号缩放预留（fontScale） + +`NetworkPopup.qml` 新增属性： + +```qml +// 字号缩放因子：默认 1.0，后续 C++ 后端新增 applet.fontScale 后绑定 +// 所有字号 = 基准字号 × fontScale，实现全局字号调节 +readonly property real fontScale: (applet && applet.fontScale !== undefined) + ? applet.fontScale : 1.0 +``` + +**所有 `font.pixelSize` 改为缩放形式**： + +| 元素 | 基准字号 | 缩放后 | +|---|---|---| +| 速度数值 | 24 | `Math.round(24 * fontScale)` | +| 速度单位 | 13 | `Math.round(13 * fontScale)` | +| 接口名/IPv4 | 13 | `Math.round(13 * fontScale)` | +| IPv6/标签/箭头 | 12 | `Math.round(12 * fontScale)` | +| chip 文字 | 12 | `Math.round(12 * fontScale)` | +| 占位图标 | 40 | `Math.round(40 * fontScale)` | +| 占位文字 | 14 | `Math.round(14 * fontScale)` | + +**当前状态**：`applet.fontScale` 尚不存在，`fontScale` 恒为 1.0，视觉无变化。后续 C++ 后端加属性 + 设置窗口加选项后即可生效，弹窗代码无需再改。 + +## 影响范围 + +| 文件 | 改动 | +|---|---| +| `NetCommon.qml` | 新增 `interfaceIcon`/`interfaceDescription` 公共函数（从 SettingsWindow 迁移） | +| `NetworkPopup.qml` | 重写布局（主体工作）+ 新增 `userTextColor`/`fontScale`/`primaryText` 覆盖 | +| `SettingsWindow.qml` | `interfaceIcon`/`interfaceDescription` 改为调用 `common.xxx`（消除本地重复定义） | +| `networkview.qml` | 仅改 `PanelPopup` 的 width/height 两个数值 | +| C++ 后端 | **本次不改**（fontScale 预留扩展点，后续再加） | + +## 保持不变的部分 + +- `NetCommon.qml` 的颜色定义和格式化函数（networkview.qml 和 TrafficChartWindow 共享） +- chip 滚动逻辑、`scrollToActiveChip`、`sortedInterfaces`、`Connections` +- `TrafficChartWindow.qml`、`AboutWindow.qml` +- C++ 后端 +- 深浅主题适配机制（颜色派生自 `DTK.palette.windowText`，自动切换） + +## 验证方式 + +本项目无测试/lint/CI 目标，验证为手动： +1. `cmake -B build && cmake --build build && sudo cmake --install build` +2. `systemctl --user restart dde-shell@DDE` +3. 左键点击任务栏网络监控图标，检查弹窗： + - 毛玻璃通透，无卡片填充色块 + - 速度数字 24px 为视觉锚点 + - 接口信息区显示类型图标 + - chip 未选中态有清晰边框 + - 分隔线划分四个区域 +4. 深色/浅色模式切换，检查文字对比度 +5. 设置窗口选字体颜色，检查弹窗主要文字是否跟随 +6. 切换网卡，检查 chip 滚动和接口信息更新