网页页面控件总目录

本页从访问者角度列出网页每个主要页面可能出现的控件、状态和验收动作。它不是源码说明，也不要求用户理解实现方式；用途是当页面出现一个按钮、输入框或空状态时，可以快速判断它属于哪一类操作。

页面会根据账号类型、机台授权、版本和服务状态隐藏部分控件。隐藏控件不是可通过猜路径绕过的功能。

全局区域

顶部导航

控件	作用	验收/注意
ZundaLink 标题	返回站点首页	点击后不应改变当前账号数据
首页	打开主页	统计可能需要等待
安装	打开安装章节	适合首次部署和恢复
使用	打开使用章节	页面侧栏按功能分组
API 文档	打开公开接口章节	只包含公开客户端可调用内容
主题按钮	浅色/深色切换	只改变当前浏览器显示
当前账号	查看账号名称和类型	先确认目标再做高风险操作

账号下拉菜单

登录后点击账号名称可能出现：

• 切换用户；
• 设置用户名密码（用户账号）；
• 本地重命名；
• 删除本地账号条目；
• 导入/导出账号列表。

本地重命名不会改变服务端账号。删除本地条目也不等于删除服务端数据；导出文件应按凭据处理。

移动端菜单

移动端通过汉堡按钮展开功能菜单，点击页面外部关闭。大表格和 JSON 文本区域可以横向滚动，不要为了适应屏幕删掉字段。

账号选择页

可见控件

控件	行为
添加账号	打开登录弹窗
账号卡片	验证并切换到该账号
编辑名称	修改本地显示名称
删除	删除浏览器本地条目，通常需要确认
拖拽排序	修改本地列表顺序
导入	读取受信设备导出的账号条目
导出	生成本地账号列表文件
返回/回到主页	关闭选择页或进入主页

账号卡片可能显示用户/机台标签、最近使用时间、验证中、验证失败和错误提示。验证期间不要重复点击多个账号。

登录弹窗

登录方式可能包括：

• 二维码文本；
• 二维码图片上传；
• 用户名；
• 密码；
• 自定义服务地址；
• 人机验证；
• 登录按钮。

成功标准是：弹窗关闭、顶部出现账号名、账号类型正确、菜单与权限匹配。登录失败时保留错误消息，先检查网络和输入方式，不要把完整二维码贴到公开聊天。

主页

主页是只读仪表盘，可能包含以下卡片：

欢迎与快捷入口

快捷入口用于进入访问码、配方、记录、成绩、相片、缓存和机台统计。快捷入口缺失时，先判断账号类型和授权，不要认为页面损坏。

服务统计

可能显示用户数、机台数、在线数、请求数、配方数量和读取耗时。它们是聚合快照，不是精确计费或个人行为证明。

配方拉取统计

可能显示拉取次数、平均耗时和波动。空数据可以表示当前账号没有统计权限或尚未生成数据。

地区分布

地区图/列表只展示聚合结果。加载失败时不应影响登录、缓存和记录页面。

功能说明与安全提醒

主页可能包含功能介绍、开放权限范围、免费使用提示和凭据安全提醒。不要把页面宣传文字当作具体版本承诺；版本以当前公告和页面状态为准。

访问码页面

详细教程见二维码与访问码。控件验收清单如下：

控件	主要状态
一次性/长期标签	切换访问码生命周期
生成按钮	生成二维码和文本
二维码	可预览、保存或被设备读取
复制文本	复制完整访问码，注意剪贴板安全
图片识别	上传二维码图片，识别后填入文本
自定义服务地址	不确定时留空
机台选择	选择有权限的目标机台
人机验证	按页面要求完成
NFC	只在支持的浏览器和设备显示

一次性码过期后重新生成；长期码泄露时立即退出相关会话并联系管理员。

配方页面

共同控件

• 刷新/读取当前配置；
• 配置名称；
• 启用开关；
• 文本值输入；
• JSON 编辑区；
• 列表或下拉选择；
• 保存按钮；
• 成功/失败消息。

值输入类型

类型	页面行为	输入建议
普通文本	直接保存字符串	不带多余换行
数字文本	页面可能只接受数字	先看范围和单位
逗号列表	多个名称/编号	使用页面规定的英文分隔符
JSON	显示语法有效/错误	双引号、保留未知字段
图片	浏览器预处理后上传	使用常见格式和合适尺寸
开关	保存布尔状态	确认是否需要重启

修改流程永远是“读取原值 → 保存原值 → 只改一项 → 保存 → 重新读取 → 按提示重启”。

查卡与会话统计页面

机台账号可能看到：

• 机台单选/多选；
• 刷新按钮；
• 自动刷新开关；
• 当前在线人数；
• 最近 30 分钟、1/2/3/6/12/24 小时统计；
• 时段统计；
• 活跃时长分组；
• 峰值小时；
• 会话总数和日均值；
• 最近游玩记录；
• 最近会话记录；
• 用户频率和回访率。

自动刷新时显示生成时间。多机台合并时每张卡片必须保留来源机台；Token 失效或页面离开后应停止刷新。

游玩记录页面

完整字段说明见游玩记录页面。页面控件包括：

• 刷新；
• 上一页、下一页；
• 第一页、最后一页；
• 附近页码和省略号；
• 跳转页码输入框；
• 加载中、换页中和错误状态；
• 记录卡片折叠/展开。

每条卡片可能显示封面、Track、时间、曲目、难度、达成率、评级、DX 分数、连击、同步、判定、Rating、伙伴和对战信息。字段缺失时隐藏小块，不要将缺失当作 0。

乐曲成绩页面

成绩页可能提供：

控件	说明
搜索框	按曲名、编号、作者或 BPM 筛选
清除搜索	恢复完整列表
排序选择	曲目、成绩、游玩次数、DX 分数、互动数量等
单曲展开	查看成绩、评论和反馈
点赞/点踩	更新曲目互动汇总
评论输入	发布新评论
回复输入	回复指定评论
删除	删除自己有权限删除的评论
内容反馈	提交需要处理的原因
审核入口	仅明确授权的审核账号显示

互动提交期间按钮禁用。响应丢失时先重新读取，不要重复发布评论或反馈。

数据缓存页面

控件包括下载普通备份、下载兼容格式（若当前版本提供）、选择 JSON 文件、重新选择文件和恢复按钮。

状态规则：

• 没有选择文件时恢复按钮禁用；
• JSON 解析成功后显示文件已加载；
• 恢复中按钮显示进度；
• 恢复成功显示条数和消息；
• 恢复失败保留原数据和错误提示。

恢复前必须下载当前状态，恢复后重新读取记录、成绩和相片。

上传缓存页面

详见上传缓存页面。页面控件包括：

• 刷新列表；
• SGWCMAID 输入；
• 自定义地址输入；
• 每条快照的下载、上传、删除；
• 上传中/下载中状态；
• 删除确认；
• 空列表、成功和错误提示。

网络超时后先刷新列表，不要自动重复写入。

相片页面

详见相片页面。控件包括刷新、清除浏览器图片缓存、删除全部、单张查看、原图下载、单张删除和关闭预览。

“清除缓存”只影响浏览器；“删除相片”影响服务端。预览图片可能懒加载，缩略图失败不等于文件不存在。

测试内容页面

获得授权的账号可能看到：

• 内容索引；
• 搜索曲名、编号、作者和 BPM；
• 滚动加载；
• 封面懒加载；
• 封面放大预览；
• 难度按钮；
• 详情读取；
• 下载确认；
• 申请入口；
• 更新公告。

搜索只筛选已经加载的索引；详情读取失败时不要把列表数据当作损坏。下载确认前核对曲名、难度和文件名。

机台管理页面

机台管理页面可分为：

1. 健康检查；
2. 网络与 Hosts；
3. 画面、摄像头、音量和直播；
4. 侧载版本；
5. 订单和限速；
6. 高级测试；
7. 挂载、热重载、重启和关闭；
8. 操作进度和最近结果。

逐项字段见机台控制项详解和机台管理弹窗与输入项。

API 页面

网页内 API 页面可能按分类折叠：会话、访问码、配方、相片、缓存、记录、统计和互动。点击分类后再点击接口可查看请求参数和响应字段。

网页 API 页面是交互式索引，公开文档站中的专题页才是版本化阅读入口。实际开发请同时参考公开接口总参考和客户端实现建议。

页面状态统一解释

状态	不应做的事	推荐动作
加载中	重复点击	等待一次请求结束
空状态	立即判断数据丢失	检查账号、范围和同步状态
业务失败	盲目重试写入	记录 msg，先读状态
网络错误	清空缓存或删除订单	检查网络和最后上报时间
操作超时	把取消当成回滚	区分网页等待与机台动作
权限不足	搜索隐藏入口	使用有权限的页面或联系管理员
版本差异	猜测配置名	以当前页面和公告为准

这份目录适合作为现场验收表；每次版本增加按钮或字段时，应在对应专题页和本目录中同步补充。