ردیابی رؤیت‌پذیری در Compose

پیگیری زمان نمایان بودن عنصر میانای کاربر روی صفحه برای انواع مختلفی از موارد استفاده مفید است، مثل ثبت گزارش‌های تحلیلی، مدیریت وضعیت میانای کاربر، و بهینه‌سازی منابع با پخش یا توقف خودکار محتوای ویدیویی. چندین اصلاح‌گر برای پیگیری رؤیت‌پذیری عنصر میانای کاربر دارد، ازجمله:

• onVisibilityChanged - این اصلاح‌گر وقتی رؤیت‌پذیری یک عنصر ترکیبی تغییر می‌کند به شما اطلاع می‌دهد. این اصلاح‌گر برای راه‌اندازی کنش یا اثر جانبی هربار که عنصر ترکیبی نمایان می‌شود ایده‌آل است.
• onLayoutRectChanged - این اصلاح‌گر اطلاعاتی درباره محدوده‌های عنصر ترکیبی نسبت‌به ریشه، پنجره، و صفحه ارائه می‌دهد. این API کنترل سطح پایین ارائه می‌دهد و API پایه برای 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 استفاده کنید. این پارامتر حداقل مدت زمانی را که یک عنصر ترکیبی باید به‌طور پیوسته قابل‌مشاهده باشد تا پاسخ‌به‌تماس راه‌اندازی شود مشخص می‌کند. اگر عنصر ترکیبی قبل‌از اتمام مدت زمان نامرئی شود، زمان‌سنج بازنشانی می‌شود. مقدار پیش‌فرض ۰ میلی‌ثانیه است.

تکه کد زیر پس‌از اینکه عنصر ترکیبی به‌مدت ۳ ثانیه برای کاربر قابل‌مشاهده بود، پس‌زمینه را به بنفش تغییر می‌دهد:

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» را از شبکه پیش‌بار می‌کند قبل‌از اینکه عنصر ترکیبی کاملاً نمایان شود. در «شکل ۲»، روبات سوم بار نمی‌شود، زیرا عنصر ترکیبی کاملاً نمایان نیست. در «شکل ۳»، minFractionVisible تنظیم شده است و روبات سوم قبل‌از اینکه کاملاً در صفحه قابل‌مشاهده باشد بار می‌شود.