ดึงเพื่อรีเฟรช

คอมโพเนนต์การดึงเพื่อรีเฟรชช่วยให้ผู้ใช้ลากลงที่จุดเริ่มต้นของเนื้อหาแอปเพื่อรีเฟรชข้อมูลได้

พื้นผิว 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 จะรวม 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) })
            }
        }
    }
}

ประเด็นสำคัญเกี่ยวกับโค้ด

  • สีของตัวบ่งชี้ได้รับการปรับแต่งผ่านพร็อพเพอร์ตี้ containerColor และ color ในพารามิเตอร์ indicator
  • rememberPullToRefreshState() จัดการสถานะของการดำเนินการรีเฟรช คุณใช้สถานะนี้ร่วมกับพารามิเตอร์ indicator

ผลลัพธ์

วิดีโอนี้แสดงการใช้งานการดึงเพื่อรีเฟรชพร้อมตัวบ่งชี้สี

รูปที่ 2 การติดตั้งใช้งานการดึงเพื่อรีเฟรชที่มีสไตล์ที่กำหนดเอง

ตัวอย่างขั้นสูง: สร้างตัวบ่งชี้ที่ปรับแต่งอย่างเต็มที่

คุณสร้างตัวบ่งชี้ที่กำหนดเองที่ซับซ้อนได้โดยใช้ประโยชน์จาก Composable และ ภาพเคลื่อนไหวที่มีอยู่ ข้อมูลโค้ดนี้แสดงวิธีสร้างตัวบ่งชี้ที่กำหนดเองทั้งหมดในการติดตั้งใช้งานการดึงเพื่อรีเฟรช

@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
                        }
                )
            }
        }
    }
}

ประเด็นสำคัญเกี่ยวกับโค้ด

  • ข้อมูลโค้ดก่อนหน้านี้ใช้ 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 การติดตั้งใช้งานการดึงเพื่อรีเฟรชพร้อมตัวบ่งชี้ที่กำหนดเอง

แหล่งข้อมูลเพิ่มเติม