تتبُّع مستوى العرض في Compose

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

• onVisibilityChanged: يرسل إليك هذا المعدِّل إشعارًا عند تغيير مستوى ظهور عنصر قابل للإنشاء. وهي مثالية لتنفيذ إجراء أو تأثير جانبي كلما أصبحت الدالة المركّبة مرئية.
• onLayoutRectChanged: يوفّر هذا المعدِّل معلومات عن حدود عنصر قابل للإنشاء بالنسبة إلى الجذر والنافذة والشاشة. توفّر هذه الواجهة إمكانية التحكّم على مستوى منخفض، وهي واجهة برمجة التطبيقات الأساسية في onVisibilityChanged. يشبه المعدِّل onGloballyPositioned، ولكنّه يوفّر أداءً أفضل ومرونة أكبر.

يمكنك استخدام واجهات برمجة التطبيقات هذه مع أي دالة مركّبة كجزء من سلسلة عناصر التعديل.

تتبُّع التغييرات في مستوى الظهور باستخدام onVisibilityChanged

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

لتلقّي إشعار عند تغيير مستوى عرض عنصر، استخدِم المعدِّل onVisibilityChanged، كما هو موضّح في المثال التالي:

Text(
    text = "Some text",
    modifier = Modifier
        .onVisibilityChanged { visible ->
            if (visible) {
                // Do something if visible
            } else {
                // Do something if not visible
            }
        }
        .padding(vertical = 8.dp)
)
VisibilitySnippets.kt

يوفّر المعدِّل onVisibilityChanged قيمة منطقية تعكس حالة إمكانية رؤية العنصر القابل للإنشاء الحالية. بالإضافة إلى ذلك، يوفّر هذا الحقل مَعلمات، مثل minFraction وminDurationMs، تتيح لك التحكّم بشكل أفضل في الوقت الذي يجب فيه تشغيل دالة معاودة الاتصال الخاصة بإذن الوصول.

كما هو الحال مع كل معدِّل آخر، يهمّ ترتيب التسلسل مع المعدِّل onVisibilityChanged. يعرض المثال السابق دالة قابلة للإنشاء تعرض نصًا مع مساحة متروكة. للتأكّد من أنّ المعدِّل يؤثّر في العنصر القابل للإنشاء بالكامل مع المساحة المتروكة، أضِف المعدِّل onVisibilityChanged قبل المعدِّل padding.

ضبط حد زمني على دالة مركّبة قبل تشغيل معاودة الاتصال الخاصة بنطاق ظهور العلامة التجارية

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

لتنفيذ إجراء بعد أن يصبح عنصر مرئيًا لمدة محدّدة، استخدِم المَعلمة minDurationMs في المعدِّل onVisibilityChanged. تحدّد هذه المَعلمة الحدّ الأدنى لمدة ظهور الدالة المركّبة بشكل مستمر ليتم تشغيل معاودة الاتصال. إذا توقّف العنصر القابل للإنشاء عن الظهور قبل انتهاء المدة، تتم إعادة ضبط الموقّت. القيمة التلقائية هي 0 مللي ثانية.

يغيّر المقتطف التالي لون الخلفية إلى اللون الأرجواني بعد أن تظهر الدالة المركّبة للمستخدم لمدة 3 ثوانٍ:

var background by remember { mutableStateOf(PalePink) }
Card(
    modifier = modifier
        // ...
        .onVisibilityChanged(minDurationMs = 3000) {
            if (it) {
                background = MutedPlum
            }
        }
) {

    Box(
        modifier = Modifier
            // ...
            .background(background),
        contentAlignment = Alignment.Center,
    ) {
        // ...
    }
}
VisibilitySnippets.kt

ضبط الحدّ الأدنى للكسر المرئي

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

في مثل هذه الحالات، استخدِم المَعلمة minFractionVisible في المعدِّل onVisibilityChanged لتحديد الجزء الذي يجب أن يظهر على الشاشة كي يتم وضع علامة على العنصر القابل للإنشاء على أنّه مرئي. يمكن إدخال قيم عائمة تتراوح بين 0.0f و1.0f، ويتم ضبطها على 1.0f تلقائيًا. يشير 1.0f إلى أنّ العنصر القابل للإنشاء يجب أن يكون مرئيًا بالكامل على الشاشة حتى يتم تشغيل معاودة الاتصال.

LazyColumn(
    modifier = modifier.fillMaxSize()
) {
    item {
        Box(
            modifier = Modifier
                // ...
                // Here the visible callback gets triggered when 20% of the composable is visible
                .onVisibilityChanged(
                    minFractionVisible = 0.2f,
                ) { visible ->
                    if (visible) {
                        // Call specific logic here
                        // viewModel.fetchDataFromNetwork()
                    }
                }
                .padding(vertical = 16.dp)
        ) {
            Text(
                text = "Sample Text",
                modifier = Modifier.padding(horizontal = 16.dp)
            )
        }
    }
}
VisibilitySnippets.kt

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