更新记录

1.0.0（2026-08-09）

首次发布：基于 UTS 原生 AppWidget 实现 Android 桌面课表组件，显示当前课与下一节课、地点、任课老师、教学周，切换时刻自动刷新；提供通用课表数据模型与 JS 辅助层，可接入任意课表类 App。

平台兼容性

uni-app(3.91)

其他

qc-course-widget 框架发布包

把「桌面课表组件」抽离为独立、通用、可发布的 uni-app 原生插件框架。 本目录是提交到 DCloud 插件市场（ext.dcloud.net.cn）的就绪产物，包含：

course-widget-framework/
├── uni_modules/qc-course-widget/     # ★ 直接提交市场的插件（zip 此目录即可）
│   ├── package.json                 # 插件元信息（市场展示）
│   ├── widget.js                    # 通用 JS 辅助层（对外主 API）
│   ├── readme.md                    # 插件使用文档
│   └── utssdk/app-android/          # 原生 AppWidget 实现（index.uts / 资源 / Manifest）
├── demo/                            # ★ 可运行示例工程（市场"Demo 演示"链接用）
│   └── ...（vue3 uni-app 工程，含示例课表数据）
└── README.md                        # 本文件

一、插件能做什么

• 在 Android 桌面显示当前正在上的课 + 下一节课（课程名 / 节次时间 / 地点 / 任课老师 / 教学周）。
• 在当前课结束、下一节课开始的切换时刻自动刷新（原生 AlarmManager），并随系统日期/时间变化刷新。
• 数据 100% 本地计算，仅存 App 私有 SharedPreferences，不上传任何服务器。
• 通用数据模型，可接入任意课表 App（高校教务、培训班、个人课表）。

支持范围：仅 Android + App 端（UTS 原生插件）。iOS / H5 / 小程序自动降级（isSupported() 返回 false）。

二、在你的项目中接入（3 步）

1. 放插件

把 uni_modules/qc-course-widget/ 整个目录复制到你的项目 uni_modules/ 下。

2. 制作自定义基座（必须）

原生 AppWidget 只有自定义基座能跑，标准云端基座不行。

HBuilderX 右键项目 → 制作自定义调试基座（云端打包）→ 装到手机 → 运行到手机时选「使用自定义调试基座」。

3. 调用 API

import {
  isSupported,
  pushSchedule,
  restoreSchedule,
  refresh,
  requestAddToDesktop,
  clearCache
} from '@/uni_modules/qc-course-widget/widget.js'

// 课表加载成功后
pushSchedule(rawSchedule)        // rawSchedule 见下方"数据模型"

// App.vue onShow：用缓存刷新，无需重拉
restoreSchedule()

// 我的页面按钮：引导添加到桌面
requestAddToDesktop()

三、通用课表数据模型

const rawSchedule = {
  student:     "张三",                 // 可选
  currentWeek: 3,                      // 可选，当前教学周（1-based）
  periods: [                           // 节次时间表
    { index: 1, start: "08:00", end: "08:45" },
    { index: 2, start: "08:55", end: "09:40" }
  ],
  weeks: [                             // 教学周日期范围（"第N周"角标 & 假期跳过）
    { zc: 1, start: "2026-03-02", end: "2026-03-08" }
  ],
  courses: [
    {
      name: "高等数学",
      teacher: "张老师",
      room: "一教101",
      day: 1,                           // 1=周一 .. 7=周日
      periodStart: 1,                   // 起始节次（对应 periods[].index）
      periodCount: 2,                   // 连上几节
      weeks: [1, 2, 3, 4, 5, 6, 7, 8]   // 哪些教学周有这门课
    }
  ]
}

插件把 courses 与 periods/weeks 展开成「未来 21 天每节课的绝对时间戳」， 原生层按当前时间筛选当前课 / 下一节课。

四、从"清澄电力"式数据适配（示例）

若你的课表字段与通用模型不同（如清澄电力用 jc 表示节次、dj/djs 表示起始节与节数）， 加一层映射即可，无需改插件：

// 把"清澄电力"结构转成通用模型
function toGenericSchedule(qc) {
  return {
    student: (qc.student && qc.student.name) || '',
    currentWeek: qc.currentWeek || 0,
    periods: (qc.periods || []).map((p) => ({
      index: p.jc, start: p.start, end: p.end
    })),
    weeks: (qc.weeks || []).map((w) => ({ zc: w.zc, start: w.start, end: w.end })),
    courses: (qc.courses || []).map((c) => ({
      name: c.name, teacher: c.teacher, room: c.room,
      day: c.day,
      periodStart: c.dj,            // 起始节次
      periodCount: c.djs,           // 连上节数
      weeks: c.weeks || []
    }))
  }
}

// 使用
import { pushSchedule } from '@/uni_modules/qc-course-widget/widget.js'
pushSchedule(toGenericSchedule(this.data))

五、Demo 工程

demo/ 是一个最小可运行的 vue3 uni-app 工程，演示完整接入：

• 内置一份示例 rawSchedule（通用模型）。
• 首页三个按钮：推送课表到组件 / 添加到桌面 / 刷新组件，并显示支持状态。
• 包含 uni_modules/qc-course-widget 副本，可直接运行（需先按第二步制作自定义基座）。

运行 Demo：用 HBuilderX 打开 demo/，制作自定义调试基座后运行到 Android 手机。

六、提交到 DCloud 插件市场（你来执行）

本框架包已就绪。实际上架需你用自己的 DCloud 账号在网页控制台提交，我这边无法代提交。

1. 登录 DCloud 插件市场 → 右上角「发布插件」。
2. 上传插件：把 uni_modules/qc-course-widget/ 压缩为 zip 上传（插件 ID 即 qc-course-widget）。
3. 填写信息（可直接用下面文案）：
   • 名称：桌面课表小组件 qc-course-widget
   • 分类：UTS插件
   • 简介：Android 桌面课表小组件，显示当前课+下一节课、地点与老师，按课表自动刷新。通用框架，适配任意课表 App。
   • 价格：免费（或自定）
   • 平台：Android（UTS）；明确标注「仅 Android，iOS 敬请期待」
4. 关联 Demo：上传/链接 demo/ 工程作为演示（强烈建议，利于过审）。
5. 提交审核，按市场反馈补充截图（组件在桌面显示当前课/下一节课的实机截图最佳）。

上架文案（可直接复制）

桌面课表小组件（qc-course-widget） 把你的课表放到 Android 手机桌面，实时显示「当前正在上的课 + 下一节课」，含地点、任课老师、教学周，并在切换时刻自动刷新。 基于 UTS 原生 AppWidget 实现，数据本地计算不上传；通用课表数据模型，可接入任意课表类 App。 仅支持 Android App 端（需自定义基座），iOS / H5 / 小程序自动降级。

七、FAQ

• 添加到桌面没反应 / 没数据：确认用自定义基座；国产桌面可能忽略程序化固定，按提示「长按桌面 → 添***件 → 今日课表」手动添加。
• iOS 不显示：本插件仅 Android，iOS 端相关调用返回「仅 Android App 端支持」。
• 想改样式：改 utssdk/app-android/res/drawable/*.xml（背景）和 res/layout/qc_course_widget.xml（布局）。
• 想改标题/周次逻辑：utssdk/app-android/index.uts 的 activeWeekText / update。