#4544·HMCL

[Feature] 公告系统

Author: GlavoCreated Sep 23, 2025Updated Sep 9, 2026

Labelsenhancement

概述 | Summary

支持在主页展示公告列表。

原因 | Reason

我希望我们拥有主动推送一些信息的能力，这样能够在遇到重大问题（比如微软服务无法访问）的时候能够及时将消息推送给用户。

详情 | Description

以下是实现方式的草案，需要进一步讨论研究确定最终方案。

所有有效公告应该组织为一个 JSON 列表，存储至 JSON 文件并放置在 docs.hmcl.net 内。

公告文件格式参考 LittleSkin API，类似下例：

json5

[
  {
    // 公告标题，本地化的文本
    "title": "string",             
     // 公告正文，本地化的文本，内容中可以包括简单的 HTML 标签
    "content": {                   
        "default": "<p>Meow</p>",
        "zh": "<p>喵</p>"
    },
    // 公告正文链接，本地化的文本。和 content 互斥，获取公告的实际正文内容需要读取该链接
    // "link": {
    //     "default": "https://example.com/en",
    //     "zh": "https://example.com/zh"
    // },
    // 公告的类型，board 类型的公告展示在主页，popup 类型的公告在启动启动器时弹出
    "type": "board",
    // 公告优先级，整数。值越大，优先级越高，应被安排在上方或前方展示
    "priority": 100,                
    // 公告的重要/严重性
    "severity": "info",
    // 当前公告的父公告，若父公告未被展示，则不会展示当前公告
    "parent": "019976a8-04af-7442-9ffd-ebdaf9bbf68e",
    // 公告的唯一标识，UUID v7
    "id": "019976b2-ad49-7451-b090-83b66c532cdd"
  }
]

HMCL 启动时应检查 ./.hmcl/cache 文件夹中的 announcements.json 文件，如果不存在，则尝试从 docs.hmcl.net 拉取公告列表。

在拉取公告列表后，HMCL 应当创建 ./.hmcl/cache/announcements.json 文件，该文件格式类似下例：

json5

{
    // 最后一次尝试拉取公告的时间戳
    "lastAccessTime": 1758632697195,
    // 已经关闭的公告 ID 列表
    "closed": [ ... ],
    "announcements": [
        ... // 服务端公告列表
    ]
}

每次启动启动器时应当读取 ./.hmcl/cache/announcements.json 的内容，如果 lastAccessTime 距离当前超过限制（十分钟？半个小时？），则将该时间戳转换为 If-Modified-Since: 标头并重新请求公告列表，如果服务器返回新公告则更新 announcements.json 文件中的服务端公告列表，并且删除其他字段中已经不存在于公告列表内的 ID。

无论公告列表是否已经变化，都应当以当前时间戳刷新 lastAccessTime，从而降低对服务器的压力。

在打开启动器后，启动器应依次弹出所有未列于 closed 字段中的 popup 类型公告，确认公告后启动器将公告 ID 加入 closed 字段。

进入主界面后，启动器将在主页右侧依次展示所有未列于 closed 字段中的 board 类型公告。公告可以关闭，关闭后加入 closed 字段。

Source: HMCL-dev/HMCL

View original on GitHub View discussion on GitHub