按钮与交互

用户在星河岛上的操作通过 IslandCallback 回传给应用。所有回调均在主线程执行，事件尽力送达，不作为业务的唯一依据。

按钮

文字按钮、圆形按钮（含计时控制按钮与状态卡片的停止圆钮）与底部图标按钮三类合计最多 4 个。各卡片可用的按钮如下：

TextButton("confirm", "确认收货", style = ButtonStyle.PRIMARY)
TextButton("cancel", "取消订单", style = ButtonStyle.DESTRUCTIVE, requiresUnlock = true)
IconButton("mute", IslandImage.glyph(muteBitmap), description = "静音")
ToggleButton("subtitle", "字幕", checked = true)

• 按钮编号非空白、最多 64 个字符，同一卡片内不得重复；不得使用保留编号 pause、resume、stop、toggle、prev、play_pause、next。
• requiresUnlock = true 的按钮在锁屏时隐藏。
• 开关被点按后，星河岛不会自行切换状态；请在 onAction 中处理后，以同一内容编号更新 checked。

回调

回复、发送与标为已读

短信与即时消息均使用 MessageCard 消息模板。未输入时显示回复入口；输入后，发送键位于输入条右端，「取消」和应用提供的「标为已读」等按钮保留在下方。配图见回复与发送状态。

编辑或发送回复期间，新消息不替换正在回复的卡片。未实际交给应用的文字保留为草稿，重新打开对应会话后可继续发送。

消息卡片调用 setReplyEnabled(true) 后显示回复栏。用户发送的文字仅交给发送该卡片的应用；星河岛交出文字后，卡片提示「已交给应用发送」。实际发送由应用完成，发送后可用同一内容编号更新卡片。锁屏时不显示回复栏。

override fun onReply(activityId: String, text: String) {
    if (activityId != "chat-xiaoming") return
    // 在应用自己的后台任务中，将 text 发送到此编号对应的会话。
    // 根据实际发送结果更新会话与卡片。
}

标为已读

通过 TextButton("mark_read", "标为已读") 添加按钮。在同一 IslandCallback 中处理以下操作；mark_read 为示例自定义编号。星河岛不会自动把会话标为已读。

override fun onAction(activityId: String, actionId: String) {
    if (activityId != "chat-xiaoming" || actionId != "mark_read") return
    // 在应用中将对应会话标为已读，业务处理完成后更新或结束此内容。
    // client.update(...) 或 client.end(activityId) 必须在后台线程调用。
}

回复文字最多 2000 个字符，输入区域最多显示三行；空白内容不能发送。取消输入会退出编辑，草稿仍保留。未能把文字交给应用时提示「发送未完成，文字已保留。」；「已交给应用发送」不表示实际发送或送达成功。

示例工程只展示卡片与操作回传，不发送真实短信或聊天消息。实际发送、已读状态与发送结果由接入应用实现。需要在锁屏隐藏已读按钮时，设置 requiresUnlock = true。

拖动音乐进度

仅在应用支持跳转播放位置时启用拖动；播放按键也只声明实际支持的操作。应用收到回调后仍须确认内容编号与当前播放内容相符。

音乐卡片调用 setSeekable(true) 后，用户可拖动进度条。松手后 onSeek 收到目标位置（毫秒）；应用跳转播放位置后，以同一内容编号更新播放进度，进度从松手位置继续推进。

用户手势

用户在星河岛上的常用操作如下；应用据此理解 onDismissed、onExpanded 与 onCollapsed 的触发时机。

• 点按胶囊：展开卡片，再点按收起。横屏时用户开启「横屏点击胶囊不展开卡片」后，点按只收起不展开，长按仍展开。
• 在胶囊上向下拉（竖屏）：打开系统通知面板；系统不支持时与向摄像头一侧划相同，收起当前内容。
• 在胶囊上向摄像头一侧划（竖屏为向上划）：收起当前内容。
• 沿胶囊方向划动（竖屏左右、横屏上下）：显示副岛时换成该侧副岛的内容；没有副岛时，用户开启「划动切换内容」则换成排队中的另一条内容，否则收起当前内容。切换不收起内容，不触发 onDismissed。
• 点按副岛（小圆点）：该内容提到主岛并展开卡片；横屏开启上述开关时只提到主岛。
• 长按胶囊：展开卡片且不自动收起；用户开启「长按打开对应应用」且内容设置了打开目标时，长按改为打开对应应用。

用户收起内容

用户按「用户手势」中列出的方式收起内容时，内容从星河岛上收回，应用收到 onDismissed。内容并未结束，在以下情况下重新显示：

• 有真实的新消息或新的重要提醒；普通进度刷新、换歌词等重复更新不视为新的提醒。
• 用户进入并退出一次本应用。
• 星河岛无显示内容时，用户点按摄像头区域或沿胶囊长边滑动。

用户开启「长时间未操作时收起」或「停留后收起」后，星河岛会在设定时间内没有操作时自动收起内容。此情形不调用 onDismissed，恢复条件与上面相同。

内容不再需要时，请调用 end()。

自动展开

同一事项连续更新时显示最新内容，期间提出的自动展开要求保留一次，不会因紧接着的普通进度更新而取消；仍遵守同一应用十秒内最多一次的限制。

setAlertOnStart(true) 与 setAlertOnUpdate(true) 使卡片在首次显示或内容变化时自动展开片刻。同一应用 10 秒内最多自动展开一次；熄屏或下拉通知栏、控制中心时不自动展开；全屏应用（如游戏、视频）时以胶囊提醒代替，不展开卡片。请仅在用户需要立即知晓的时刻使用，例如送达、到达或计时结束。

与通知协同

应用通常会同时发出一条通知。使用 setOwnNotification(id, tag) 声明当前用户中本应用自己的通知（与 NotificationManager.notify 的编号和标签一致）后：

• 这条内容在星河岛上期间，对应通知不再单独显示在星河岛上。
• 内容显示在主岛或副岛上，且用户开启「屏蔽系统横幅」时，对应通知不再弹出系统横幅。
• 内容结束后，通知在下次更新时按通知的规则正常显示。

锁屏

涉及个人信息的内容（如消息、订单详情）建议使用 TITLE_ONLY。