اختيار الألوان باستخدام Palette API

يُعدّ التصميم المرئي الجيد ضروريًا لنجاح التطبيق، وتُعدّ أنظمة الألوان مكوّنًا أساسيًا في التصميم. مكتبة Palette هي مكتبة في Jetpack تستخرج الألوان البارزة من الصور لإنشاء تطبيقات جذابة بصريًا.

يمكنك استخدام مكتبة Palette لتصميم مظاهر التنسيق وتطبيق ألوان مخصّصة على العناصر المرئية في تطبيقك. على سبيل المثال، يمكنك استخدام لوحة ألوان لإنشاء بطاقة عنوان منسّقة الألوان لأغنية استنادًا إلى غلاف ألبومها أو لضبط لون شريط أدوات التطبيق عند تغيير صورة الخلفية. يتيح لك الكائن Palette الوصول إلى الألوان في صورة Bitmap مع توفير ستة ملفات شخصية رئيسية للألوان من الصورة النقطية لإعلامك باختيارات التصميم.

إعداد المكتبة

لاستخدام مكتبة Palette، أضِف ما يلي إلى build.gradle:

android {
    compileSdkVersion(36)
    ...
}

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

android {
    compileSdkVersion 36
    ...
}

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

إنشاء لوحة ألوان

يتيح لك عنصر Palette الوصول إلى الألوان الأساسية في صورة بالإضافة إلى الألوان المقابلة للنص المركّب. استخدِم لوحات الألوان لتصميم نمط تطبيقك وتغيير نظام الألوان في تطبيقك ديناميكيًا استنادًا إلى صورة مصدر معيّنة.

لإنشاء لوحة ألوان، عليك أولاً إنشاء مثيل Palette.Builder من Bitmap. يمكنك بعد ذلك استخدام Palette.Builder لتخصيص لوحة الألوان قبل إنشائها. يصف هذا القسم إنشاء لوحة الألوان وتخصيصها من صورة نقطية.

إنشاء مثيل Palette

أنشئ مثيلاً من Palette باستخدام الإجراء from(Bitmap bitmap) لإنشاء Palette.Builder أولاً من Bitmap.

يمكن لأداة الإنشاء إنشاء لوحة الألوان بشكل متزامن أو غير متزامن. استخدِم إنشاء لوحة الألوان المتزامنة إذا كنت تريد إنشاء لوحة الألوان في سلسلة المحادثات نفسها التي يتم استدعاء الطريقة فيها. إذا كنت تنشئ لوحة الألوان بشكل غير متزامن، على سلسلة محادثات مختلفة، استخدِم طريقة onGenerated() للوصول إلى لوحة الألوان فور إنشائها.

يوفر مقتطف الرمز التالي أمثلة على طرق إنشاء كلا النوعين من لوحات الألوان:

// 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.
    }
}

// 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 مؤقتًا لمنع بطء أداء واجهة المستخدم. لا تنشئ لوحات الألوان في سلسلة التعليمات الرئيسية.

تخصيص لوحة الألوان

تتيح لك أداة Palette.Builder تخصيص لوحة الألوان من خلال اختيار عدد الألوان في اللوحة الناتجة، والمنطقة التي تستخدمها الأداة في الصورة لإنشاء اللوحة، والألوان التي يتم تضمينها في اللوحة. على سبيل المثال، يمكنك استبعاد اللون الأسود أو التأكّد من أنّ الأداة تستخدم النصف العلوي فقط من الصورة لإنشاء لوحة الألوان.

يمكنك ضبط حجم لوحة الألوان وألوانها بدقة باستخدام الطرق التالية من الفئة Palette.Builder:

addFilter()

تضيف هذه الطريقة فلترًا يشير إلى الألوان المسموح بها في لوحة الألوان الناتجة. مرِّر Palette.Filter الخاص بك وعدِّل طريقة isAllowed() لتحديد الألوان التي تتم فلترتها من لوحة الألوان.

maximumColorCount()

تحدّد هذه الطريقة الحد الأقصى لعدد الألوان في لوحة الألوان. القيمة التلقائية هي 16، وتعتمد القيمة المثلى على الصورة المصدر. بالنسبة إلى المناظر الطبيعية، تتراوح القيم المثلى بين 8 و16، في حين أنّ الصور التي تحتوي على وجوه عادةً ما تكون قيمها بين 24 و32. يستغرق Palette.Builder وقتًا أطول لإنشاء لوحات ألوان تحتوي على المزيد من الألوان.

setRegion()

تشير هذه الطريقة إلى المنطقة التي تستخدمها أداة الإنشاء من الصورة النقطية عند إنشاء لوحة الألوان. يمكنك استخدام هذه الطريقة فقط عند إنشاء لوحة الألوان من صورة نقطية، ولا تؤثر في الصورة الأصلية.

addTarget()

تتيح لك هذه الطريقة مطابقة الألوان بنفسك من خلال إضافة Target ملف ألوان إلى أداة الإنشاء. إذا كان Target التلقائي غير كافٍ، يمكن للمطوّرين المتقدّمين إنشاء Target خاص بهم باستخدام Target.Builder.

استخراج ملفات تعريف الألوان

استنادًا إلى معايير التصميم المتعدد الأبعاد، تستخرج مكتبة Palette ملفات تعريف الألوان الشائعة الاستخدام من صورة معيّنة. يتم تحديد كل ملف شخصي من خلال Target، ويتم تسجيل الألوان المستخرَجة من صورة نقطية مقابل كل ملف شخصي استنادًا إلى التشبع والإضاءة والعدد (عدد وحدات البكسل في الصورة النقطية التي يمثّلها اللون). بالنسبة إلى كل ملف شخصي، يحدّد اللون الذي يحصل على أفضل نتيجة ملف اللون الشخصي للصورة المحدّدة.

بشكل تلقائي، يحتوي عنصر Palette على 16 لونًا أساسيًا من صورة معيّنة. عند إنشاء لوحة الألوان، يمكنك تخصيص عدد ألوانها باستخدام Palette.Builder. يؤدي استخراج المزيد من الألوان إلى توفير المزيد من التطابقات المحتملة لكل ملف شخصي للألوان، ولكنه يؤدي أيضًا إلى استغراق Palette.Builder وقتًا أطول عند إنشاء لوحة الألوان.

تحاول مكتبة Palette استخراج ملفات تعريف الألوان الستة التالية:

• نابض بالحياة فاتح
• نابض
• نابض بالحياة داكن
• ألوان فاتحة هادئة
• كتم الصوت
• لون داكن خافت

تعرض كل طريقة من طرق get<Profile>Color() في Palette اللون في لوحة الألوان المرتبطة بهذا الملف الشخصي المحدّد، حيث يتم استبدال <Profile> باسم أحد ملفات الألوان الستة. على سبيل المثال، الطريقة التي يتم من خلالها الحصول على الملف الشخصي للون "الداكن الزاهي" هي getDarkVibrantColor(). بما أنّ بعض الصور لا تحتوي على جميع ملفات الألوان، يجب توفير لون تلقائي لعرضه.

يعرض الشكل 1 صورة وملفات الألوان المقابلة لها من طرق get<Profile>Color().

استخدام عينات الألوان لإنشاء مخططات الألوان

تنشئ فئة Palette أيضًا كائنات Palette.Swatch لكل ملف شخصي للألوان. تحتوي كائنات Palette.Swatch على اللون المرتبط بهذا الملف الشخصي بالإضافة إلى عدد وحدات البكسل التي تشغل هذا اللون.

تحتوي العينات على طرق إضافية للوصول إلى مزيد من المعلومات حول ملف تعريف اللون، مثل قيم HSL وعدد وحدات البكسل. يمكنك استخدام عيّنات الألوان للمساعدة في إنشاء أنظمة ألوان ومظاهر تطبيقات أكثر شمولاً باستخدام الطريقتَين getBodyTextColor() وgetTitleTextColor(). تعرض هذه الطرق ألوانًا مناسبة للاستخدام فوق لون العيّنة.

تُرجع كل طريقة من طرق get<Profile>Swatch() من Palette العينة المرتبطة بهذا الملف الشخصي المحدد، حيث يتم استبدال <Profile> باسم أحد ملفات تعريف الألوان الستة. على الرغم من أنّ طرق get<Profile>Swatch() في لوحة الألوان لا تتطلّب مَعلمات القيمة التلقائية، فإنّها تعرض null إذا لم يكن هذا الملف الشخصي المحدّد متوفّرًا في الصورة. لذلك، تحقق من أن العينة ليست فارغة قبل استخدامها. على سبيل المثال، يحصل الرمز التالي على لون نص العنوان من لوحة ألوان إذا لم يكن نموذج الألوان "نابض بالحياة" فارغًا:

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

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

للوصول إلى جميع الألوان في لوحة الألوان، تعرض الطريقة getSwatches() قائمة بجميع العينات التي تم إنشاؤها من صورة، بما في ذلك الملفات الشخصية الستة العادية للألوان.

يستخدم مقتطف الرمز التالي الطرق من مقتطفات الرمز السابقة لإنشاء لوحة ألوان بشكل متزامن والحصول على عيّنة ألوان نابضة بالحياة وتغيير ألوان شريط الأدوات لتتطابق مع صورة الصورة النقطية. يعرض الشكل 2 الصورة الناتجة وشريط الأدوات.

// 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))
    }
}

// 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);
}