تتبُّع مستوى العرض في 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

الشكل 1. تتغيّر الخلفية من اللون الوردي إلى اللون البرقوقي بعد أن يظهر العنصر القابل للإنشاء على الشاشة لمدة 3 ثوانٍ متواصلة.

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

يُعدّ ضبط الحد الأدنى للكسر المرئي في دالة معاودة الاتصال الخاصة بظهور العنصر القابل للإنشاء أمرًا مفيدًا عند التعامل مع المحتوى القابل للتمرير (على سبيل المثال، 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

الشكل 2. بدون ضبط minFractionVisible	الشكل 3. مع ضبط minFractionVisible على 0.2f

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

ملاحظة: تم إبطاء سرعة الفيديوهات السابقة عمدًا لتوضيح المحتوى.