צריך למשוך כדי לרענן

הרכיב 'משיכה לרענון' מאפשר למשתמשים לגרור למטה בתחילת התוכן של האפליקציה כדי לרענן את הנתונים.

ממשק API

כדי להטמיע את התכונה 'משיכה לרענון', שמשמשת כקונטיינר לתוכן שאפשר לגלול בו, משתמשים ברכיב ה-composable PullToRefreshBox. הפרמטרים המרכזיים הבאים קובעים את התנהגות הרענון ואת המראה שלו:

  • isRefreshing: ערך בוליאני שמציין אם פעולת הרענון מתבצעת כרגע.
  • onRefresh: פונקציית lambda שפועלת כשהמשתמש מפעיל רענון.
  • indicator: התאמה אישית של האינדיקטור שמוצג במשיכה לרענון.

דוגמה בסיסית

קטע הקוד הזה מדגים שימוש בסיסי ב-PullToRefreshBox:

@Composable
fun PullToRefreshBasicSample(
    items: List<String>,
    isRefreshing: Boolean,
    onRefresh: () -> Unit,
    modifier: Modifier = Modifier
) {
    PullToRefreshBox(
        isRefreshing = isRefreshing,
        onRefresh = onRefresh,
        modifier = modifier
    ) {
        LazyColumn(Modifier.fillMaxSize()) {
            items(items) {
                ListItem({ Text(text = it) })
            }
        }
    }
}
PullToRefreshBox.kt

נקודות עיקריות לגבי הקוד

  • PullToRefreshBox עוטף LazyColumn, שמציג רשימה של מחרוזות.
  • PullToRefreshBox מחייב את הפרמטרים isRefreshing ו-onRefresh.
  • התוכן בתוך הבלוק PullToRefreshBox מייצג את התוכן שאפשר לגלול בו.

התוצאה

בסרטון הזה מוצגת ההטמעה הבסיסית של 'משיכה לרענון' מהקוד הקודם:

איור 1. הטמעה בסיסית של 'משיכה לרענון' ברשימת פריטים.

דוגמה מתקדמת: התאמה אישית של צבע האינדיקטור

@Composable
fun PullToRefreshCustomStyleSample(
    items: List<String>,
    isRefreshing: Boolean,
    onRefresh: () -> Unit,
    modifier: Modifier = Modifier
) {
    val state = rememberPullToRefreshState()

    PullToRefreshBox(
        isRefreshing = isRefreshing,
        onRefresh = onRefresh,
        modifier = modifier,
        state = state,
        indicator = {
            Indicator(
                modifier = Modifier.align(Alignment.TopCenter),
                isRefreshing = isRefreshing,
                containerColor = MaterialTheme.colorScheme.primaryContainer,
                color = MaterialTheme.colorScheme.onPrimaryContainer,
                state = state
            )
        },
    ) {
        LazyColumn(Modifier.fillMaxSize()) {
            items(items) {
                ListItem({ Text(text = it) })
            }
        }
    }
}
PullToRefreshBox.kt

נקודות עיקריות לגבי הקוד

  • צבע האינדיקטור מותאם אישית באמצעות המאפיינים containerColor ו-color בפרמטר indicator.
  • rememberPullToRefreshState() מנהל את המצב של פעולת הרענון. משתמשים במצב הזה בשילוב עם הפרמטר indicator.

התוצאה

בסרטון הזה מוצגת הטמעה של 'משיכה לרענון' עם אינדיקטור צבעוני:

איור 2. הטמעה של 'משיכה לרענון' עם סגנון מותאם אישית.

דוגמה מתקדמת: יצירת אינדיקטור מותאם אישית לחלוטין

אתם יכולים ליצור אינדיקטורים מורכבים בהתאמה אישית על ידי שימוש ברכיבים קייימים ליצירת רכיבים מותאמים אישית ובאנימציות.קטע הקוד הזה מראה איך ליצור אינדיקטור בהתאמה אישית מלאה בהטמעה של 'משיכה לרענון':

@Composable
fun PullToRefreshCustomIndicatorSample(
    items: List<String>,
    isRefreshing: Boolean,
    onRefresh: () -> Unit,
    modifier: Modifier = Modifier
) {
    val state = rememberPullToRefreshState()

    PullToRefreshBox(
        isRefreshing = isRefreshing,
        onRefresh = onRefresh,
        modifier = modifier,
        state = state,
        indicator = {
            MyCustomIndicator(
                state = state,
                isRefreshing = isRefreshing,
                modifier = Modifier.align(Alignment.TopCenter)
            )
        }
    ) {
        LazyColumn(Modifier.fillMaxSize()) {
            items(items) {
                ListItem({ Text(text = it) })
            }
        }
    }
}

// ...
@Composable
fun MyCustomIndicator(
    state: PullToRefreshState,
    isRefreshing: Boolean,
    modifier: Modifier = Modifier,
) {
    Box(
        modifier = modifier.pullToRefreshIndicator(
            state = state,
            isRefreshing = isRefreshing,
            containerColor = PullToRefreshDefaults.containerColor,
            threshold = PositionalThreshold
        ),
        contentAlignment = Alignment.Center
    ) {
        Crossfade(
            targetState = isRefreshing,
            animationSpec = tween(durationMillis = CROSSFADE_DURATION_MILLIS),
            modifier = Modifier.align(Alignment.Center)
        ) { refreshing ->
            if (refreshing) {
                CircularProgressIndicator(Modifier.size(SPINNER_SIZE))
            } else {
                val distanceFraction = { state.distanceFraction.coerceIn(0f, 1f) }
                Icon(
                    imageVector = Icons.Filled.CloudDownload,
                    contentDescription = "Refresh",
                    modifier = Modifier
                        .size(18.dp)
                        .graphicsLayer {
                            val progress = distanceFraction()
                            this.alpha = progress
                            this.scaleX = progress
                            this.scaleY = progress
                        }
                )
            }
        }
    }
}
PullToRefreshBox.kt

נקודות עיקריות לגבי הקוד

  • בקטע הקוד הקודם נעשה שימוש ב-Indicator שסופק על ידי הספרייה. קטע הקוד הזה יוצר רכיב אינדיקטור מותאם אישית בשם MyCustomIndicator. ב-composable הזה, המשתנה המשנה pullToRefreshIndicator מטפל במיקום ובהפעלת הרענון.
  • כמו בקטע הקוד הקודם, המכונה PullToRefreshState הופקה, כך שאפשר להעביר את אותה מכונה גם ל-PullToRefreshBox וגם ל-pullToRefreshModifier.
  • הצבע של הקונטיינר וסף המיקום נלקחים מהקלאס PullToRefreshDefaults. כך תוכלו לעשות שימוש חוזר בהתנהגות ובסגנון ברירת המחדל של ספריית Material, ולהתאים אישית רק את הרכיבים שחשובים לכם.
  • MyCustomIndicator משתמש ב-Crossfade כדי לעבור בין סמל ענן לבין CircularProgressIndicator. סמל הענן מתרחב ככל שהמשתמש מושך, ועובר ל-CircularProgressIndicator כשפעולת הרענון מתחילה.
    • targetState משתמש ב-isRefreshing כדי לקבוע איזה מצב יוצג (סמל הענן או אינדיקטור ההתקדמות המעגלי).
    • animationSpec מגדיר אנימציה tween למעבר, עם משך זמן מסוים של CROSSFADE_DURATION_MILLIS.
    • הערך state.distanceFraction מייצג את המרחק שאליו המשתמש משך למטה, החל מ-0f (ללא משיכה) ועד 1f (משיכה מלאה).
    • המאפיין graphicsLayer משנה את קנה המידה והשקיפות.

התוצאה

בסרטון הזה מוצג האינדיקטור המותאם אישית מהקוד הקודם:

איור 3. הטמעה של 'משיכה לרענון' עם אינדיקטור מותאם אישית.

מקורות מידע נוספים