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

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

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

اصلاح‌کننده onVisibilityChanged مقدار بولی ارائه می‌دهد که نشان‌دهنده وضعیت رؤیت‌پذیری فعلی composable است. علاوه‌براین، پارامترهایی مثل minFractionVisible و 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,
    ) {
        // ...
    }
}

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

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

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

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

وقتی کسر قابل‌مشاهده بزرگ‌تر از minFractionVisible باشد، یا وقتی composable کاملاً قابل‌مشاهده باشد یا نمای دید را پر کند، callback مقدار true را دریافت می‌کند. درغیراین‌صورت، false دریافت می‌کند.

LazyColumn(
    modifier = modifier.fillMaxSize()
) {
    item {
        Box(
            modifier = Modifier
                // ...
                // Here `visible` is `true` when more than 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)
            )
        }
    }
}

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

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

پنهان کردن composable و حفظ فضای آن

برای پنهان کردن یک composable بدون تغییر چیدمان اطراف آن، از اصلاح‌کننده visible استفاده کنید. وقتی از false عبور می‌کنید، ترکیب‌پذیر همچنان اندازه‌گیری می‌شود اما قرار داده یا ترسیم نمی‌شود. برخلاف تنظیم alpha روی 0f، visible(false) عنصر را از درخت دسترس‌پذیری نیز برمی‌دارد و تعامل‌های لمسی را غیرفعال می‌کند درحالی‌که فضای چیدمان آن را حفظ می‌کند.

مثال زیر نماد علامت تأییدی را نشان می‌دهد که وقتی پنهان است، فضای خود را حفظ می‌کند، بنابراین نوشتار کنار آن حرکت نمی‌کند:

Row(modifier, verticalAlignment = Alignment.CenterVertically) {
    Icon(
        painter = painterResource(R.drawable.check),
        contentDescription = "Saved",
        modifier = Modifier
            // The icon keeps its space while it's hidden, so the text doesn't move.
            .visible(isSaved)
    )
    Text("Draft", Modifier.padding(start = 8.dp))
}

وقتی چیدمان اطراف composable نباید با ظاهر شدن و ناپدید شدن composable حرکت کند، از visible استفاده کنید. برای برداشتن ترکیب‌پذیر و فضای آن، آن را فراخوانی نکنید، یا از AnimatedVisibility برای پویانمایی کردن آن به داخل و خارج استفاده کنید.

قبلی
اندازه‌گیری‌های ذاتی