23 KiB
Node Info Page UI/UX Specification
1. Scope
本文档定义 Trail Mate Node Info / 节点详情页面的 UI/UX 规格。
本文档当前只约束“联系人中打开某个节点后看到的详情页”，不覆盖联系人列表页本身，也不覆盖地图主页面。
本页面中的地图背景、拖动、缩放、图层切换与投影能力，不在本文档中单独重新定义底层组件职责，而是继承共享地图视口组件规格：
- Firmware Visual Style Specification
- Shared Map Viewport Component Specification
- Shared Map Viewport Implementation Specification
这是一份实现约束文档，不是视觉灵感草图。后续 node_info_page_layout.* 与 node_info_page_components.* 的改造应回到本文档核对，而不是继续靠局部补丁演化。
本文档中的未定义项，默认视为“禁止实现”，而不是“留给实现者自由发挥”。
换句话说：
- 只有文档明确列出的字段可以显示
- 只有文档明确允许的降级行为可以出现
- 没有被文档点名的补充信息，默认不应出现在标准
Node Info页面
如果后续需要扩展字段或增加新的视觉元素，应先改规格，再改代码。
2. Requirement Restatement
节点详情页的目标不是做成一个由多个卡片和边框堆起来的信息面板，而是做成一个以“节点空间位置”为主视觉、以“节点链路信息”为右侧辅信息的沉浸式页面。
当前已经确认的需求如下：
- 整个节点详情页需要重构，不再沿用旧的卡片式/框式信息布局。
- 页面主体不要再出现内容框、链路框、信息卡等视觉容器，内容尽量直接落在页面上。
- 如果节点存在经纬度信息，地图应作为页面背景。
- 节点 ID 显示在左上角。
- 经纬度显示在左下角，并且“上面经度，下面纬度”。
- 原来链路框里显示的信息，不再使用单独框体，而是全部放到页面右侧，一行一项。
- 如果节点存在经纬度，需要在地图上标出该节点位置。
- 如果同时存在“我的经纬度”和“该节点经纬度”，需要在地图上同时标记两个点，并连线显示，还要渲染两点之间的距离。
- 页面右下角增加
+和-两个地图缩放按钮，缩放中心始终是该节点。 - 只有在节点存在经纬度时，缩放按钮才可操作；如果没有经纬度，两个缩放按钮不可操作。
- 当节点存在经纬度时，地图需要支持滑动，允许用户拖动查看节点周边区域。
- “角色”字段如果只能显示
-，则不要显示。当前规格中默认移除该字段。 - 地图上的文字描述需要使用一组较鲜明、彼此区分的彩色配色。ID、经纬度、链路信息项、距离等可以使用不同颜色，整体要尽量好看。
- 页面底部中间增加一个
Layer按钮，用于图层切换。 Layer按钮的功能必须与GPS / 地图页中的Layer按钮完全一致，至少包括：- 街道图 /
OSM - 地形图 /
Terrain - 卫星图 /
Satellite - 等高线开关 /
Contour
- 街道图 /
Node Info页不允许定义自己的图层切换语义；它只能复用共享地图视口所定义的图层切换语义。
3. Distinctions
3.1 页面主对象
节点详情页的主对象是“一个远端节点”。
地图不是主对象，地图只是这个节点的空间上下文。
3.2 页面主视觉
页面主视觉不是“表格”也不是“卡片组”，而是：
- 有坐标时：以地图为背景的空间视图
- 无坐标时：以纯背景承载文本信息的降级视图
3.3 右侧信息区的职责
右侧区域负责承载节点的链路和附加信息，它是“信息投影区”，不是第二个主页面，也不是独立卡片容器。
3.4 不再成立的旧表达
以下表达在新规格中不再成立：
- “角色”字段恒常显示，即使值没有意义
- 使用链路框来承载链路信息
- 使用多个内容框把一个节点拆成多个视觉岛
- 让地图退化为小插图或次要组件
4. Page Goals
4.1 核心目标
- 让用户一眼先看到“这个节点在哪里”
- 再快速看到“它和我之间是什么关系”
- 最后看到“它的链路/状态细节”
4.2 非目标
本页面当前不是：
- 节点配置编辑器
- 完整诊断页
- 多标签页容器
- 多卡片信息看板
5. Layout Specification
5.1 Overall Structure
页面保留应用级公共顶部栏能力，例如返回、标题、电量等。
除顶部栏外，内容区域采用全屏单画布表达，不再引入内容卡片、信息框、链路框、外轮廓盒子。
本节给出的结构图只表达“区域关系”，不表达固定像素。
Node Info 的具体几何必须由当前设备尺寸和 page_profile 决定，不能把其它文档中面向 pager 的 480x222 示例反向理解成 Node Info 或全固件的统一布局法。
+--------------------------------------------------+
| Top Bar |
+--------------------------------------------------+
| |
| ID right-side |
| map / background info lines |
| |
| |
| lon |
| lat [Layer] + |
| - |
+--------------------------------------------------+
5.1.1 Compact Portrait Baseline
以下基线适用于当前 320x240 竖屏设备族，是 Node Info 页面评审、截图比对和回归检查时的规范性参考布局：
- 根页面：
320x240 - TopBar：
320x30 - 内容区：
320x210 - 内容区内边距：
10px - 右侧链路列宽：
122px - 右侧链路列起始 Y：
12px - 右侧链路列行高：
12px - 右侧链路列行间距：
1px - 右下角缩放按钮：
28x28 - 底部中间
Layer按钮：68x24
这个基线只约束当前紧凑竖屏 profile 下的 Node Info 页面，不构成全固件通用布局法。
5.2 Background
有节点坐标
- 地图铺满内容区域，作为主背景
- 默认首帧以节点为中心
- 地图需要支持用户滑动查看周边区域
- 地图缩放围绕节点进行
- 地图底图必须保持清晰可读；标准态下不允许再叠加任何持续存在的半透明蒙版、雾化层、scrim 或右侧渐隐遮罩
- 唯一允许盖在地图之上的半透明层，只能是临时模态弹层自己的背景遮罩，且它必须在弹层关闭后完全消失
无节点坐标
- 不显示地图底图
- 使用纯色或轻量纹理背景承载文本信息
- 缩放按钮显示为禁用态
5.3 Left-Top: Node Identity
左上角显示节点 ID。
要求：
- 位置稳定，优先级高
- 不被右侧信息区挤压
- 颜色应明显区别于背景
- 可以使用强调色
如果后续需要同时显示短名/昵称，也应从属于 ID，不应取代 ID 的第一视觉位。
5.4 Left-Bottom: Coordinates
左下角显示坐标文本，顺序固定为：
- 经度
- 纬度
要求：
- 上面经度，下面纬度
- 文字颜色与 ID 和右侧信息项区分开
- 坐标缺失时不显示伪值、不显示占位破折号
5.5 Right Side: Info Lines
页面右侧为信息列，一行一项。
要求：
- 不再使用链路框
- 每一行只承载一个信息项
- 信息项自上而下排列
- 视觉上比左侧主信息弱，但仍应清晰可读
- 行之间需要保持稳定节奏和可扫描性
- 整列按右缘读数列处理，必须真正右对齐
- 当底图为瓦片地图或卫星图时，右侧读数列必须优先保证对比度和瞬时可读性；它允许比全局正文使用更亮的叠加读数色，但不得退化成随机多彩文本
5.5.1 Standard Field Set
标准 Node Info 页面右侧信息列只允许显示以下字段，顺序固定：
ProtocolRSSISNRSeen
这 4 项组成标准节点详情页的完整链路信息合同。
如果某一项缺失，则直接省略，后续项上移；不允许用任何其它字段补位。
5.5.2 Field Text Templates
右侧信息列文本模板固定如下：
Protocol- 允许值：
Meshtastic/MeshCore/RNode/LXMF - 不允许缩写成
MT/MC/RN/LX
- 允许值：
RSSI- 模板：
RSSI -49 dBm - 数值取整到 1 dBm
- 模板：
SNR- 模板：
SNR +6.2 dB - 保留 1 位小数，正数必须带
+
- 模板：
Seen- 模板：
Seen 12s/Seen 3m/Seen 2h/Seen 1d - 使用相对时长短格式
- 模板：
5.5.3 Readout Color Contract
右侧读数列在地图背景上使用固定的高可读颜色合同，当前版本定义如下：
Protocol- 使用明亮暖 amber
- 目标是成为第一眼可扫读项
RSSI- 使用明亮 info blue / cyan
- 必须明显亮于普通正文棕色
SNR- 使用明亮 ok green
Seen- 使用浅暖亮色，而不是暗淡次文本棕色
Zoom- 使用与
Seen同级或略强一级的浅亮色
- 使用与
禁止做法：
- 继续沿用全局普通正文深棕色直接覆盖到地图瓦片之上
- 为了“统一”而把
Seen/Zoom压回低亮度灰褐色 - 对每一行随意指定未收敛的新颜色
5.5.4 Forbidden Fields
以下字段在标准 Node Info 页面中明确禁止显示：
LoRaMQTTFREQSFBWCHHOPSNEXTRole- 任何调试字段
- 任何为了“补满右侧区域”而临时加入的派生字段
这些信息如果未来确有价值，应进入单独的诊断页或高级详情模式，而不是重新塞回标准节点详情页。
5.5.5 Line Count Contract
标准 Node Info 页面右侧信息列最大行数为 4。
这不是“当前实现巧合”，而是规格本身的一部分。
任何实现如果在标准节点详情页中显示第 5 行及以上的链路信息，都应视为违反规格。
5.5.6 Viewport Status Line
标准 Node Info 页面允许在 Seen 下方额外显示 1 行视口状态行，当前版本固定只用于显示当前缩放等级。
它不是链路信息的一部分，因此不计入 5.5.4 中“链路信息列最大行数为 4”的限制。
要求：
- 固定显示在
Seen的下方 - 仍然属于右侧读数列，必须右对齐
- 只在节点存在有效经纬度时显示
- 当前版本文本模板固定为
Zoom 12 - 不允许在这行里追加其它调试字段、tile 状态、坐标系、底图源简称等信息
5.5.7 Readout Backdrop
右侧链路读数列允许增加一个 内容包裹式半透明底板，用途只有一个：在瓦片地图或卫星图背景上提升 Protocol / RSSI / SNR / Seen / Zoom 这组读数的瞬时可读性。
要求：
- 底板只能包裹右侧当前可见的读数项，尺寸必须由“可见读数文本的实际包围盒 + 少量内边距”决定
- 当前版本透明度固定为
60% - 当前版本底板颜色固定继承固件暖色面板底色语义，即
PanelBG - 底板必须跟随可见读数项数量与文本宽度变化，不能退化成固定半列、固定整列或半屏遮罩
- 底板只服务于右侧读数簇，不得扩展到地图主体区域，也不得影响左上 ID、左下坐标、地图标记或距离标签的视觉层级
- 底板是读数簇的承托层，不是新的“链路框”或“信息卡”；禁止重新引入标题栏、分组边框、分隔线或二级卡片语义
- 当右侧没有任何可见读数项时，底板必须完全隐藏
禁止做法：
- 用整块右半屏蒙版、渐隐遮罩、scrim、雾化层来替代这个底板
- 为了实现可读性而重新把地图做灰、做雾或整体降对比
- 把底板做成与右侧列宽永久绑定的固定矩形，而不是内容驱动矩形
5.6 Bottom-Right: Zoom Controls
右下角放置两个按钮：
+-
要求：
- 始终固定在右下角区域
- 只控制地图缩放
- 缩放中心始终是当前节点
- 缩放等级契约固定继承共享地图视口 / 地图页契约：最小
0，最大18，默认12 - 首次进入页面时，视口默认使用
12作为首选缩放级别；若该级别中心瓦片不可用，才允许在0..18范围内寻找最近可用级别 - 用户点击
+或-后，缩放动作必须重新回到“以当前节点为锚点”的相机语义，不能继续沿用拖动后偏离节点的屏幕中心 - 用户触发的缩放请求只受缩放范围约束，不得再额外被“当前更高/更低一级中心瓦片是否存在”拦截为 no-op；瓦片缺失属于地图数据可用性问题，不是缩放语义问题
- 当已经到达最小或最大缩放级别时，对应按钮必须显示为禁用态
当节点没有经纬度时：
- 两个按钮保持可见但不可操作
- 视觉上必须表现为禁用态
- 点击后不执行任何地图行为
5.7 Bottom-Center: Layer Button
页面底部中间必须放置一个 Layer 按钮。
要求：
- 位置固定在底部中间区域
- 它属于页面固定 chrome，不跟随地图拖动
- 它打开的图层切换能力必须与
GPS / 地图页的Layer按钮功能完全一致 - 它不允许引入一套
Node Info私有的图层定义、图层命名或图层切换后果
Layer 按钮控制的是共享地图配置，而不是当前页面私有状态。
这意味着：
- 切换
OSM / Terrain / Satellite时，改变的是共享基础底图选择 - 切换
Contour时，改变的是共享等高线叠加开关 - 这些变化的语义应与地图页保持一致
无坐标状态下的 Layer 按钮
即使当前节点没有坐标，Layer 按钮仍然保持可见且可操作。
原因是：
- 它切换的是共享地图图层偏好
- 它不依赖当前节点是否可投影
- 无坐标只意味着当前页不显示地图内容，不意味着图层切换能力失效
但在无坐标状态下：
- 页面仍然不得伪装出可浏览地图
- 切换图层后也不会强行显示地图背景
- 页面主降级态保持不变
6. Map Semantics
6.1 Node Marker
当节点存在经纬度时：
- 必须在地图上标记节点位置
- 节点标记应清楚、醒目、易定位
- 标记色应与“我的位置”标记色区分
6.2 Self Marker
只有在本机也存在有效经纬度时，才显示“我的位置”标记。
6.3 Connection Line
只有在“节点位置”和“我的位置”都存在时，才显示连线。
要求：
- 连线应清楚但不要喧宾夺主
- 颜色应与底图和两个标记都能区分
6.4 Distance Label
只有在“节点位置”和“我的位置”都存在时，才显示距离。
要求：
- 距离标签必须与连线语义一致
- 距离标签优先服务于空间理解，不应遮挡主文本
6.5 Panning Semantics
当节点存在经纬度时，地图内容层必须支持滑动。
要求：
- 用户可以通过拖动地图查看节点周边区域
- 滑动的是地图视口，不是整个页面布局
- ID、经纬度文本、右侧信息列、缩放按钮等 UI 覆盖层位置必须保持稳定，不能跟着地图一起漂移
- 节点标记、自身标记、连线、距离等地图语义层必须与底图一起同步移动
- 如果节点没有经纬度，则不提供地图滑动能力
- 首帧默认视图必须让当前节点落在可视区几何中心，而不是左偏或右偏构图
- 拖动只代表“临时浏览周边区域”；它不改变本页的主对象，也不改变缩放锚点语义
- 因此，当用户在拖动后再次执行缩放时，视口必须重新收敛到“节点居中”的锚点状态
滑动能力的职责是“浏览节点周边”，不是改写页面主对象。即使用户把视口拖离节点，节点仍然是本页的主参考对象。
7. Data Presence States
7.1 State A: Node Has No Coordinates
表现：
- 不显示地图底图
- 不显示节点地图标记
- 不显示自我标记
- 不显示连线
- 不显示距离
- 缩放按钮禁用
- 仍显示左上 ID 和右侧信息列
7.2 State B: Node Has Coordinates, Self Has No Coordinates
表现：
- 显示地图背景
- 显示节点标记
- 不显示自我标记
- 不显示连线
- 不显示距离
- 支持地图滑动
- 缩放按钮可用
7.3 State C: Node Has Coordinates, Self Also Has Coordinates
表现：
- 显示地图背景
- 显示节点标记
- 显示自我标记
- 显示两点连线
- 显示距离
- 支持地图滑动
- 缩放按钮可用
8. Visual Style
8.1 General Style Direction
Node Info 页面必须继承 Firmware Visual Style Specification。
这意味着：
- 页面整体必须保持暖色工程仪表风格
- TopBar 必须与其它标准页面使用同一套共享 chrome
- 不允许在该页私自引入深色 HUD / cyber 配色体系
- 地图语义层可以使用有限语义色，但页面 chrome 仍以暖色 token 为主
页面应摆脱“调试面板感”和“表单感”，整体更接近一张有空间感的暖色工程地图详情页。
要求：
- 不堆框
- 不堆边线
- 不让页面看起来像报表
- 颜色鲜明但不杂乱
8.2 Color Strategy
以下元素允许使用有限的语义区分色：
- ID
- 经度
- 纬度
- 距离
- 节点标记
- 自身标记
- 连线
右侧信息列默认应以 Text / TextDim 为主，只在必要时用 Info / Ok / Warn / AmberDark 做语义强调。
颜色要表达层次和角色，不是随机上色。
对于右侧信息列，色彩分配也应固定收敛：
Protocol：TextRSSI：TextSNR：OkSeen：TextDim
标准节点详情页不允许让不同链路项各自随机发明一套颜色。
8.3 Typography
要求：
- ID 为页面最高优先级文本之一
- 经纬度次一级，但仍要明显
- 右侧信息项按可扫描性优先，而不是挤成密集小字
- 不要因为要容纳更多字段而把字体压得过小
9. Interaction Specification
9.1 Enter Page
进入节点详情页后：
- 页面应直接展示节点当前信息
- 如果有坐标，应直接进入地图背景态
- 如果有坐标，首帧默认以节点为中心
- 不需要额外点击才能展开地图
9.2 Drag / Pan
当节点存在经纬度时，地图必须支持拖动。
要求：
- 拖动手势只作用于地图视口
- 拖动后，用户可以查看节点附近区域
- 拖动不改变节点作为页面主对象的语义地位
- 拖动后不应导致左上 ID、左下坐标、右侧信息列和右下缩放按钮错位
9.3 Zoom In / Out
+放大地图-缩小地图- 缩放中心固定为该节点，不是屏幕中心自由漫游
- 如果用户此前已经把地图拖离节点，触发缩放后视图应回到以节点为缩放锚点的状态
9.4 Disabled Interaction
当节点没有坐标时：
- 缩放按钮不可操作
- 地图不可滑动
- 页面不能假装存在地图能力
- 不应出现点击后“看起来点了但什么都没发生”的模糊反馈
9.5 Layer Switching
Layer 按钮触发的图层切换交互遵守以下规则：
- 不重建
Node Info页面。 - 不改变当前查看对象。
- 不改变页面右侧信息语义。
- 如果当前节点有坐标，则底图按新图层配置刷新。
- 如果当前节点无坐标，则只更新共享地图图层偏好，不强行制造地图显示。
- 缺图提示、图层归一化、等高线开关语义必须与共享地图视口一致。
- 图层弹窗/弹层必须继承全局暖色弹层风格，并在小屏上保持可操作，不允许做成遮挡严重、难以操作的深色模态块。
320x240基线下，图层弹窗的垂直定位必须优先贴近顶部安全区或贴近触发按钮的上方；如果按钮上方空间不足，不允许退化成“尽量压在屏幕下沿”的低位弹窗。- 图层弹窗的状态摘要必须压缩为单行展示，固定为同一行中的
Base: <Source>与Contour: <ON/OFF>；不允许再次拆成两行。 - 图层弹窗在
320x240基线下必须保证OSM / Terrain / Satellite / Contour / Close五个动作项一次完整可见；不允许依赖裁切、滚动或超高按钮来挤占可操作空间。
10. Content Rules
10.1 Role Field
“角色”字段默认不显示。
只有当后续产品上真正定义了有意义、稳定、对用户有价值的角色语义，并且该值不是占位符时，才允许重新引入。
10.2 Empty Values
不要用 -、N/A、空标签去填充页面。
规则是：
- 有值才显示
- 无值就省略
10.3 Information Priority
页面的信息优先级如下：
- 节点身份
- 节点空间位置
- 我与节点的空间关系
- 节点链路与附加信息
右侧信息项不得反过来压制地图和身份信息。
10.4 Standard Page Contract
标准 Node Info 页面不是诊断页。
因此它的信息合同固定为：
- 左上：节点 ID
- 左下：经度、纬度
- 地图层：节点位置、自身位置、连线、距离
- 右侧：
Protocol / RSSI / SNR / Seen
除此之外，不再显示其它链路细节。
这条合同的目的就是压缩实现自由度，避免不同开发者或 AI 在“也许这些字段有用”的判断下继续发散。
11. Implementation Guardrails
为避免实现再次漂移，后续改造时必须遵守以下约束：
- 不允许重新引入“链路框”。
- 不允许为了补字段而恢复卡片式布局。
- 不允许保留只会显示
-的角色字段。 - 不允许把地图降为页面中的一个小组件，只要节点有坐标，地图就是背景主画布。
- 不允许让缩放围绕任意中心点漂移，缩放中心必须是节点。
- 不允许在无坐标状态下伪装成可缩放地图页。
- 不允许把“地图支持滑动”实现成整个详情页跟着滚动，固定信息层必须保持稳定。
- 不允许把颜色策略退化成“全部同色文本”。
- 不允许把右侧信息列做成“放在右侧的左对齐段落”。
- 不允许把协议对象名重新压缩成
MT/MC/RN/LX这类缩写主表达。 - 不允许在标准
Node Info页面中重新加入LoRa / MQTT / FREQ / SF / BW / CH / HOPS / NEXT。 - 不允许把右侧信息列扩展到 4 行以上。
- 不允许在
Node Info页面内再次实现一套独立地图主流程；地图底图、投影、拖动、缩放、图层切换必须接入共享地图视口组件。 - 不允许在
Node Info页面内定义与GPS / 地图页不同的图层切换语义。 - 不允许把
Layer按钮实现成只改视觉、不改共享图层配置的伪入口。
12. Open Items
以下问题当前可以留给实现阶段，但不能违反前述结构约束：
- 地图标记的具体图形样式
- 距离标签放置在连线中点、靠近节点还是靠近右侧信息列
- 无坐标状态下采用纯色背景还是轻量纹理背景
- 不同设备尺寸上的字号与边距微调
这些都属于实现细节微调，不应推翻本文档的页面结构。
13. Summary Baseline
一句话总结本页规格：
节点详情页应当是一个“以节点位置为中心的全屏地图详情页”，而不是一个“套着多个框的节点信息面板”。