تتميز تطبيقات الكاميرا الحديثة بميزات قوية ومتداخلة. يتوقّع المستخدمون تسجيل فيديو بنطاق عالي ديناميكية مذهل، والتقاط حركة سلسة بمعدّل 60 لقطة في الثانية، والحصول على لقطات سلسة جدًا باستخدام ميزة "تثبيت المعاينة"، وغالبًا ما يكون ذلك في الوقت نفسه.

بصفتنا مطوّرين، نعلم أنّ الواقع أكثر تعقيدًا. كيف يمكنك ضمان أنّ جهازًا معيّنًا يتيح فعلاً استخدام مجموعة معيّنة من الميزات؟ حتى الآن، كان تفعيل ميزات متعددة غالبًا ما يكون بمثابة مقامرة. يمكنك التحقّق من إتاحة كل ميزة على حدة، ولكن قد يؤدي الجمع بينها إلى سلوك غير محدّد أو، ما هو أسوأ، إلى فشل جلسة الكاميرا. ويجبر هذا الغموض المطوّرين على توخي الحذر، ما يمنع المستخدمين على الأجهزة المتوافقة من الوصول إلى أفضل تجربة ممكنة.

على سبيل المثال، لا تتيح سوى عدد قليل جدًا من الأجهزة المتميزة تسجيل فيديو بنطاق عالي الديناميكية وبمعدّل 60 لقطة في الثانية بشكل موثوق في الوقت نفسه. وبالتالي، تتجنّب معظم التطبيقات تفعيل كلتا الميزتَين في الوقت نفسه لمنع تجربة المستخدم السيئة على غالبية الهواتف.

لمعالجة هذه المشكلة، نحن بصدد طرح مجموعة الميزات في CameraX - وهي واجهة برمجة تطبيقات جديدة مصمّمة لإزالة هذا التخمين. يمكنك الآن الاستعلام عما إذا كانت مجموعة معيّنة من الميزات متاحة قبل ضبط الكاميرا، أو ما عليك سوى إخبار CameraX بأولوياتك والسماح لها بتفعيل أفضل مجموعة متاحة لك.

لمحة عن CameraX

قبل أن نتعمّق في واجهة برمجة تطبيقات "مجموعة الميزات" الجديدة، لنلخّص بسرعة ما هو CameraX. إنّ CameraX هي مكتبة دعم Jetpack، تم تصميمها لمساعدتك في تسهيل تطوير تطبيقات الكاميرا. وهي توفّر واجهة برمجة تطبيقات متّسقة وسهلة الاستخدام تعمل على معظم أجهزة Android، مع التوافق مع الإصدارات السابقة حتى Android 6.0 (المستوى 23 من واجهة برمجة التطبيقات). إذا كنت تستخدم CameraX لأول مرة، ننصحك بالاطّلاع على المستندات الرسمية وتجربة الدرس البرمجي للبدء.

ما يمكنك إنشاؤه باستخدام واجهة برمجة تطبيقات "مجموعة الميزات"

لم يعُد عليك المقامرة بمجموعات الميزات ويمكنك بثقة تقديم أفضل تجارب الكاميرا الممكنة، مثل تسجيل فيديو بنطاق عالي ديناميكية وبمعدّل 60 لقطة في الثانية في الوقت نفسه على أجهزة متوافقة (مثل Pixel 10 Pro)، مع تجنُّب الأخطاء بشكل سلس على الأجهزة التي لا يمكنها إتاحة هذه المجموعة.

هاتف Pixel 10 Pro يتيح كلاً من النطاق العالي الديناميكية و60 لقطة في الثانية في الوقت نفسه

على جهاز قديم لا يمكنه تشغيل النطاق العالي الديناميكية و60 لقطة في الثانية في الوقت نفسه، يتم تفعيل النطاق العالي الديناميكية فقط بينما يتم إيقاف خيار 60 لقطة في الثانية.

باستخدام واجهة برمجة تطبيقات "مجموعة الميزات"، يمكنك إجراء ما يلي:

• إنشاء واجهات مستخدم ديناميكية وأكثر ذكاءً: يمكنك تفعيل الإعدادات أو إيقافها بذكاء في واجهة المستخدم استنادًا إلى إمكانية استخدام الجهاز في الوقت الفعلي. على سبيل المثال، إذا فعّل المستخدم النطاق العالي الديناميكية، يمكنك على الفور تعتيم خيار 60 لقطة في الثانية وإيقافه إذا لم تكن المجموعة متاحة على هذا الجهاز. 

• تقديم وضع "عالي الجودة" موثوق به: يمكنك ضبط الكاميرا باستخدام قائمة مرتبة حسب الأولوية للميزات المطلوبة. تعثر CameraX تلقائيًا على أفضل مجموعة متاحة لأي جهاز وتفعّلها، ما يضمن الحصول على نتيجة رائعة بدون منطق معقّد خاص بالجهاز.
• منع حالات فشل جلسة الكاميرا: من خلال التحقّق من إمكانية استخدام الميزات مسبقًا، يمكنك منع الكاميرا من محاولة ضبط مجموعة غير متاحة، ما يزيل مصدرًا شائعًا للأعطال ويقدّم تجربة سلسة للمستخدم.

طريقة العمل: المكوّنات الأساسية

تتمحور واجهة برمجة التطبيقات الجديدة حول إضافات رئيسية إلى SessionConfig و CameraInfo.

1. GroupableFeature: تقدّم واجهة برمجة التطبيقات هذه مجموعة من الميزات القابلة للتجميع المحدّدة مسبقًا، مثل HDR_HLG10 وFPS_60 وPREVIEW_STABILIZATION وIMAGE_ULTRA_HDR. بسبب القيود الحسابية، لا يمكن تجميع سوى مجموعة معيّنة من الميزات بدرجة الموثوقية العالية التي توفّرها واجهة برمجة التطبيقات هذه. ونحن نعمل بنشاط على توسيع هذه القائمة وسنقدّم إمكانية استخدام المزيد من الميزات في الإصدارات المستقبلية.
   
2. مَعلمات SessionConfig الجديدة: تقبل هذه الفئة، المستخدَمة لبدء جلسة الكاميرا، الآن مَعلمتَين جديدتَين:
   • requiredFeatureGroup: استخدِم هذه المَعلمة للميزات التي يجب أن تكون متاحة لنجاح عملية الضبط، وهي مثالية للميزات التي يفعّلها المستخدم صراحةً، مثل تبديل مفتاح "النطاق العالي الديناميكية". لضمان تجربة حتمية ومتّسقة، سيؤدي طلب bindToLifecycle إلى طرح IllegalArgumentException إذا لم تكن المجموعة المطلوبة غير متاحة، بدلاً من تجاهل طلب الميزة بدون إشعار. يجب استخدام واجهة برمجة التطبيقات CameraInfo#isFeatureGroupSupported (التفاصيل أدناه) للاستعلام عن هذه النتيجة مسبقًا.
   • preferredFeatureGroup: استخدِم هذه المَعلمة للميزات المرغوبة ولكنها اختيارية، على سبيل المثال عندما تريد تنفيذ وضع تلقائي "عالي الجودة". يمكنك تقديم قائمة بالميزات المطلوبة مرتّبة حسب أولوياتك، وتفعّل CameraX تلقائيًا المجموعة ذات الأولوية القصوى التي يتيحها الجهاز.
3. **CameraInfo#isFeatureGroupSupported()**: هذه هي طريقة الاستعلام الأساسية للتحقّق صراحةً مما إذا كانت مجموعة ميزات متاحة، وهي مناسبة تمامًا لتوفير خيارات الميزات المتاحة فقط للمستخدمين في واجهة مستخدم تطبيقك. يمكنك تمرير SessionConfig إليها، وستعرض قيمة منطقية تشير إلى ما إذا كانت المجموعة متاحة. إذا كنت تنوي ربط SessionConfig بميزات مطلوبة، عليك استخدام واجهة برمجة التطبيقات هذه أولاً للتأكّد من أنّها متاحة. 

طريقة الاستخدام

لنلقِ نظرة على كيفية استخدام هذه المكوّنات لإنشاء تجربة كاميرا أفضل.

السيناريو 1: وضع "عالي الجودة" بأفضل ما يمكن

إذا كنت تريد تفعيل أفضل الميزات الممكنة تلقائيًا، يمكنك تقديم قائمة مرتبة حسب الأولوية إلى preferredFeatureGroup. في هذا المثال، نطلب من CameraX منح الأولوية للنطاق العالي الديناميكية، ثم 60 لقطة في الثانية، وأخيرًا ميزة "تثبيت المعاينة". تتعامل CameraX مع تعقيد التحقّق من جميع المجموعات الممكنة واختيار أفضل مجموعة يتيحها الجهاز.

على سبيل المثال، إذا كان بإمكان الجهاز التعامل مع النطاق العالي الديناميكية و60 لقطة في الثانية معًا ولكن ليس مع ميزة "تثبيت المعاينة"، ستفعّل CameraX الميزتَين الأوليَين وتتجاهل الثالثة. بهذه الطريقة، يمكنك الحصول على أفضل تجربة ممكنة بدون كتابة عمليات تحقّق معقدة خاصة بالجهاز.

cameraProvider.bindToLifecycle(

    lifecycleOwner,

    cameraSelector,

    SessionConfig(

        useCases = listOf(preview, videoCapture),

        // The order of features in this list determines their priority. 

        // CameraX will enable the best-supported combination based on these

        // priorities: HDR_HLG10 > FPS_60 > Preview Stabilization.  

        preferredFeatureGroup =

           listOf(HDR_HLG10, FPS_60, PREVIEW_STABILIZATION),

    ).apply {

        // (Optional) Get a callback with the enabled features

        // to update your UI. 

        setFeatureSelectionListener { selectedFeatures ->

            updateUiIndicators(selectedFeatures)

        }

    }

)

بالنسبة إلى مقتطف الرمز البرمجي هذا، ستحاول CameraX تفعيل مجموعات الميزات بترتيب الأولوية التالي، مع اختيار أول مجموعة يتيحها الجهاز بالكامل:

1. النطاق العالي الديناميكية + 60 لقطة في الثانية + ميزة "تثبيت المعاينة"
2. النطاق العالي الديناميكية + 60 لقطة في الثانية
3. النطاق العالي الديناميكية + ميزة "تثبيت المعاينة"
4. النطاق العالي الديناميكية
5. 60 لقطة في الثانية + ميزة "تثبيت المعاينة"
6. 60 لقطة في الثانية
7. ميزة "تثبيت المعاينة"
8. لا شيء من الميزات أعلاه

السيناريو 2: إنشاء واجهة مستخدم تفاعلية

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

/**

 * Returns a list of features that are NOT supported in combination

 * with the currently selected features.

 */

fun getUnsupportedFeatures(

    currentFeatures: Set<GroupableFeature>

): Set<GroupableFeature> {

    val unsupportedFeatures = mutableSetOf<GroupableFeature>()

    val appFeatureOptions = setOf(HDR_HLG10, FPS_60, PREVIEW_STABILIZATION)


    // Iterate over every available feature option in your app. 

    appFeatureOptions.forEach { featureOption ->

        // Skip features the user has already selected. 

        if (currentFeatures.contains(featureOption)) return@forEach


        // Check if adding this new feature is supported. 

        val isSupported = cameraInfo.isFeatureGroupSupported(

            SessionConfig(

                useCases = useCases,

                // Check the new feature on top of existing ones.

                requiredFeatureGroup = currentFeatures + featureOption

            )

        )


        if (!isSupported) {

            unsupportedFeatures.add(featureOption)

        }

    }


    return unsupportedFeatures

}

يمكنك بعد ذلك ربط هذا المنطق بـ ViewModel أو وحدة التحكّم في واجهة المستخدم للاستجابة لبيانات أدخلها المستخدم وإعادة ربط الكاميرا بإعدادات مضمونة العمل.

// Invoked when user turns some feature on/off.

fun onFeatureChange(currentFeatures: Set<GroupableFeature>) {

    // Identify features that are unsupported with the current selection.

    val unsupportedFeatures = getUnsupportedFeatures(currentFeatures)



    // Update app UI so that users can't enable them.

    updateDisabledFeatures(unsupportedFeatures)



    // Since the UI now only allows selecting supported feature combinations, 

    // `currentFeatures` is always valid. This allows setting

    // `requiredFeatureGroup` directly, without needing to re-check for

    // support or set a feature selection listener.  

    cameraProvider.bindToLifecycle(

        lifecycleOwner,

        cameraSelector,

        SessionConfig(

            useCases = listOf(preview, videoCapture),

            requiredFeatureGroup = currentFeatures,

        )

    )

}

للاطّلاع على هذه المفاهيم في تطبيق عملي، يمكنك استكشاف تطبيق الاختبار الداخلي. يقدّم هذا التطبيق عملية تنفيذ كاملة لكل من السيناريوهات "بأفضل ما يمكن" و "واجهة مستخدم تفاعلية" التي تمت مناقشتها أعلاه.

يُرجى العِلم أنّ هذا تطبيق اختبار وليس نموذجًا رسميًا متوافقًا. على الرغم من أنّه مرجع رائع لواجهة برمجة تطبيقات "مجموعة الميزات"، لم يتم تحسينه للاستخدام في مرحلة الإنتاج.

البدء اليوم

تزيل واجهة برمجة تطبيقات "مجموعة الميزات" الغموض الذي يكتنف العمل باستخدام إمكانات الكاميرا المتقدّمة. من خلال توفير طريقة محدّدة للاستعلام عن إمكانية استخدام الميزات، يمكنك إنشاء تطبيقات كاميرا أكثر قوة وموثوقية بثقة.

تتوفّر واجهة برمجة التطبيقات كإصدار تجريبي في CameraX 1.5 ومن المقرر أن تصبح مستقرة تمامًا في الإصدار 1.6، مع توفّر المزيد من الدعم والتحسينات في الطريق.

لمزيد من المعلومات، يُرجى الاطّلاع على المستندات الرسمية. نحن متشوّقون لرؤية ما ستنشئه، ونتطلّع إلى ملاحظاتك. يُرجى مشاركة أفكارك والإبلاغ عن أي مشاكل من خلال القنوات التالية:

• مجموعة مناقشة المطوّرين في CameraX
• الإبلاغ عن خطأ هنا