add: 添加 shiguang-bridge 类型声明文件和 tsconfig 配置

.vscode/settings.json

@@ -4,5 +4,6 @@
     "scripts/schemas/adapters.schema.json": "resources/**/adapters.yaml"
   },
   "yaml.format.enable": true,
-  "yaml.validate": true
+  "yaml.validate": true,
+  "js/ts.suggest.completeFunctionCalls": true
 }

scripts/types/shiguang-bridge.d.ts

@@ -0,0 +1,157 @@
+// shiguang-bridge.d.ts
+// 适配脚本全局类型声明，供 VSCode / JetBrains 识别 window.shiguangBridgePromise 与 window.shiguangBridge
+// 本文档不参与运行时，不会被浏览器加载
+
+/**
+ * 异步交互 API，挂载于 window.shiguangBridgePromise。
+ * 所有方法均返回 Promise，需配合 await 使用。
+ */
+interface ShiguangBridgePromise {
+    /**
+     * 显示公告弹窗，等待用户确认。
+     *
+     * @param title 弹窗标题
+     * @param content 弹窗内容
+     * @param confirmText 确认按钮文本
+     * @returns 确认返回 true，取消返回 false
+     */
+    showAlert(title: string, content: string, confirmText: string): Promise<boolean>;
+
+    /**
+     * 显示输入框弹窗，支持 JS 侧校验。
+     *
+     * @param title 弹窗标题
+     * @param tip 输入框提示文本
+     * @param defaultText 默认文本
+     * @param validatorJsFunction 全局作用域中的验证函数名。
+     *        返回 false 表示通过，返回字符串表示错误信息。
+     * @returns 用户输入内容；取消返回 null
+     */
+    showPrompt(
+        title: string,
+        tip: string,
+        defaultText: string,
+        validatorJsFunction?: string
+    ): Promise<string | null>;
+
+    /**
+     * 显示单选列表弹窗。
+     *
+     * @param title 弹窗标题
+     * @param itemsJsonString 选项列表的 JSON 字符串，如 '["选项1","选项2"]'
+     * @param defaultSelectedIndex 默认选中索引，-1 表示不选中
+     * @returns 选中索引；取消返回 null
+     */
+    showSingleSelection(
+        title: string,
+        itemsJsonString: string,
+        defaultSelectedIndex?: number
+    ): Promise<number | null>;
+
+    /**
+     * 提交课程数据。
+     *
+     * 传入的 JSON 字符串每项字段：
+     * - `name` 课程名
+     * - `teacher` 老师
+     * - `position` 地点
+     * - `day` 星期 1~7
+     * - `startSection` / `endSection` 起止节次，isCustomTime 为 false 时必填
+     * - `weeks` 周次数组
+     * - `isCustomTime` 是否自定义时间，默认 false
+     * - `customStartTime` / `customEndTime` 自定义时间 HH:mm，isCustomTime 为 true 时必填
+     * - `credit` 学分
+     *
+     * @param coursesJsonString 课程数组的 JSON 字符串
+     * @returns 导入成功返回 true，失败抛出 Error
+     */
+    saveImportedCourses(coursesJsonString: string): Promise<true>;
+
+    /**
+     * 提交预设时间段数据。
+     *
+     * 传入的 JSON 字符串每项字段：
+     * - `number` 节次编号，必须从 1 开始连续递增
+     * - `startTime` / `endTime` 起止时间 HH:mm
+     *
+     * 时间段之间不允许重叠。
+     *
+     * 若本次导入包含组合作息方案，本方法必须先于 saveComboSchedule 调用且成功。
+     *
+     * @param timeSlotsJsonString 时间段数组的 JSON 字符串
+     * @returns 导入成功返回 true，失败抛出 Error
+     */
+    savePresetTimeSlots(timeSlotsJsonString: string): Promise<true>;
+
+    /**
+     * 提交课表配置数据。
+     *
+     * 传入的 JSON 字符串字段：
+     * - `semesterStartDate` 学期开始日期 YYYY-MM-DD，默认 null
+     * - `semesterTotalWeeks` 总周数，默认 20
+     * - `defaultClassDuration` 单节时长（分钟），默认 45
+     * - `defaultBreakDuration` 课间休息（分钟），默认 10
+     * - `firstDayOfWeek` 一周第一天，1=周一，7=周日，默认 1
+     *
+     * 只需提供想修改的字段。
+     *
+     * @param configJsonString 课表配置的 JSON 字符串
+     * @returns 导入成功返回 true，失败抛出 Error
+     */
+    saveCourseConfig(configJsonString: string): Promise<true>;
+
+    /**
+     * 提交组合作息方案。
+     *
+     * 传入的 JSON 字符串字段：
+     * - `name` 方案名，可选，为空时回退为当前课表名
+     * - `publicSchedules` 公共作息模板数组
+     *
+     * 每个模板字段：
+     * - `name` 作息名
+     * - `startDate` / `endDate` 生效区间 YYYY-MM-DD
+     * - `defaultClassDuration` / `defaultBreakDuration` 时长（分钟），默认 45 / 10
+     * - `timeSlots` 节次时间点数组，可只提交差异节次，未提供的由基础时间段补齐
+     *
+     * 必须先成功调用 savePresetTimeSlots，否则会被直接拒绝。
+     *
+     * @param comboScheduleJsonString 组合作息方案的 JSON 字符串
+     * @returns 导入成功返回 true，失败抛出 Error
+     */
+    saveComboSchedule(comboScheduleJsonString: string): Promise<true>;
+}
+
+/**
+ * 同步辅助 API，挂载于 window.shiguangBridge。
+ * 不阻塞 JS 流程，主要用于即时反馈或生命周期通知。
+ */
+interface ShiguangBridge {
+    /**
+     * 在界面短暂显示一条提示信息。
+     *
+     * @param message 提示内容
+     */
+    showToast(message: string): void;
+
+    /**
+     * 通知任务完成，执行收尾。
+     * 仅应在整个流程成功完成后调用。
+     */
+    notifyTaskCompletion(): void;
+}
+
+declare global {
+    interface Window {
+        /** 异步交互 API */
+        shiguangBridgePromise: ShiguangBridgePromise;
+        /** 同步辅助 API */
+        shiguangBridge: ShiguangBridge;
+
+        /** @deprecated 旧版兼容别名，请使用 shiguangBridgePromise */
+        AndroidBridgePromise: ShiguangBridgePromise;
+        /** @deprecated 旧版兼容别名，请使用 shiguangBridge */
+        AndroidBridge: ShiguangBridge;
+    }
+}
+
+export {};

tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "checkJs": true,
+    "allowJs": true,
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM"],
+
+    "module": "ESNext",
+    "moduleDetection": "force",
+
+    "noEmit": true,
+
+    "strict": false,
+
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": [
+    "scripts/types/shiguang-bridge.d.ts",
+    "resources/**/*.js"
+  ]
+}