lh-ui-android

Appearance

Toast 轻提示 ​

自持可见性与计时的墨色胶囊浮层，用于轻量级操作反馈。不阻塞用户操作。

契约源：lh-ui-core/specs/toast.json · 黄金用例：cases/toast.json（6 条，状态机 4 条 + 渲染 2 条，全部翻译为本地测试）

用法 ​

toast 是自持状态机：状态由 LhToastState 承载，宿主调用 show(text) 显示、hide() 隐藏， 计时到期自动隐藏并触发 onClose。组件在可见时按帧自驱动 tick，宿主也可自行调用接管计时。

9:41Toast
操作成功

HTML 模拟预览（Android / Compose 外观），非真机渲染

kotlin
val state = rememberLhToastState(onClose = { /* 可选：记录关闭 */ })
Column {
  LhButton(onClick = { state.show("已保存") }) { Text("触发") }
  LhToast(state = state)
}

语义类型 ​

非 default 类型时在文字前绘制直径等于字号的语义色圆点。

9:41Toast 类型
成功提示
警告提示
失败提示
主要提示

HTML 模拟预览（Android / Compose 外观），非真机渲染

定位 ​

position 取 top / center / bottom，两端各留 spacing.xl 边距；宽度由文字测量得出并封顶可用宽度的 80%。

9:41Toast 定位
顶部
底部

HTML 模拟预览（Android / Compose 外观），非真机渲染

API ​

Props ​

属性说明类型默认值
state轻提示状态机（承载可见性、文字与计时）LhToastState—
type语义类型；非 default 时绘制语义色圆点LhToastTypedefault
position在可用区域内的定位LhToastPositioncenter
modifier修饰符（作用于胶囊）ModifierModifier

LhToastState ​

成员说明
show(text: String)显示并重置计时
hide()立即隐藏，不触发 onClose
tick(deltaMs: Int): Boolean推进计时；到期时隐藏、触发 onClose 并返回 true
visible / text / duration当前状态（可观察）

工厂：rememberLhToastState(duration = 2000, onClose = {})。

LhToastType / LhToastPosition ​

值圆点色
default无圆点
primary / success / warning / danger / info对应语义色

LhToastPosition：top / center / bottom。

令牌对照 ​

令牌用途
toast.maxWidth胶囊最大宽度（240dp；实际取可用宽度 80% 与之较小）
toast.borderRadius胶囊圆角（跟随 radius.base）
toast.paddingHorizontal / toast.paddingVertical胶囊内边距
toast.fontSize文字字号（圆点直径同此值）
toast.gap圆点与文字间距
zIndex.toast层级语义对齐（Compose Popup 自带窗口级层级）
color.background.overlay（主题层 ink 映射）胶囊底色
color.onPrimary文字色
color.{primary,success,warning,danger,info}.default语义圆点色

黄金用例对照 ​

case id断言本地测试
show-makes-visibleshow 后可见且渲染文字LhToastDefaultsTest.show_makes_visible_and_renders_text
auto-hides-after-duration到期自动隐藏并触发 onCloseLhToastDefaultsTest.auto_hides_after_duration_and_emits_onClose + LhToastTest.auto_hides_after_duration
tick-before-duration-keeps-visible计时未到保持可见且不触发 onCloseLhToastDefaultsTest.tick_before_duration_keeps_visible_and_does_not_emit
hide-is-silenthide 不触发 onCloseLhToastDefaultsTest.hide_is_silent
success-type-uses-success-tokensuccess 类型消费成功色LhToastDefaultsTest.success_type_uses_success_tokens
hidden-emits-no-commands不可见时不渲染LhToastTest.hidden_toast_renders_nothing
bash
./gradlew :components:toast:test                                  # JVM 部分
./gradlew :components:toast:connectedAndroidTest                 # 交互部分（需设备）