Skip to content

SecScore-URL-Protocol.md

Latest commit

 

History

History
229 lines (146 loc) · 4.01 KB

SecScore-URL-Protocol.md

File metadata and controls

229 lines (146 loc) · 4.01 KB

SecScore URL 协议说明

1. 概述

SecScore 提供自定义 URL 协议，用于从浏览器、命令行或其他应用中直接调用软件功能。

  • 协议名（scheme）：secscore

  • URL 基本格式：

    secscore://<command>[/<subcommand>]

  • 大小写约定：

    • 协议名、命令部分大小写不敏感（SecScore://settings 与 secscore://SETTINGS 等效）
    • 建议实际使用中统一采用小写

  • 行为约定：

    • 若 SecScore 未运行：启动应用，并根据 URL 执行对应操作
    • 若 SecScore 已运行：不会启动第二个实例，而是把 URL 转发给现有实例执行

2. 页面导航类 URL

用于打开主窗口并跳转到指定功能页面。

2.1 首页

  • URL：

    secscore://
secscore://home

  • 行为：

    • 打开主窗口，跳转到 /（首页）

2.2 学生管理

  • URL：

    secscore://students

  • 行为：

    • 打开主窗口，跳转到 /students

2.3 积分管理

  • URL：

    secscore://score

  • 行为：

    • 打开主窗口，跳转到 /score

2.4 排行榜

  • URL：

    secscore://leaderboard

  • 行为：

    • 打开主窗口，跳转到 /leaderboard

2.5 结算历史

  • URL：

    secscore://settlements

  • 行为：

    • 打开主窗口，跳转到 /settlements

2.6 理由管理

  • URL：

    secscore://reasons

  • 行为：

    • 打开主窗口，跳转到 /reasons

2.7 系统设置

  • URL：

    secscore://settings

  • 行为：

    • 打开主窗口，跳转到 /settings

3. 悬浮侧边栏控制类 URL

用于控制右侧的全局悬浮侧边栏（global-sidebar 窗口）。

3.1 显示悬浮侧边栏

  • URL：

    secscore://sidebar/show

  • 行为：

    • 若悬浮侧边栏已存在：show() + focus()
    • 若不存在：创建 global-sidebar 窗口并显示

3.2 隐藏悬浮侧边栏

  • URL：

    secscore://sidebar/hide

  • 行为：

    • 若悬浮侧边栏存在：调用 hide()
    • 若不存在：不做任何操作

3.3 切换显隐（toggle）

  • URL：

    secscore://sidebar/toggle
secscore://sidebar

  • 行为：

    • 若悬浮侧边栏存在：
      • 当前可见 → 隐藏
      • 当前不可见 → 显示并 focus()
    • 若不存在：创建并显示 global-sidebar 窗口

4. 使用示例（Windows）

4.1 通过“运行”对话框（Win + R）

在“运行”窗口中输入：

secscore://settings
secscore://sidebar/toggle

点击“确定”后，SecScore 会执行对应操作。

4.2 通过浏览器地址栏

在浏览器（如 Edge）地址栏中输入：

secscore://score

浏览器会唤起 SecScore 应用并跳转到“积分管理”。

4.3 通过命令行

在命令行中执行：

start "" "secscore://leaderboard"

会唤起 SecScore 并打开“排行榜”。

5. 安装与注册说明（打包版本）

下述内容针对打包后的安装版本，开发模式（pnpm dev）下可能不会自动注册协议。

  • 协议注册配置位于 electron-builder.yml：
    • scheme: secscore
    • name: SecScore URL Protocol
  • 在安装完成后，操作系统会把所有 secscore:// URL 交给 SecScore 处理。

6. 错误与兼容性说明

  • 所有 URL 都为本地调用，不通过网络传输。

  • 当前 URL 协议只包含页面级操作与悬浮侧边栏控制，不带参数（例如学生 ID）。

  • 对于未识别的命令，例如：

    secscore://unknown

    主进程会忽略该 URL，不会抛出错误弹窗。

7. 后续扩展建议

如果需要更复杂的 URL 功能，可以在保持现有兼容性的前提下扩展，例如：

  • 按学生 ID 打开积分记录：

    secscore://score/12345

  • 带筛选条件的排行榜视图：

    secscore://leaderboard/today

此类扩展只需在主进程的 URL 解析函数中增加相应分支逻辑即可。