Files
class-schedule/starschedule/docs/正方教务导入.md
T
2026-09-20 13:33:09 +08:00

4.5 KiB
Raw Blame History

正方教务导入说明

星课表只内置一份正方适配脚本,不连接外部学校仓库。

脚本路径:

shared/src/commonMain/composeResources/files/zhengfang.js

运行时通过 Compose Resources 读取:

Res.readBytes("files/zhengfang.js").decodeToString()

1. 用户路径

  1. 我的 → 课表导入/导出 → 正方教务导入(Destination.WebView())。
  2. 地址栏输入正方登录 URL(或从空白页开始输入)。
  3. 登录后进入 学生课表查询,选择学年学期并查询。
  4. 点「执行导入」,选择目标课表。
  5. 脚本确认对话框 → 抓取 → saveImportedCourses → 覆盖写入 → notifyTaskCompletion 回到周课表。

2. 页面要求

脚本会:

  1. fetch 当前页 HTML,内容需包含「课表查询」。
  2. 读取 #shcPDF 的 data-type:list 或网格。
  3. 列表找 #kblist_table,网格找 #kbgrid_table_0。
  4. 使用 jQuery(window.jQuery)。没有 jQuery 会直接失败。

网格解析 parserTbale()(函数名沿用历史拼写):遍历 #kbgrid_table_0 td.td_wrap 下的 .timetable_con。
列表解析 parserList():按星期 tbody 扫行。

能解析的字段:课程名、星期、节次区间、周次(含 1-16、1-16(单)、逗号分隔)、教师、地点(取空白分隔的最后一段)。课程名会去掉 ●★○。

周次规则:

  • n-m 闭区间
  • (单) 只保留奇数周,(双) 只保留偶数周
  • 多段用逗号

3. JS Bridge

页面注入后可用:

对象 方法 行为
shiguangBridge showToast(message) 短提示
shiguangBridge notifyTaskCompletion() Native 结束导入并返回课表
shiguangBridgePromise showAlert(title, content, confirm) 确认框,Promise<boolean>
shiguangBridgePromise showPrompt(...) 输入框,可带 JS 校验函数名
shiguangBridgePromise showSingleSelection(title, items, defaultIndex) 单选
shiguangBridgePromise saveImportedCourses(coursesJsonString) 保存课程数组
shiguangBridgePromise saveCourseConfig(configJsonString) 保存学期配置(正方脚本目前未调用)
shiguangBridgePromise savePresetTimeSlots(timeSlotsJsonString) 保存节次(正方脚本目前未调用)

兼容别名:AndroidBridge、AndroidBridgePromise。

Native 回调:

window._shiguangNativeCallback(callbackId, isSuccess, result)

消息 JSON:

{
  "action": "saveImportedCourses",
  "callbackId": "cb_1_...",
  "payload": "{\"coursesJsonString\":\"[...]\"}"
}

payload 本身是再包一层的 JSON 字符串。Android 用 JavascriptInterface 的 postMessage 收到后交给 WebBridgeHandler.onMessageReceived。

4. 写入规则

saveImportedCourses 解析为 List<ImportCourseJsonModel>,调用:

courseConversionRepository.importCoursesFromList(tableId, list)
  • 必须已经选过目标课表,否则失败。
  • 删除该课表全部旧课程 再插入。
  • 每条生成新 UUID。
  • 按课程名分配颜色池下标。
  • 正方脚本 不导入节次时刻和开学日期。导入后请在「自定义时间段」「设置开学日期」里按学校作息补全,否则小组件和提醒的钟点可能不准。

5. 改脚本时注意

  • 正方不同学校皮肤可能改 class 名。改选择器前用真机打开该校课表查询页看 DOM。
  • 脚本末尾直接 runImportFlow(),每次 executeScript 都会跑完整流程。
  • 不要在脚本里写死学校 URL;URL 由用户输入。
  • 解析结果必须是 Bridge 能 decode 的数组:至少含 name, day, weeks, teacher, position, startSection, endSection。
  • 保持依赖 jQuery 的前提,或同时改成原生 DOM——当前实现明确检查 jQuery。

6. Native 侧相关文件

文件 职责
ui/schoolselection/web/WebViewScreen.kt 地址栏、导入按钮、读 js、选课表
WebBridgeProtocol.kt 注入脚本、消息数据类
WebBridgeHandler.kt action 路由、写库
WebDialogHost.kt Alert / Prompt / 单选 Compose 弹窗
WebView.android.kt WebView 创建、JS 接口、桌面 UA
AndroidWebConstants.kt 桌面 UA 等
WebViewRequestInterceptor.kt 请求拦截(如有)

isDesktopMode 切换 UA,部分正方在「电脑模式」才能看到完整课表。

Release 混淆注意:NativeBridge.postMessage 必须能被 JS 调到,见 构建与发布 · ProGuard。