发送、更新与结束

本页说明连接状态、一条内容的组成与生命周期，以及提交结果的处理方式。

连接状态

状态	含义	建议处理
`NOT_INSTALLED`	未安装星流，或星流不支持当前通信版本	不显示星河岛相关功能入口
`WAITING`	正在等待星河岛响应	长时间停留说明星河岛未启用或设备尚未就绪，无需重试
`REJECTED`	星河岛拒绝了连接	检查应用签名与权限声明
`READY`	已连接	可以发送内容

星河岛重新启动后，客户端自动重新连接，状态依次变为 WAITING、READY。重新连接后请调用 listMine() 核对仍在显示的内容，并重新提交需要的内容。

组成一条内容

内容由 IslandActivity.Builder(id, capsule, card) 生成。内容编号 id 在本应用内唯一，长度 1 至 128 个字符；更新与结束都使用这个编号。

胶囊

val capsule = Capsule.Builder(IslandImage.picture(coverBitmap))   // 左侧图像，必填
    .setLabel("送货中")                                              // 左侧标签，最多 32 个字符
    .setTrailing(CapsuleTrailing.countdown(arriveAtMillis))         // 右侧：倒计时
    .build()

右侧内容	写法
文字	`CapsuleTrailing.text("晚上一起吃饭吗？")`
等宽数值	`CapsuleTrailing.number("45%")`
倒计时	`CapsuleTrailing.countdown(endAtMillis)`
正计时	`CapsuleTrailing.stopwatch(startedAtMillis)`
进度环	`CapsuleTrailing.progress(0.6f)`
加载指示	`CapsuleTrailing.busy()`
波形	`CapsuleTrailing.waveform()`

胶囊最右端可用 setTail() 固定一个小图或进度环；副岛内容可用 setSatellite() 单独指定，未指定时显示左侧图像。

图像

写法	用途
`IslandImage.picture(bitmap)`	照片类图像：头像、封面、商品图，按原图显示
`IslandImage.glyph(bitmap)`	单色图标，按符号样式显示在圆形浅色底上
`IslandImage.symbol(BuiltinSymbol.TIMER)`	星河岛内置符号
`IslandImage.appIcon()`	本应用图标，仅用于胶囊与副岛

卡片

卡片从九套模板中选择一套，写法见卡片模板。

内容选项

方法	说明
`setPriority()`	排位参考：`LOW`、`DEFAULT`、`HIGH`。消息卡片按新消息排位，不使用此项
`setAlertOnStart()`	首次显示时自动展开卡片片刻
`setAlertOnUpdate()`	内容变化时自动展开卡片片刻
`setLockScreenVisibility()`	锁屏时显示多少：`PUBLIC`、`TITLE_ONLY`、`HIDDEN`
`setOpenIntent()`	点按卡片时执行的操作
`setOwnNotification()`	声明对应的应用通知，见与通知协同
`setPostedAt()`	发送时间；显示来源栏时显示在来源栏右侧
`setStaleAt()`	过时时间，过后卡片注明「信息可能已过时」
`setDismissPolicy()`	消失方式：`untilEnded()` 或 `afterMillis()`
`setLandscapeText()`	横屏胶囊的完整短文字，最多 32 个字符，数字与英文分组后须在四行以内；未提供时保留完整数值或短状态。消息仍显示应用名称
`setAccentColor()`	强调色
`setContentDescription()`	无障碍读屏说明

生命周期

开始：start(activity) 显示一条内容。同一内容编号已在显示时整份替换。
更新：update(activity) 与 start 相同，使用同一内容编号即可。星河岛比较前后内容，只对变化部分执行过渡。
结束：end(id, outro) 结束一条内容，outro 可省略。endAll() 结束本应用的全部内容。
自动结束：由应用结束的内容最长显示 8 小时；设置了 afterMillis() 的内容到时自动消失。星河岛结束内容时，应用收到 onEnded。

提交结果

start、update、end 与 endAll 返回 IslandResult。accepted 为 true 表示已受理；受理不等于已显示，例如应用在前台或排位靠后时内容暂不显示。

结果	含义	建议处理
`OK`	已受理	—
`IMAGE_REJECTED`	已受理，有图片不符合要求未显示	检查位图尺寸与大小
`NO_PERMISSION`	清单缺少发送权限	确认工具包的清单已合并
`SOURCE_DISABLED`	用户关闭了本应用的内容	停止提交
`KIND_DISABLED`	用户在星流中关闭了「星河岛歌词」，音乐卡片不予显示	停止提交音乐卡片
`QUOTA_EXCEEDED`	通过 SDK 保留的内容已达 3 条（包括排队内容）	先结束旧内容
`RATE_LIMITED`	每秒提交超过 10 次	降低更新频率
`INVALID`	内容无效或连接尚未就绪	原有内容保持不变；检查数值
`BUSY`	星河岛暂时繁忙	稍后重试
`NOT_CONNECTED`	尚未连接或连接已断开	等待 `READY` 后重新提交

文字超长、按钮超出上限、必填项缺失等写法错误不会在提交时才发现：对应的构造方法、setXxx 或 build() 会立即抛出 IllegalArgumentException，并附中文说明。