kmpalette

这是一个用于从图像生成调色板（包括主色）的Compose Multiplatform库。你可以将此库与MaterialKolor结合使用，根据图像生成动态Material主题。

支持从多个来源加载图像，详见来源。

**注意：**这是androidx.palette库的移植版本。

你可以在demo.kmpalette.com查看Web演示。

目录

• 平台
• 灵感来源
• 动态Material主题
• 设置
  • 版本目录
• 使用方法
  • 主色
  • 生成调色板
  • 来源
• 演示
• 功能请求
• 贡献
• 许可证
  • 与原始源代码的变更

平台

这个库是为Compose Multiplatform编写的，可以在以下平台上使用：

灵感来源

我创建这个库是因为我想在Compose Multiplatform应用中使用androidx.palette库。但是那个库不是多平台的，所以我决定移植它。

动态Material主题

想要根据图像中的主色创建动态Material主题吗？

查看我的另一个Compose Multiplatform库MaterialKolor！

设置

你可以使用Gradle将这个库添加到你的项目中。有几个可选的扩展库，详见来源。

版本目录

在libs.versions.toml中：

[versions]
kmpalette = "3.1.0"

[libraries]
kmpalette-core = { module = "com.kmpalette:kmpalette-core", version.ref = "kmpalette" }
# 可选的源库
kmpalette-extensions-base64 = { module = "com.kmpalette:extensions-base64", version.ref = "kmpalette" }
kmpalette-extensions-bytearray = { module = "com.kmpalette:extensions-bytearray", version.ref = "kmpalette" }
kmpalette-extensions-libres = { module = "com.kmpalette:extensions-libres", version.ref = "kmpalette" }
kmpalette-extensions-network = { module = "com.kmpalette:extensions-network", version.ref = "kmpalette" }
kmpalette-extensions-file = { module = "com.kmpalette:extensions-file", version.ref = "kmpalette" }

要将其添加到多平台项目中，请将依赖项添加到公共源集：

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                // 核心库
                implementation(libs.kmpalette.core)

                // 基于你的图像源的可选扩展
                implementation(libs.kmpalette.extensions.base64)
                implementation(libs.kmpalette.extensions.bytearray)
                implementation(libs.kmpalette.extensions.libres)
                implementation(libs.kmpalette.extensions.network)
                implementation(libs.kmpalette.extensions.file)
            }
        }
    }
}

使用方法

要查看生成的KDocs，请访问docs.kmpalette.com

要使用这个库，你首先必须有一个ImageBitmap或Painter对象。

要获取ImageBitmap，你可以使用来源之一或使用为你创建它的库。

由于这个库是androidx.palette库的移植版本，使用方法非常相似。但是这个库提供了一些有用的扩展函数和可组合项。

在kmpalette-core中查找主库，包括Palette和Swatch对象的扩展。

包含了两个有用的@Composeable就绪的State对象：

• DominantColorState - 一个持有生成的主色Color对象的状态对象。
• PaletteState - 一个持有生成的Palette对象的状态对象。

它们可以这样使用：

主色

你可以使用rememberDominantColorState可组合项从ImageBitmap生成主色。这还将为你提供一个onColor作为文本颜色使用。

@Composable
fun SomeComposable(bitmap: ImageBitmap) {
    val dominantColorState = rememberDominantColorState()
    LaunchedEffect(bitmap) {
        dominantColorState.updateFrom(bitmap)
    }

    Box(
        modifier = Modifier
            .width(200.dp)
            .height(100.dp)
            .background(dominantColorState.color)
    ) {
        Text("Some Text", color = dominantColorState.onColor)
    }
}

你也可以通过指定DominantColorState.loader参数来使用Painter对象：

@Composable
fun SomeComposable(painter: Painter) {
    val loader = rememberPainterLoader()
    val dominantColorState = rememberDominantColorState(loader = loader)
    LaunchedEffect(painter) {
        dominantColorState.updateFrom(painter)
    }

    // ...
}

由于主色的生成是一个可能失败的异步操作，你可以使用DominantColorState.result对象跟踪操作的结果。

如果你想过滤主色，你可以向rememberDominantColorState()传递一个lambda：

val dominantColorState = rememberDominantColorState(
    isSwatchValid = { swatch ->
        swatch.color.contrastAgainst(MaterialTheme.colorScheme.surfaceColor) >= MinContrastRatio
    }
)
LaunchedEffect(bitmap) {
    dominantColorState.updateFrom(bitmap)
}

要查看获取主色的更多示例，请参阅演示应用

生成颜色调色板

如果你想要一个完整的颜色调色板而不仅仅是一个主色，你可以使用rememberPaletteState可组合函数。这将提供一个Palette对象，其中包含几种不同的颜色Swatch，每个都有自己的颜色和_onColor_。

使用ImageBitmap：

fun SomeComposable(bitmap: ImageBitmap) {
    val paletteState = rememberPaletteState()
    LaunchedEffect(bitmap) {
        paletteState.generate(bitmap)
    }

    Box(
        modifier = Modifier
            .width(200.dp)
            .height(100.dp)
            .background(paletteState.vibrantSwatch?.color ?: Color.White)
    ) {
        Text(
            "Some Text",
            color = paletteState.vibrantSwatch?.onColor ?: Color.Black,
        )
    }
}

或使用Painter：

fun SomeComposable(painter: Painter) {
    val loader = rememberPainterLoader()
    val paletteState = rememberPaletteState(loader = loader)
    LaunchedEffect(painter) {
        paletteState.generate(painter)
    }

    // ...
}

由于主色的生成是一个可能失败的异步操作，你可以通过DominantColorState.result对象跟踪操作的结果。

要查看生成调色板的更多示例，请参阅演示应用

来源

kmpalette-core库提供了从ImageBitmap或Painter对象生成颜色调色板的核心功能。

该库为一些流行的来源提供了一些扩展工件。

这些扩展中的每一个都提供了一个ImageBitmapLoader对象，可用于从输入类生成ImageBitmap。例如，NetworkLoader可用于从Url生成ImageBitmap：

@Composable
fun SomeComposable(url: Url) {
    val networkLoader = rememberNetworkLoader()
    val dominantColorState = rememberDominantColorState(loader = networkLoader)
    LaunchedEffect(url) {
        dominantColorState.updateFrom(url)
    }

    Box(
        modifier = Modifier
            .width(200.dp)
            .height(100.dp)
            .background(dominantColorState.color)
    ) {
        Text("Some Text", color = dominantColorState.onColor)
    }
}

Compose跨平台资源

从Compose跨平台1.6.0开始，处理资源的方式发生了变化。因此，本库已删除其扩展，因为不再需要它。

要从DrawableResource生成调色板，你可以使用@Composable imageResource()获取ImageBitmap，然后将其传递给默认加载器。

@Composable
fun MyComposeable() {
    val image = imageResource(R.drawable.my_image)
    val dominantColorState = rememberDominantColorState()
    LaunchedEffect(url) {
        dominantColorState.updateFrom(image)
    }
}

演示

在demo目录中提供了一个演示应用。它是一个在Android、iOS和桌面上运行的Compose跨平台应用。

有关更多信息，请参阅README。

功能请求

如果你有功能请求，请开一个issue。如果你想实现功能请求，请参阅贡献部分。

贡献

我们始终欢迎贡献！如果你想贡献，请随时创建PR或开启issue。

许可证

androidx-palette模块根据Apache许可证2.0版获得许可。有关更多信息，请参阅他们的LICENSE和他们的仓库这里。

原始源代码的变更

• 将Java代码转换为Kotlin
• 将库转换为Kotlin跨平台

对于其余代码，请参阅LICENSE获取更多信息。