kmpalette

Maven Central

badge-android badge-ios badge-desktop badge-js

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

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

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

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

平台

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

构件	Android	Desktop	iOS	macOS	Browser
`core`	✅	✅	✅	✅	✅
`extensions-base64`	✅	✅	✅	✅	✅
`extensions-bytearray`	✅	✅	✅	✅	✅
`extensions-libres`	✅	✅	✅	✅	✅
`extensions-network`	✅	✅	✅	✅	✅
`extensions-file`	✅	✅	✅	✅	❌

灵感来源

我创建这个库是因为我想在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对象生成颜色调色板的核心功能。

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

工件	库	加载器	输入类	演示
`extensions-base64`	不适用	`Base64Loader`	`String`	`Base64DemoScreen`
`extensions-bytearray`	不适用	`ByteArrayLoader`	`ByteArray`	不适用
`extensions-libres`	libres	`LibresLoader`	`Image`	`LibresPaletteScreen`
`extensions-network`	ktor	`NetworkLoader`	`Url`	`NetworkDemoScreen`
`extensions-file`	okio	`PathLoader`, `FilePathLoader`	`Path`, `String`	不适用

这些扩展中的每一个都提供了一个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)
    }
}