接口参考

星河岛 SDK 0.1.2 全部公开接口，位于 com.astraisland.sdk 包。签名以 Kotlin 书写；Java 中属性对应 getXxx() / isXxx()，带默认值的参数提供多个重载，工厂方法为静态方法。

以下签名以 Kotlin 书写；Java 中属性对应 getXxx() / isXxx()，带默认值的参数提供多个重载，工厂方法为静态方法。

IslandClient

class IslandClient(context: Context)

星河岛客户端。context 可为任意上下文，客户端只保留其应用上下文。

IslandCallback

abstract class IslandCallback

按需重写，所有方法默认不做任何处理，都在主线程调用。事件尽力送达，不作为业务依据。

enum class EndReason { EXPIRED, REMOVED }

IslandResult

enum class IslandResult { OK, IMAGE_REJECTED, NO_PERMISSION, SOURCE_DISABLED, KIND_DISABLED, QUOTA_EXCEEDED, RATE_LIMITED, INVALID, BUSY, NOT_CONNECTED }

val accepted: Boolean：是否已受理（OK 或 IMAGE_REJECTED）。受理不等于已显示，例如本应用在前台、排位靠后时内容暂不显示。

IslandActivity

class IslandActivity   // 通过 IslandActivity.Builder 生成
class IslandActivity.Builder(id: String, capsule: Capsule, card: IslandCard)

放上星河岛的一条内容。id 为内容编号，本应用内唯一，1 至 128 个字符（不能为空白）。

异常：Builder(...) 在编号为空白或超过 128 个字符时抛出 IllegalArgumentException；setPostedAt、setStaleAt 在时间不大于 0 时抛出；setLandscapeText、setContentDescription 在文字为空白或超长时抛出；build() 在全部文字合计超过 8192 字节（UTF-8）时抛出。

只读属性：id、capsule、card、priority、alertOnStart、alertOnUpdate、lockScreenVisibility、openIntent、notificationId: Int?、notificationTag: String?、postedAtMillis: Long?、staleAtMillis: Long?、dismissPolicy、landscapeText、accentColor、contentDescription。

enum class Priority { LOW, DEFAULT, HIGH }

enum class LockScreenVisibility { PUBLIC, TITLE_ONLY, HIDDEN }

class DismissPolicy
  companion object {
    fun untilEnded(): DismissPolicy          // 一直显示，直到应用调用 end()；最长 8 小时
    fun afterMillis(millis: Long): DismissPolicy  // 显示后经过给定时长（大于 0，否则抛出 IllegalArgumentException）自动消失
  }

class Outro(val success: Boolean, val text: String)

结束内容时可选的收尾：胶囊上显示对勾（success = true）或叉号和一句话，约 1.6 秒后消失；只在这条内容仍在星河岛上时显示。text 为空白或超过 128 个字符时抛出 IllegalArgumentException。

Capsule

class Capsule   // 通过 Capsule.Builder 生成
class Capsule.Builder(leading: IslandImage)

胶囊：左侧一张图片（必填），可跟一段小标题；右侧一项信息；最右端可再固定一个小图或进度环。

只读属性：leading、leadingTint、breathing、label、trailing、tail、satellite。

CapsuleTrailing（胶囊右侧信息，静态工厂方法；颜色为 ARGB，null 时使用胶囊文字颜色或强调色，过暗的颜色会被提亮）：

CapsuleTail（胶囊最右端，静态工厂方法）：image(image: IslandImage)；progress(fraction: Float, color: Int? = null)（fraction 为 0 至 1）。

Satellite（副岛内容，静态工厂方法）：image(image: IslandImage)；progress(fraction: Float, image: IslandImage? = null, color: Int? = null)（进度环，环中间可放一张图片）。

以上工厂方法在文字为空白或超长、时间不大于 0、比例不在 0 至 1 之间（含非有限数）时抛出 IllegalArgumentException。

IslandImage 与 BuiltinSymbol

class IslandImage
  companion object {
    fun picture(bitmap: Bitmap): IslandImage   // 照片类图片：头像、封面、商品图、截图，按原图显示
    fun glyph(bitmap: Bitmap): IslandImage     // 单色图标：按内置符号样式显示（卡片上带圆形浅色底，胶囊中不加描边）
    fun symbol(symbol: BuiltinSymbol): IslandImage  // 星河岛内置符号
    fun appIcon(): IslandImage                 // 本应用的桌面图标，仅用于胶囊与副岛
  }
  val isAppIcon: Boolean
  val isPicture: Boolean

位图须满足：未被回收；宽和高均在 1 至 2048 像素之间；占用内存（Bitmap.getAllocationByteCount()）不超过 8 MB（8388608 字节）。不满足时 picture、glyph 抛出 IllegalArgumentException。

卡片上的图片（卡片左图、头像、标题小图、进度小图、对称标志）不接受 appIcon()：显示来源栏时，来源栏已显示应用图标与名称；用户关闭「显示应用来源」且卡片没有内容图片时，星河岛在卡片左侧显示应用图标。

enum class BuiltinSymbol：MUSIC（音乐）、TIMER（计时器）、ALARM（闹钟）、BATTERY（电池）、BOLT（闪电）、HEADPHONES（耳机）、BLUETOOTH（蓝牙）、MESSAGE（消息）、CHECK（对勾）、CLOSE（叉号）、PLAY（播放）、PAUSE（暂停）、SKIP_NEXT（下一首）、SKIP_PREV（上一首）、NAVIGATION（方向箭头）、HOURGLASS（沙漏）、INFO（提示）、DOWNLOAD（下载）。

IslandCard（展开卡片）

sealed class IslandCard { abstract val title: String }

九种子类：GenericCard、ProgressCard、EmphasisCard、DetailsCard、StatusCard、PictureCard、MediaCard、MessageCard、MirrorCard，均通过各自的 Builder 生成。

所有卡片的共同规则：

• 用户开启「显示应用来源」时，卡片顶部由星河岛写上来源栏：本应用的图标与名称（名称取自系统，应用无法修改）；设置了发送时间时在来源栏右侧写出时间。该开关位于星流「显示规则」页，默认关闭；关闭后不显示来源栏，卡片左侧没有内容图片时改为显示应用图标。
• 卡片左侧的图片只放内容自己的图片（头像、封面、商品图、符号），不接受应用图标。
• 文字长度按 UTF-16 字符计：标题最多 128 个字符，说明最多 256 个字符，正文最多 4096 个字符，其余短文字最多 32 个字符。必填文字不能为空白。
• 所有 setXxx 方法传入 null 表示不显示该项。
• 文字不合规时，对应的 Builder 构造方法或 setXxx 方法立即抛出 IllegalArgumentException；组合规则（按钮数量、必填项等）在 build() 时检查。

GenericCard（通用）

左侧图片，标题（右侧可放大显示一项数值或时间），说明一行，正文最多两行，底部按钮。

GenericCard.Builder(title: String)

属性：title、subtitle、body、image、value、tag、titleMark。

CardValue（静态工厂方法）：text(text: String, color: Int? = null, icon: IslandImage? = null)（数值，最多 32 个字符；颜色为 null 时使用强调色，过暗的颜色会被提亮；icon 为数值前的小图）；countdown(endAtMillis: Long)；stopwatch(startedAtMillis: Long)。

CardTag：CardTag(text: String?, icon: IslandImage? = null)。文字最多 32 个字符；文字与图标都为 null 时抛出 IllegalArgumentException。属性：text、icon。

ProgressCard（进度）

左侧图片，标题（右侧自动显示百分比），说明与正文，底部一条进度条；进度条可分阶段并在下方写阶段名，也可带一个随进度移动的小图（例如骑手）。适用于外卖、打车、下载、上传等。

ProgressCard.Builder(title: String)

属性：title、subtitle、body、image、fraction: Float?（null 表示进度不确定）、startLabel、endLabel、stages: List<String>、marker。

EmphasisCard（强调）

一张卡里最要紧的一串码或一段计时放大显示。

• 码（EmphasisValue.code）：标题作为上方一行小字写明是什么（例如「取件码」），码放大写在下方，说明与正文写在码下面。
• 计时（倒计时、正计时、已暂停）：左侧图片（未设置时为计时符号），标题与说明写在放大的时间上方，正文写在时间下方，右侧可放 TimerControl 控制按钮与圆形图标按钮。

EmphasisCard.Builder(title: String, value: EmphasisValue)

属性：title、value、subtitle、body、image、controls: List<TimerControl>。

EmphasisValue（静态工厂方法）：code(text: String)（最多 32 个字符）；countdown(endAtMillis: Long)（到点停在 00:00）；stopwatch(startedAtMillis: Long)；paused(durationMillis: Long)（已暂停的计时，静止显示给定时长，格式 mm:ss，满一小时为 h:mm:ss；时长不能为负数）。属性 isTimer: Boolean：是否为计时。

DetailsCard（明细）

通用卡片的排布，底部并排若干格（上方名称、下方数值），例如违章的车牌与时间、电影的场次与座位。

DetailsCard.Builder(title: String)

属性：title、subtitle、body、image、details: List<CardDetail>、tag、titleMark。

CardDetail：CardDetail(label: String, value: String)，名称与数值各最多 32 个字符。属性：label、value。

StatusCard（状态）

左侧图片，标题与说明，右侧放大显示一项数值或正计时，底部可带一条电量式的水平条；正文写在下方，最多两行。适用于设备连接、运行状态等。

StatusCard.Builder(title: String)

属性：title、subtitle、body、image、value、level: Float?、stopButton: Boolean。伴生常量：const val ACTION_STOP: String = "stop"。

StatusValue（静态工厂方法）：text(text: String)（最多 32 个字符，例如「85%」「已连接」）；stopwatch(startedAtMillis: Long)。

PictureCard（大图）

标题与一行正文，下方一张铺满卡片宽度的大图（最高约 140dp，超出部分居中裁切）。只有一个文字按钮时，按钮显示在标题右侧。锁屏只显示标题时不显示大图。

PictureCard.Builder(title: String, picture: IslandImage)：picture 须为 IslandImage.picture，否则抛出 IllegalArgumentException。

属性：title、picture、body。

MediaCard（音乐）

左侧封面，歌名与歌手，一行歌词，播放按键与进度条。进度由星河岛按播放状态与速度自行推进。播放按键排在右侧或歌词下方，由用户在星流「星河岛歌词」页选择的「音乐卡片样式」决定，应用无需处理。

MediaCard.Builder(title: String)：title 为歌名，最多 128 个字符。

属性：title、artist、cover、playing、durationMillis: Long?、positionMillis: Long?、positionAtMillis: Long?、playbackSpeed: Float、lyric、controls: Set<MediaControl>、seekable。音乐卡片不接受其他按钮。

MessageCard（消息）

左侧头像，发送者与最新一条消息（最多两行），可带回复输入框与按钮。消息卡片按新消息排位：刚送达时优先显示在主岛，停留一段时间后让位；设置了发送时间时，发送时间变化才算新的一条，未设置时标题或消息内容变化才算。

MessageCard.Builder(sender: String, text: String)：发送者最多 128 个字符；消息内容最多 4096 个字符，卡片上最多显示两行。

属性：title（发送者）、text、avatar、replyEnabled。

MirrorCard（对称）

左右两侧各写一个名称（可带标志与小字），中间放大显示两侧的比分，下方一行写比赛信息。尚无比分时，中间放大显示 setCenterText 设置的文字（例如「19:30 开赛」）。卡片不显示按钮。

MirrorCard.Builder(title: String, left: MirrorSide, right: MirrorSide)：title 不单独显示在卡片上，用于无障碍读屏。

属性：title、left、right、centerText、detail。

MirrorSide：MirrorSide(name: String, score: String? = null, logo: IslandImage? = null, note: String? = null)。名称、比分、小字各最多 32 个字符；logo 为名称上方的标志。属性：name、score、logo、note。

按钮

sealed class IslandButton(val id: String, val requiresUnlock: Boolean)

用户点击后，onAction 收到内容编号与按钮编号。requiresUnlock = true 时，锁屏状态下隐藏此按钮。

按钮编号：非空白，最多 64 个字符，同一张卡片内不得重复；不得使用 SDK 保留的编号 pause、resume、stop、toggle、prev、play_pause、next。违反时构造方法或 build() 抛出 IllegalArgumentException。

各类属性与构造参数同名。

enum class ButtonStyle { NORMAL, PRIMARY, DESTRUCTIVE }

NORMAL：灰色底；PRIMARY：强调色实心底，用于最主要的操作；DESTRUCTIVE：浅红底红字，用于删除、取消等操作。

enum class TimerControl(val actionId: String) { PAUSE("pause"), RESUME("resume"), STOP("stop") }

计时类强调卡片右侧的圆形控制按钮：PAUSE 暂停（强调色实心圆钮），RESUME 继续（强调色实心圆钮），STOP 结束（灰色圆钮，叉号）。

enum class MediaControl(val actionId: String) { PREVIOUS("prev"), PLAY_PAUSE("play_pause"), NEXT("next") }

音乐卡片的播放按键：上一首、播放或暂停（图形随播放状态切换）、下一首。

数量上限（每张卡片）：

各卡片可用的按钮：

按钮的具体位置由星河岛按卡片排布决定：例如只有一个文字按钮且第一行右侧空闲时，它显示为第一行右侧的小按钮。底部文字按钮的排法可用 setButtonLayout 调整，见「按钮排法」。

按钮排法

底部带字的按钮默认每排 3 个、各占三分之一；4 个时平均分两排、各两个；一排里只剩 1 个时占半排居中。可用卡片构建器的 setButtonLayout 按卡修改，不设置时按默认排法。

class ButtonLayout @JvmOverloads constructor(
    val perRow: Int = 3,
    val rowFill: RowFill = RowFill.EQUAL,
    val loneFill: LoneFill = LoneFill.HALF,
    val loneAlign: LoneAlign = LoneAlign.CENTER,
)

GenericCard.Builder("停车计费")
    .addButton(TextButton("pay", "缴费", ButtonStyle.PRIMARY))
    .addButton(TextButton("later", "稍后"))
    .addButton(TextButton("detail", "详情"))
    .setButtonLayout(ButtonLayout(perRow = 3))
    .build()

• 有底部文字按钮的卡片（通用、进度、强调、明细、状态、大图、消息）都可以设置；音乐与对称卡片没有文字按钮。
• 只影响底部排开的文字按钮。圆形按钮、底部图标按钮（一排最多 4 个）与开关（单独一排）不按这套排法。
• 四个是文字按钮的总数上限；每排个数大于按钮总数时按实际数量排。
• 设置只在 0.1.2 及以上的星河岛生效；旧版星河岛读不到这项设置，仍按每排两个排，不会报错。