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

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

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

مانند هر اصلاح‌گر دیگری، ترتیب در اصلاح‌گر onVisibilityChanged اهمیت دارد. مثال قبلی تابع ترکیب‌پذیری را نشان می‌دهد که نوشتار را با حاشیه داخلی ارائه می‌کند. برای اطمینان از اینکه اصلاح‌کننده بر کل ترکیب‌پذیر همراه با حاشیه داخلی تأثیر می‌گذارد، اصلاح‌کننده onVisibilityChanged را قبل‌از اصلاح‌کننده padding اضافه کنید.

تنظیم محدودیت زمانی برای composable قبل‌از راه‌اندازی فراخوان رؤیت‌پذیری

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

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

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

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

شکل ۱. پس‌از اینکه ترکیب‌پذیر به‌مدت ۳ ثانیه به‌طور مداوم روی صفحه‌نمایش قرار گرفت، پس‌زمینه از صورتی به آلویی تغییر می‌کند.

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

تنظیم حداقل کسر قابل‌مشاهده برای callback رؤیت‌پذیری composable هنگام کار با محتوای پیمایشی (برای مثال، 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

شکل ۲. بدون تنظیم minFractionVisible.	شکل ۳. با minFractionVisible تنظیم‌شده به‌عنوان 0.2f.

مثالی که قبلاً استفاده شد، Androidify Bots را از شبکه پیش‌بارگیری می‌کند، قبل‌از اینکه ترکیب‌پذیر کاملاً نمایان شود. در شکل ۲، ربات سوم بار نمی‌شود، زیرا ترکیب‌پذیر کاملاً قابل‌مشاهده نیست. در شکل ۳، minFractionVisible تنظیم شده است و ربات سوم قبل‌از اینکه کاملاً در صفحه نمایان شود بار می‌شود.

توجه: ویدیوهای قبلی برای شفافیت بیشتر به‌طور عمدی آهسته شده‌اند.