Splitties

Splitties 是一个小型 Kotlin 多平台库的集合（以 Android 为首要目标）。

这些库旨在减少你需要编写的代码量，节省代码阅读和编写时间，让你能更专注于为用户（即使只有你自己）构建想要的功能，或有更多时间来"玩乐"。

这个项目之所以命名为"Splitties"，是因为它被拆分成小模块，作为独立的库分发，所以你可以只添加项目/模块中需要的部分，有助于减少用户设备需要下载和保存在有限存储空间中的最终二进制文件的大小（顺便说一下，一切资源都是有限的）。

一些面向 Android 的模块提供了类似 Anko 的功能。这里有 Splitties 与 Anko 的简短对比。

每个模块都经过设计，具有小巧的体积和尽可能高的效率。

一些示例

Splitties 的核心是简化你的代码。以下是一些示例：

Kotlin:

startActivity(Intent(this, DemoActivity::class.java))

使用 Splitties Activities 的 Kotlin:

start<DemoActivity>()

Kotlin:

Snackbar.make(root, R.string.refresh_successful, Snackbar.LENGTH_SHORT)
    .show()

使用 Splitties Snackbar 的 Kotlin:

root.snack(R.string.refresh_successful)

协程竞速： （raceOf(…) 来自协程模块）

suspend fun awaitUserChoice(ui: SomeUi, choices: List<Stuff>): Stuff? = raceOf({
    ui.awaitSomeUserAction(choices)
}, {
    ui.awaitDismissal()
    null
}, {
    ui.showSomethingInRealtimeUntilCancelled() // 返回 Nothing，会运行但永远不会"获胜"。
})

Kotlin:

Snackbar.make(root, getString(R.string.deleted_x_items, deletedCount), Snackbar.LENGTH_LONG)
    .setAction(android.R.string.cancel) {
        deleteOperation.requestRollback()
    }
    .setActionTextColor(ContextCompat.getColor(this, R.color.fancy_color))
    .show()

使用 Splitties Snackbar 的 Kotlin:

root.longSnack(str(R.string.deleted_x_items, deletedCount)) {
    action(android.R.string.cancel, textColor = color(R.color.fancy_color)) {
        deleteOperation.requestRollback()
    }
}

概览

系统交互（仅 Android）
用户输入和用户界面相关的拆分
应用内和跨应用通信：Activities、Fragments、Intents 和 Bundles
并发（多平台）
数据持久化（多平台）
实用工具（多平台）
调试（仅 Android）
遗留（仅 Android）

系统交互（仅 Android）：

[App Context:](https://github.com/LouisCAD/Splitties/blob/main/modules/appctx 使用 appCtx 随时获取应用程序的 Context。
[System Services:](https://github.com/LouisCAD/Splitties/blob/main/modules/systemservices 不再需要 context.getSystemService(NAME_OF_SERVICE) as NameOfManager。

用户输入和用户界面相关的拆分：

小型消息（仅 Android）

[Snackbar:](https://github.com/LouisCAD/Splitties/blob/main/modules/snackbar 使用 snack(…) 和 longSnack(…) 简单地显示 Snackbar。
[Toast:](https://github.com/LouisCAD/Splitties/blob/main/modules/toast 只需调用 toast(yourText) 显示 Toast，并避免 API 25 的 BadTokenException。

对话框（仅 Android）

[Alert Dialog:](https://github.com/LouisCAD/Splitties/blob/main/modules/alertdialog 使用简单的代码创建简单的警告对话框。
[Alert Dialog AppCompat:](https://github.com/LouisCAD/Splitties/blob/main/modules/alertdialog-appcompat Alert Dialog 的 AppCompat 版本。
[Alert Dialog AppCompat Coroutines:](https://github.com/LouisCAD/Splitties/blob/main/modules/alertdialog-appcompat-coroutines AppCompat AlertDialog 的 showAndAwait 扩展函数。
[Alert Dialog Material:](https://github.com/LouisCAD/Splitties/blob/main/modules/alertdialog-appcompat Alert Dialog AppCompat 的 Material Components 扩展。

系统 UI（仅 Android）

[Dangerous permissions:](https://github.com/LouisCAD/Splitties/blob/main/modules/permissions 请求运行时权限，不污染你的代码库。

View 扩展（仅 Android）

Views: View 的扩展函数和属性。
Views AppCompat: Views 的 AppCompat 扩展。包括 ImageView 着色、ActionBar 和工具提示的辅助函数。
Views CardView: Views 的 CardView 扩展。提供 contentPadding 属性。
Views Material: Views 的 Material Components 扩展。
Views Coroutines Material: Material Components 与 Kotlin 协程结合。
Views RecyclerView: Views 的 RecyclerView 扩展。
Views Coroutines: Android Views 与 Kotlin 协程结合。

使用 Kotlin 的强大功能创建基于 View 的 UI（仅限 Android）

Views DSL: 使用易读的 Kotlin 代码创建 UI（支持 IDE 预览）。
Views DSL AppCompat: Views DSL 的 AppCompat 扩展。
Views DSL ConstraintLayout: Views DSL 的 ConstraintLayout 扩展。
Views DSL CoordinatorLayout: Views DSL 的 CoordinatorLayout 扩展。
Views DSL Material: Views DSL 的 Material Components 扩展。
Views DSL RecyclerView: Views DSL 的 RecyclerView 扩展。

各种 UI 实用工具（仅限 Android）

Resources: 轻松获取字符串、颜色或可绘制资源的扩展，支持主题属性。
Dimensions: Android dp 对 View 和 Context 的扩展。在使用 Views DSL 时特别方便。
可选择的视图
- Selectable Views: 在 API 23 之前具有 foreground 属性的可选择视图。
- Selectable Views AppCompat: 适用于 AppCompatTextView 的可选择视图。
- Selectable Views ConstraintLayout: 适用于 ConstraintLayout 的可选择视图。
Typesafe RecyclerView: 类型安全的 ViewHolder 和 ItemViewHolder，便于 RecyclerView 的基本使用。

Material Design 辅助工具（仅限 Android）

Material Colors: 2014 年 Material Design 调色板作为颜色资源。
Material Lists: 实现 Material Design 指南的列表项视图（非常适合在 RecyclerView 中使用）。

应用内和跨应用通信：Activities、Fragments、Intents 和 Bundles

Activities: 以最少的样板代码启动活动。
Intents: 将 companion object 转换为强大的类型安全 intent 规范，并以简洁易用的方式创建 PendingIntent。
Fragments: 以最少的样板代码从片段启动活动并执行事务。
Fragment Args: 通过委托属性实现无需繁琐操作的片段参数。
Bundle: 使用 BundleSpec 通过属性语法为 Intent 附加信息等操作 Bundle。

并发（多平台）

协程: kotlinx.coroutines的通用扩展。
生命周期协程(仅限Android): 与AndroidX Lifecycle 的协程集成。
主线程: 与主线程相关的属性和前提条件检查器。
主处理程序(仅限Android): 顶级 mainHandler 属性，用于停止为主 Looper 分配多个 Handler。
检查延迟(仅限Android): mainThreadLazy 在主线程上检查属性访问。

数据持久化(多平台)

首选项: Android的 SharedPreferences/DataStore 和macOS/iOS/watchOS的 NSUserDefaults 的属性语法。
Arch Room: 用Kotlin实例化数据库和执行事务的Room辅助工具。

实用工具(多平台)

位标志: Long、Int、Short、Byte 及其无符号对应项的 hasFlag、withFlag 和 minusFlag 扩展。
集合: 无需 Iterator 分配的 List 的 forEach。

调试(仅限Android)

Stetho初始化: 在调试版本中使用 [Stetho]，无需编写任何代码！

遗留(仅限Android)

异常: unexpectedValue(…)、unsupportedAction(…) 和类似的返回 Nothing 的函数。
Arch生命周期: 获取 ViewModel、使用 LiveData 和观察 Lifecycle 的扩展。

下载

Gradle说明

确保在项目的(根) build.gradle 文件中定义的仓库中包含 mavenCentral() (新的Android Studio项目默认包含)。

为了更容易利用Splitties的内容来开发Android项目，有一些组合构件包含了大多数的splits。

Android基础

使用 [refreshVersions] 添加：Splitties.pack.androidBase 或 Splitties.pack.androidBaseWithViewsDsl。

这两个包不包含AppCompat，适用于WearOS应用。

包含以下模块： [activities]、[appctx]、[bitflags]、[bundle]、[collections]、[coroutines]、[dimensions]、[fragments]、[fragmentargs]、[intents]、[lifecycle-coroutines]、[mainhandler]、[mainthread]、[material-colors]、[permissions]、[preferences]、[resources]、[systemservices]、[toast]、[views]、[views-coroutines]、[views-recyclerview]、[views-selectable]、[views-selectable-constraintlayout]

Gradle依赖：

implementation("com.louiscad.splitties:splitties-fun-pack-android-base:3.0.0")

还有一个包含Views DSL的版本。它额外包含以下模块：

[views-dsl]、[views-dsl-constraintlayout]、[views-dsl-recyclerview]

Gradle依赖：

implementation("com.louiscad.splitties:splitties-fun-pack-android-base-with-views-dsl:3.0.0")

Android AppCompat

使用 refreshVersions 添加：Splitties.pack.appCompat 或 Splitties.pack.appCompatWithViewsDsl。

这两个包包含了 Android 基础包和以下模块：

[alertdialog-appcompat](https://github.com/LouisCAD/Splitties/blob/main/modules/alertdialog-appcompat
[alertdialog-appcompat-coroutines](https://github.com/LouisCAD/Splitties/blob/main/modules/alertdialog-appcompat-coroutines
[views-appcompat](https://github.com/LouisCAD/Splitties/blob/main/modules/views-appcompat
[views-selectable-appcompat](https://github.com/LouisCAD/Splitties/blob/main/modules/views-selectable-appcompat

Gradle 依赖：

implementation("com.louiscad.splitties:splitties-fun-pack-android-appcompat:3.0.0")

还有一个带 Views DSL 的版本。它额外包含了 Android 基础包的 Views DSL 版本和以下模块：

[views-dsl-appcompat](https://github.com/LouisCAD/Splitties/blob/main/modules/views-dsl-appcompat

Gradle 依赖：

implementation("com.louiscad.splitties:splitties-fun-pack-android-appcompat-with-views-dsl:3.0.0")

Android Material Components

使用 refreshVersions 添加：Splitties.pack.androidMdc 或 Splitties.pack.androidMdcWithViewsDsl。

这两个包包含了 Android AppCompat 包和以下模块：

[alertdialog-material](https://github.com/LouisCAD/Splitties/blob/main/modules/alertdialog-material
[material-lists](https://github.com/LouisCAD/Splitties/blob/main/modules/material-lists
[snackbar](https://github.com/LouisCAD/Splitties/blob/main/modules/snackbar
[views-cardview](https://github.com/LouisCAD/Splitties/blob/main/modules/views-cardview
[views-coroutines-material](https://github.com/LouisCAD/Splitties/blob/main/modules/views-coroutines-material
[views-material](https://github.com/LouisCAD/Splitties/blob/main/modules/views-material

Gradle 依赖：

implementation("com.louiscad.splitties:splitties-fun-pack-android-material-components:3.0.0")

还有一个带 Views DSL 的版本。它额外包含了 Android AppCompat 包的 Views DSL 版本和以下模块：

[views-dsl-coordinatorlayout](https://github.com/LouisCAD/Splitties/blob/main/modules/views-dsl-coordinatorlayout
[views-dsl-material](https://github.com/LouisCAD/Splitties/blob/main/modules/views-dsl-material

Gradle 依赖：

implementation("com.louiscad.splitties:splitties-fun-pack-android-material-components-with-views-dsl:3.0.0")

所有构件（47个）

由于您可能会使用多个构件，为了避免重复，我们建议您将版本放在一个集中的位置，这样升级到新版本时就不需要太多工作。

最好的方法是使用 refreshVersions，它为 Splitties 内置了依赖符号，还包括许多其他流行和高质量的库，如 kotlinx、AndroidX、Square/CashApp 的库和 Google 的库。

最重要的是，使用它运行 refreshVersions 任务可以在几秒钟内显示所有依赖项的可用更新，直接显示在 versions.properties 中，使升级变得轻而易举，甚至只需使用键盘即可完成。

供您参考，Splitties 的当前最新版本是 3.0.0

<details> <summary> <b>以下是此库所有构件的 Maven 坐标，供参考。（点击展开）</b> </summary> ``` com.louiscad.splitties:splitties-activities com.louiscad.splitties:splitties-alertdialog com.louiscad.splitties:splitties-alertdialog-appcompat com.louiscad.splitties:splitties-alertdialog-appcompat-coroutines com.louiscad.splitties:splitties-appctx com.louiscad.splitties:splitties-arch-lifecycle com.louiscad.splitties:splitties-arch-room com.louiscad.splitties:splitties-bitflags com.louiscad.splitties:splitties-bundle com.louiscad.splitties:splitties-checkedlazy com.louiscad.splitties:splitties-collections com.louiscad.splitties:splitties-coroutines com.louiscad.splitties:splitties-dimensions com.louiscad.splitties:splitties-exceptions com.louiscad.splitties:splitties-fragments com.louiscad.splitties:splitties-fragmentargs com.louiscad.splitties:splitties-intents com.louiscad.splitties:splitties-lifecycle-coroutines com.louiscad.splitties:splitties-mainhandler com.louiscad.splitties:splitties-mainthread com.louiscad.splitties:splitties-material-colors com.louiscad.splitties:splitties-material-lists com.louiscad.splitties:splitties-permissions com.louiscad.splitties:splitties-preferences com.louiscad.splitties:splitties-resources com.louiscad.splitties:splitties-snackbar com.louiscad.splitties:splitties-stetho-init com.louiscad.splitties:splitties-systemservices com.louiscad.splitties:splitties-toast com.louiscad.splitties:splitties-typesaferecyclerview com.louiscad.splitties:splitties-views com.louiscad.splitties:splitties-views-appcompat com.louiscad.splitties:splitties-views-cardview com.louiscad.splitties:splitties-views-coroutines com.louiscad.splitties:splitties-views-coroutines-material com.louiscad.splitties:splitties-views-dsl com.louiscad.splitties:splitties-views-dsl-appcompat com.louiscad.splitties:splitties-views-dsl-constraintlayout com.louiscad.splitties:splitties-views-dsl-coordinatorlayout com.louiscad.splitties:splitties-views-dsl-ide-preview com.louiscad.splitties:splitties-views-dsl-material com.louiscad.splitties:splitties-views-dsl-recyclerview com.louiscad.splitties:splitties-views-material com.louiscad.splitties:splitties-views-recyclerview com.louiscad.splitties:splitties-views-selectable com.louiscad.splitties:splitties-views-selectable-appcompat com.louiscad.splitties:splitties-views-selectable-constraintlayout ```

快照版本

假设你需要尝试一个尚未正式发布的新功能或修复：

你可以通过添加相应的仓库来获取快照版本，如下所示，并将库版本更改为最新的快照版本 3.0.0-SNAPSHOT：

allProjects {
    repositories {
        mavenCentral()
        google() // 在下面添加 sonatype 快照仓库
        maven(url = "https://oss.sonatype.org/content/repositories/snapshots")
    }
}

新版本通知

发布会在 GitHub 上公布，你可以通过点击"Watch"，然后选择"Releases only"来订阅。

然而，如果你使用 refreshVersions，当你运行 refreshVersions 任务时，你也会在 versions.properties 文件中了解到更新信息。

改进这个库

如果你希望这个库在新模块或现有模块中有新功能或改进，请先开一个 issue 或对类似的 issue 进行投票/评论，以便讨论。

文档贡献也受欢迎。对于拼写错误或其他小改进，可以直接提交 PR（拉取请求）。对于更重要的文档贡献，请先开一个 issue 进行讨论。

如果你发现了 bug，请开一个 issue 并提供所有重要细节。如果你知道一个简单的修复方法，不会破坏 API 且不需要考虑副作用，你也可以直接提交 PR。

你还可以加入 Kotlin Slack 的 #splitties 频道参与讨论（你可以在这里获得邀请）。

什么是 split

"split"是 Splitties 库的一个模块，你可以将其添加为依赖项。它只包含所需的传递依赖。这允许你只在你的应用或库模块中添加所需的内容，使最终的 apk/ipa/app 尽可能小，不包含应用未使用的内容。

假设你正在使用 Views DSL 构建一个 Wear OS 应用。Wear OS 应用不需要 AppCompat。包含它会浪费带宽和存储空间。Views DSL 核心模块依赖于 Android SDK，但不依赖于 AppCompat，所以使用 Views DSL 不会使你的手表应用膨胀。然而，如果你正在构建手机、平板电脑或计算机 Android 应用，有一个 Views DSL AppCompat split 提供了一些扩展供你使用。

致谢特别感谢 Jovche Mitrejchevski 在本项目决策过程中提供的帮助。

感谢 JetBrains 和贡献者们开发了 Anko，它是一个很好的灵感来源，特别是对于 Views DSL 而言。当然也要感谢优秀的 Kotlin 编程语言，使得这个项目成为可能。

感谢 Doug Stevenson 撰写的文章"Kotlin 和 Android：一次实际的实验"。可以说，Views DSL 的根源就在这个实验中。