使用 Palette API 選取顏色

良好的視覺設計對成功的應用程式至關重要，色彩配置是設計的主要元件。調色盤程式庫是 Jetpack 程式庫，可從圖片中擷取醒目顯示色彩，以便建立視覺上引人入勝的應用程式。

您可以使用調色盤程式庫設計版面配置主題，並將自訂顏色套用至應用程式中的視覺元素。舉例來說，您可以使用調色盤為歌曲建立色彩協調的標題卡，或在背景圖片變更時調整應用程式的工具列顏色。Palette 物件可讓您存取 Bitmap 圖片中的顏色，同時也提供點陣圖中的六個主要色彩設定檔，以供您進行設計選擇。

設定程式庫

如要使用 Palette 程式庫，請將下列內容新增至 build.gradle：

Kotlin

android {
    compileSdkVersion(33)
    ...
}

dependencies {
    ...
    implementation("androidx.palette:palette:1.0.0")
}

Groovy

android {
    compileSdkVersion 33
    ...
}

dependencies {
    ...
    implementation 'androidx.palette:palette:1.0.0'
}

建立色版

Palette 物件可讓您存取圖片中的主要顏色，以及疊加文字的對應顏色。使用調色盤設計應用程式樣式，並根據指定的來源圖片動態變更應用程式的色彩配置。

如要建立色盤，請先從 Bitmap 例項化 Palette.Builder。您可以使用 Palette.Builder 自訂色版，然後再產生色版。本節說明如何從點陣圖圖片產生及自訂色版。

產生 Palette 例項

使用其 from(Bitmap bitmap) 方法產生 Palette 例項，先從 Bitmap 建立 Palette.Builder。

建構工具可以同步或非同步產生色版。如果您想在呼叫方法的相同執行緒上建立調色盤，請使用同步調色盤產生功能。如果您在不同的執行緒上以非同步方式產生調色盤，請使用 onGenerated() 方法，在建立調色盤後立即存取。

以下程式碼片段提供這兩種調色盤產生方式的範例方法：

Kotlin

// Generate palette synchronously and return it.
fun createPaletteSync(bitmap: Bitmap): Palette = Palette.from(bitmap).generate()

// Generate palette asynchronously and use it on a different thread using onGenerated().
fun createPaletteAsync(bitmap: Bitmap) {
    Palette.from(bitmap).generate { palette ->
        // Use generated instance.
    }
}

Java

// Generate palette synchronously and return it.
public Palette createPaletteSync(Bitmap bitmap) {
  Palette p = Palette.from(bitmap).generate();
  return p;
}

// Generate palette asynchronously and use it on a different thread using onGenerated().
public void createPaletteAsync(Bitmap bitmap) {
  Palette.from(bitmap).generate(new PaletteAsyncListener() {
    public void onGenerated(Palette p) {
      // Use generated instance.
    }
  });
}

如果您需要為排序圖片或物件的清單持續產生色版，建議您快取 Palette 例項，以免 UI 效能變慢。請勿在主執行緒上建立色版。

自訂調色盤

Palette.Builder 可讓您自訂調色盤，方法是選擇產生調色盤的顏色數量、建構工具用來產生調色盤的圖片區域，以及調色盤包含的顏色。例如，您可以過濾掉黑色，或確保建構工具只使用圖片的上半部產生調色盤。

使用下列 Palette.Builder 類別的方法調整調色盤的大小和顏色：

addFilter()
這個方法會新增篩選器，指出結果區塊中允許的色彩。傳入您自己的 Palette.Filter，並修改其 isAllowed() 方法，以決定要從調色盤中篩除哪些顏色。
maximumColorCount()
這個方法可設定調色盤的顏色上限。預設值為 16，最佳值則取決於來源圖片。對於風景照，最佳值範圍為 8 到 16，而人像照的值通常介於 24 到 32 之間。Palette.Builder 產生色彩較多的調色盤所需的時間會更長。
setRegion()
這個方法會指出建構工具在建立色盤時使用的點陣圖區域。您只能在從點陣圖產生色盤時使用此方法，且不會影響原始圖片。
addTarget()
這個方法可讓您在建構工具中新增 Target 顏色設定檔，自行執行顏色比對。如果預設的 Target 不足，進階開發人員可以使用 Target.Builder 自行建立 Target。

擷取顏色剖析檔

根據Material Design 標準，調色盤程式庫會從圖片中擷取常用的色彩設定檔。每個設定檔都是由 Target 定義，而從點陣圖圖片中擷取的顏色會根據飽和度、亮度和母體 (在點陣圖中以色彩表示的像素數) 為每個設定檔評分。對於每個色彩設定檔，分數最高的顏色會定義該指定圖片的色彩設定檔。

根據預設，Palette 物件包含指定圖片的 16 種主要顏色。產生調色盤時，您可以使用 Palette.Builder 自訂調色盤的顏色數量。擷取更多顏色可為每個色彩設定檔提供更多可能的配對結果，但也會導致 Palette.Builder 在產生調色盤時耗費更多時間。

調色盤程式庫會嘗試擷取以下六種色彩設定檔：

  • 淺色鮮明
  • 繽紛
  • 深色鮮豔
  • 淡色調 (已調低)
  • 已忽略
  • 深色調調色

Palette 中的每個 get<Profile>Color() 方法都會傳回色票中的顏色，並與該特定設定檔建立關聯，其中 <Profile> 會替換為六個色彩設定檔之一的名稱。舉例來說，取得深色鮮明色彩設定檔的方法為 getDarkVibrantColor()。由於並非所有圖片都包含所有色彩設定檔，請提供要傳回的預設顏色。

圖 1 顯示相片和 get<Profile>Color() 方法的對應色彩設定檔。

圖片顯示左側為日落，右側擷取的調色盤。
圖 1：範例圖片和其擷取的色彩設定檔，其中包含調色盤的預設顏色上限 (16 種)。

使用色票建立色彩配置

Palette 類別也會為每個色彩設定檔產生 Palette.Swatch 物件。Palette.Swatch 物件包含該設定檔的關聯顏色，以及顏色在像素中的分布。

色票有其他方法可取得有關色彩設定檔的更多資訊，例如 HSL 值和像素填充。您可以使用色票，透過 getBodyTextColor() 和 getTitleTextColor() 方法建立更全面的色彩配置和應用程式主題。這些方法會傳回適合在色票顏色上使用的顏色。

Palette 中的每個 get<Profile>Swatch() 方法都會傳回與該特定設定檔相關聯的色塊，其中 <Profile> 會替換為六個色彩設定檔之一的名稱。雖然色盤的 get<Profile>Swatch() 方法不需要預設值參數，但如果圖片中沒有該特定設定檔，則會傳回 null。因此，請先確認色塊不是空值，再使用色塊。舉例來說，以下程式碼會從調色盤取得標題文字顏色 (當 Vibrant Swatch 不是空值時)：

Kotlin

val vibrant = myPalette.vibrantSwatch
// In Kotlin, check for null before accessing properties on the vibrant swatch.
val titleColor = vibrant?.titleTextColor

Java

Palette.Swatch vibrant = myPalette.getVibrantSwatch();
if(vibrant != null){
    int titleColor = vibrant.getTitleTextColor();
    // ...
}

如要存取調色盤中的所有顏色，getSwatches() 方法會傳回從圖片產生的所有色票清單，包括標準的六種色彩設定檔。

下列程式碼片段會使用上述程式碼片段的方法，以同步方式產生調色盤、取得其鮮豔的色塊，並變更工具列的顏色，以便與點陣圖相符。圖 2 顯示產生的圖片和工具列。

Kotlin

// Set the background and text colors of a toolbar given a bitmap image to
// match.
fun setToolbarColor(bitmap: Bitmap) {
    // Generate the palette and get the vibrant swatch.
    val vibrantSwatch = createPaletteSync(bitmap).vibrantSwatch

    // Set the toolbar background and text colors.
    // Fall back to default colors if the vibrant swatch isn't available.
    with(findViewById<Toolbar>(R.id.toolbar)) {
        setBackgroundColor(vibrantSwatch?.rgb ?:
                ContextCompat.getColor(context, R.color.default_title_background))
        setTitleTextColor(vibrantSwatch?.titleTextColor ?:
                ContextCompat.getColor(context, R.color.default_title_color))
    }
}

Java

// Set the background and text colors of a toolbar given a bitmap image to
// match.
public void setToolbarColor(Bitmap bitmap) {
    // Generate the palette and get the vibrant swatch.
    // See the createPaletteSync() method from the preceding code snippet.
    Palette p = createPaletteSync(bitmap);
    Palette.Swatch vibrantSwatch = p.getVibrantSwatch();

    Toolbar toolbar = (Toolbar) findViewById(R.id.toolbar);

    // Load default colors.
    int backgroundColor = ContextCompat.getColor(getContext(),
        R.color.default_title_background);
    int textColor = ContextCompat.getColor(getContext(),
        R.color.default_title_color);

    // Check that the Vibrant swatch is available.
    if(vibrantSwatch != null){
        backgroundColor = vibrantSwatch.getRgb();
        textColor = vibrantSwatch.getTitleTextColor();
    }

    // Set the toolbar background and text colors.
    toolbar.setBackgroundColor(backgroundColor);
        toolbar.setTitleTextColor(textColor);
}
顯示日落景色的圖片，以及內含 TitleTextColor 的工具列
圖 2 範例圖片：色彩鮮豔的工具列和對應的標題文字顏色。