ردیابی قابلیت مشاهده در نوشتن

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

• onVisibilityChanged - این اصلاح‌کننده وقتی قابلیت مشاهده یک ترکیب تغییر می‌کند به شما اطلاع می‌دهد. این برای راه‌اندازی یک عمل یا اثر جانبی هر بار که ترکیب قابل مشاهده می‌شود، ایده‌آل است.
• onLayoutRectChanged - این اصلاح‌کننده اطلاعاتی در مورد مرزهای یک composable نسبت به ریشه، پنجره و صفحه نمایش ارائه می‌دهد. این اصلاح‌کننده کنترل سطح پایین ارائه می‌دهد و API پایه برای onVisibilityChanged است. این اصلاح‌کننده مشابه onGloballyPositioned است، اما عملکرد بهتر و انعطاف‌پذیری بیشتری را ارائه می‌دهد.

شما می‌توانید از این APIها با هر ترکیب‌پذیری به عنوان بخشی از زنجیره اصلاح‌کننده استفاده کنید.

تغییرات دید را با 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 اهمیت دارد. مثال قبلی یک تابع composable را نشان می‌دهد که متن را با padding رندر می‌کند. برای اطمینان از اینکه اصلاح‌کننده بر کل composable به همراه padding تأثیر می‌گذارد، اصلاح‌کننده‌ی onVisibilityChanged را قبل از اصلاح‌کننده‌ی padding اضافه کنید.

قبل از فعال کردن قابلیت مشاهده، محدودیت زمانی روی یک composable تعیین کنید.

در برخی شرایط، ممکن است بخواهید یک اقدام را فقط پس از اینکه یک آیتم برای مدت زمان مشخصی برای کاربر قابل مشاهده بوده است، فعال کنید. به عنوان مثال، می‌توانید اگر مدتی است که یک ویدیو برای کاربر قابل مشاهده است، آن را به صورت خودکار پخش کنید.

برای فعال کردن یک عمل پس از اینکه یک آیتم برای مدت زمان مشخصی قابل مشاهده بود، از پارامتر minDurationMs در اصلاحگر onVisibilityChanged استفاده کنید. این پارامتر حداقل مدت زمانی را که یک composable برای فعال شدن callback نیاز دارد تا به طور مداوم قابل مشاهده باشد، مشخص می‌کند. اگر composable قبل از رسیدن به مدت زمان مشخص شده، قابل مشاهده بودن خود را متوقف کند، تایمر ریست می‌شود. مقدار پیش‌فرض 0 میلی‌ثانیه است.

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

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

حداقل کسر قابل مشاهده را تنظیم کنید

تنظیم حداقل کسر قابل مشاهده برای فراخوانی برگشتی قابلیت مشاهده‌ی composable هنگام کار با محتوای قابل پیمایش (برای مثال، LazyColumn ) برای بهینه‌سازی واکشی داده‌ها برای مواردی که از اندازه صفحه نمایش بزرگتر هستند، مفید است.

در چنین مواردی، از پارامتر minFractionVisible در اصلاحگر onVisibilityChanged برای تعریف کسری که باید روی صفحه باشد تا composable به عنوان visible علامت گذاری شود، استفاده کنید. این پارامتر از مقادیر float از 0.0f تا 1.0f پشتیبانی می‌کند و به طور پیش‌فرض روی 1.0f تنظیم شده است. 1.0f به این معنی است که composable باید کاملاً روی صفحه قابل مشاهده باشد تا callback فعال شود.

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