动态应用图标

目标

应用可以在运行过程中更新启动器中显示的图标，用于提示备份状态、待更新数量、下载完成或异常等信息。动态内容由应用自行生成 PNG 文件，应用不需要修改安装包中的静态图标。

前置条件

• 微服系统（lzcos）版本为 v1.6.2 或更高版本。
• 应用已经通过 LPK 安装并正常运行。
• 动态图标文件必须是 PNG，单个文件大小不超过 1 MiB。

文件位置和命名

在应用运行时目录下创建 launcher-icon 目录：

/lzcapp/run/launcher-icon/

应用侧支持以下两种文件名：

• icon.png：部署级图标，对当前部署中可见的用户生效。
• <uid>.png：用户专属图标，仅对文件名中的用户 UID 生效。例如，用户 UID 为 10001 时，文件名为 10001.png。此方式仅单实例应用需要关注；多实例应用通常只需使用 icon.png。

文件名必须完全匹配上述格式，其他文件不会作为动态图标处理。应用不需要也不应该自行创建其他槽位文件。

显示优先级

同一个用户同时存在多种图标时，显示优先级如下：

1. 用户专属图标 <uid>.png。
2. 部署级图标 icon.png。
3. 安装包中的静态图标 pkg/icon.png。

如果删除当前生效的动态文件，应用会回到下一层可用图标；当所有动态图标都不存在时，显示安装包中的静态图标。

更新图标

应用只需要把新的 PNG 内容写入对应文件即可。推荐先写入临时文件，再用重命名方式替换目标文件，避免启动器读取到未写完的内容：

set -eu

icon_dir=/lzcapp/run/launcher-icon
tmp_file="$icon_dir/.icon.tmp"

mkdir -p "$icon_dir"
cp /path/to/new-icon.png "$tmp_file"
mv -f "$tmp_file" "$icon_dir/icon.png"

如果应用需要动画效果，可以在同一个文件中按需交替写入不同画面。建议仅在图标确实发生变化时更新文件，避免不必要的频繁更新。

动态图标保存在应用运行时目录中，不属于持久化数据。应用或 LPK 重启后，/lzcapp/run/launcher-icon/ 中的图标状态会丢失，启动器会暂时显示安装包中的静态图标。应用应在每次启动时重新生成并写入需要显示的动态图标。

更新频率与内容数量

系统最多处理每秒 4 次图标变化，即最高约 4 FPS。超过此频率的中间画面不会显示。

如果图标变化内容较多，建议尽量控制在 24 个不同内容以内，以便最高效地利用浏览器缓存。简单角标、状态提醒和低频图标变化不需要关注这些限制。

停止动态显示

删除不再使用的动态图标文件即可：

rm -f /lzcapp/run/launcher-icon/icon.png

删除用户专属文件后，该用户会回退到部署级图标或静态图标。删除整个 launcher-icon 目录也可以停止所有动态覆盖。

验证

1. 确认文件存在且为 PNG：

   ls -l /lzcapp/run/launcher-icon
   file /lzcapp/run/launcher-icon/icon.png

2. 在启动器中查看应用图标是否更新。

3. 删除动态文件，确认图标回退到下一层图标。

动态应用图标不会修改应用的安装包内容，也不会改变应用在其他应用列表或系统设置中的静态图标。拖拽应用时使用安装包中的原始静态图标。

常见问题

图标没有变化

• 检查微服系统版本是否为 v1.6.2 或更高版本。
• 检查目录是否为 /lzcapp/run/launcher-icon/，文件名是否符合固定格式。
• 检查文件是否确实被替换，且大小不超过 1 MiB。
• 确认写入的是当前应用运行目录，而不是构建机或开发机上的同名目录。
• 如果应用刚刚重启，请确认应用启动逻辑是否重新生成并写入了动态图标。

用户看到的图标不一致

单实例应用如果看到用户之间的图标不一致，请检查是否同时存在 <uid>.png 和 icon.png。用户专属文件优先级更高，会覆盖部署级图标。多实例应用通常不需要创建 <uid>.png。

如何恢复默认图标

删除所有动态图标文件后，应用会显示安装包中的 pkg/icon.png。