🍞 KToast

英文文档 English Document

KToast 是一个专为 Android 设计的现代化、轻量级且高度可定制的 Toast 框架。基于 Kotlin 编写，完美兼容 Android 5.0 至最新系统。

它在旧版本上提供了一致的现代化 UI 体验，同时优雅地解决了 Android 11+ (API 30+) 对自定义 Toast 的限制。

✨ 核心特性

• 🛠️ 零配置启动：基于 Jetpack App Startup，集成即用，无需在 Application 手动初始化。
• 🚀 极简调用：Kotlin 扩展函数支持，一行代码搞定显示。
• 🎨 高度定制：支持自定义背景、圆角、图标、动画时长、位置偏移等。
• 🛡️ 系统兼容：完美适配 Android 11+。前台使用自定义 Window 渲染（无权限），后台自动降级为系统原生 Toast。
• ⚡ 生命周期感知：自动感知 Activity 状态，防止内存泄漏和崩溃。
• 👆 交互增强：支持点击气泡立即消失 (cancelOnTouch)。
• ⏱️ 延时任务：支持非阻塞的延时显示 (toastDelayed) 和撤回机制。
• 🐞 调试模式：提供 debugShow 仅在开发环境显示，不污染线上环境。
• ☕ Java 兼容：对 Java 项目友好，提供静态方法调用。

---

引入

Gradle:

1. 在Project的 build.gradle 或 setting.gradle 中添加远程仓库

   repositories {
       //
       mavenCentral()
   }

2. 在Module的 build.gradle 中添加依赖项

   implementation 'io.github.logan0817:KToast:1.0.3' // 替换为上方徽章显示的最新版本

效果展示

你也可以直接下载 演示App 体验效果

🚀 快速开始

1. 基础调用

在任何地方直接调用扩展函数：

// 显示文本
"Hello KToast!".toast()

// 显示资源 ID
R.string.app_name.toast()

2. 全局配置 (可选)

得益于 Zero-Config 设计，你不需要写 init。如果需要定制全局样式，建议在 Application.onCreate 中调用：

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        //✅ 全局配置
        KToast.debug(BuildConfig.DEBUG).config {
            textColor = Color.WHITE
            backgroundColor = Color.parseColor("#E6323232")
            backgroundRadius = 24f
            gravity = Gravity.CENTER
            yOffset = 0
            textSize = 14f
        }
    }
}

3. DSL 个性化配置

"保存成功".toast {
    backgroundColor = Color.parseColor("#4CAF50") // 绿色背景
    textColor = Color.WHITE
    icon = R.drawable.ic_success // 设置图标
    gravity = Gravity.CENTER // 居中显示
    backgroundRadius = 50f // 全圆角
}

🛠️ 进阶功能

延时显示 (Delayed Show)

支持延时显示，且返回任务句柄，可随时撤回。

// 2秒后显示
val task = "稍后跳转...".toastDelayed(2000L)

// 如果用户提前退出了页面，可以撤回
KToast.cancelDelayed(task)
KToast.cancel()

调试模式 (Debug Show)

仅当 KToast.debugMode = true 时才会显示，适合打印接口错误或埋点信息。

"API Error: 500".debugShow()

可交互 (点击消失)

"点击我可以立即关闭".toast {
    cancelOnTouch = true
    animationDuration = 500L // 慢动作动画
}

Java 调用

// 全局配置
KToast.debug(BuildConfig.DEBUG);
KToast.config(config -> {
        config.setBackgroundColor(Color.RED);
  return Unit.INSTANCE;
});

// 显示
KToast.show("来自 Java 的调用");

⚙️ 配置项详解 (KToastConfig)

你可以在 KToast.config {} (全局) 或 .toast {} (局部) 中设置以下属性：

属性名	类型	默认值	说明
textColor	Int	White	文本颜色
backgroundColor	Int	#E6323232	背景颜色 (支持 Alpha)
backgroundRadius	Float	24f	背景圆角 (dp)
gravity	Int	Bottom	显示位置
xOffset	Int	0	X 轴偏移量 (px)
yOffset	Int	64	Y 轴偏移量 (px)
textSize	Float	14f	字体大小 (sp)
paddingHorizontal	Int	24	水平内边距 (dp)
paddingVertical	Int	12	垂直内边距 (dp)
animationDuration	Long	250	弹出/消失动画时长 (ms)
cancelOnTouch	Boolean	false	是否允许点击消失
icon	Int?	null	图标资源 ID
iconSize	Float	24f	图标大小 (dp)

💡 最佳实践 (Best Practices)

强烈建议在你的 App 模块中创建一个扩展文件 AppToastExt.kt，根据你的 UI 设计规范封装统一的样式。这能保持 Library 的纯净，同时让业务调用更简单。

APP层扩展 可以参考 AppToastExt

// AppToastExt.kt

/** 显示成功提示 (绿色) */
fun CharSequence.showSuccess() {
    this.toast {
        backgroundColor = Color.parseColor("#4CAF50")
        icon = R.drawable.ic_check_circle
    }
}

/** 显示错误提示 (红色) */
fun CharSequence.showError() {
    this.toast {
        backgroundColor = Color.parseColor("#F44336")
        icon = R.drawable.ic_error
    }
}

// 调用
"登录成功".showSuccess()

🔒 混淆配置 (Proguard)

库内部已经包含了 consumer-rules.pro，通常情况下你不需要手动添加任何规则。

---

License

MIT License

Copyright (c) 2026 Logan Gan

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.