#客户端使用

AstraSchedule 客户端是基于 Electron 的 Windows 桌面应用程序，设计用于教室电子白板或教学一体机上长期运行。本章介绍客户端的安装、配置和日常使用方法。

#安装与首次启动

从 GitHub Releases 页面下载最新版本的安装包（ElectronClassSchedule-Setup-YYYYMM.D.N.exe），运行安装程序完成安装。安装完成后，客户端会自动启动并显示课表窗口。

首次启动时，客户端使用内置的默认配置和默认服务端地址（class.khbit.cn）。如果使用自建服务端，需要通过托盘菜单修改服务端地址和班级标识。服务端地址和班级标识配置正确后，客户端将自动从服务端拉取课表、作息、天气等数据。

客户端默认为开机自启动，无需手动添加到启动文件夹。此行为可在托盘菜单中关闭。

#托盘菜单完整功能

右键点击系统托盘中的星程课表图标（或左键点击图标、或点击课表窗口中的星期标签），弹出托盘菜单。菜单包含以下二十一项功能（按顺序排列）：

#云端与更新

#课表与视图

#显示与开关

托盘提示文字（tooltip）显示当前版本号和连接状态（在线、离线、Serverless 模式），更新下载过程中会显示下载进度。

#窗口模式

客户端窗口支持三种窗口行为特性，适应教室白板的特殊使用场景：

#窗口置顶

窗口始终保持在屏幕最顶层，不会被其他窗口（如浏览器、PPT）遮挡。使用 screen-saver 级别的置顶策略，level 为最高值，确保在最极端的窗口层级中也能保持可见。默认开启，可通过托盘菜单开关。

#点击穿透

窗口默认对鼠标事件透明——鼠标可以直接穿透课表窗口操作其下方的应用程序（如电子白板软件、浏览器）。当鼠标悬停在课表的可交互区域（课程列表、倒计时框、迷你倒计时、侧边栏、横幅）上方时，客户端每 100 毫秒检测一次光标位置，若光标位于这些元素上，则临时关闭穿透并降低窗口透明度，允许正常的鼠标操作。

此机制确保课表显示不干扰白板的正常使用，同时保留了必要时操作课表的能力。

#窗口透明度

窗口采用透明背景（transparent: true），课表元素的背景不透明度由 CSS 变量 --global-bg-opacity 控制（默认 0.3）。鼠标悬停在课表区域时透明度可进一步降低，增强课表的可读性。鼠标移开后窗口恢复至几乎透明，减少视觉干扰。

#键盘与鼠标交互

#主窗口

• 鼠标悬停：将鼠标移动到课表区域（课程、倒计时、侧边栏等元素）上方时，窗口透明度降低、点击穿透关闭。
• 鼠标移出：鼠标离开课表区域后，窗口恢复高透明度和点击穿透。
• 窗口失焦：窗口失去焦点时自动恢复默认透明度。
• 点击星期标签：点击课表窗口中的星期文字标签，可在当前位置弹出托盘菜单。

#倒数日窗口

• 切换按钮：点击右上角的 ⇔ 或 ⇖ 按钮在展开模式和最小化模式之间切换。
• 悬停按钮：鼠标悬停在切换按钮上时临时关闭点击穿透，移开后恢复。

#系统事件

• 系统挂起/关机：Windows 进入睡眠或关机时，客户端自动退出，避免恢复后状态异常。
• 单实例锁：客户端使用 Electron 的单实例锁机制，防止同时运行多个实例。再次启动时自动聚焦到已有窗口。

#electron-store 持久化键值

以下设置为用户偏好，通过 electron-store 持久化保存在 %APPDATA%/electron-class-schedule/config.json 中，重装或更新后保持不变：

此外，浏览器 localStorage 中保存了当前周数（weekIndex）、计时偏移（timeOffset）和日程偏移（dayOffset）等运行时状态。

#自动更新

客户端使用 electron-updater 实现自动更新。更新机制的工作流程如下：

1. 启动检查：应用启动 3 秒后自动检查更新。
2. 更新源：默认从 GitHub Releases 获取更新（通过镜像代理加速）。可通过托盘菜单"更新源（可选）"修改为自定义地址。
3. 静默下载：检测到更新后自动在后台下载，托盘提示显示下载进度百分比。
4. 自动安装：下载完成后提示"更新可用"，自动退出并安装新版本，安装完成后重新启动。
5. 手动检查：通过托盘菜单"检查更新"随时手动触发检查。

自动更新仅在打包版本（app.isPackaged）中生效。开发调试版本不会触发更新检测。如果网络环境无法访问 GitHub，可通过"更新源（可选）"菜单项配置内部镜像地址。Windows 7 系统可能需要安装特定系统补丁才能正常执行自动更新。