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

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

หมายเหตุ: PullToRefreshBox() อยู่ในช่วงทดลอง

แพลตฟอร์ม API

ใช้คอมโพสิชัน 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

หมายเหตุ: ในตัวอย่างพื้นฐาน ระบบไม่ได้ส่ง state ไปยัง PullToRefreshBox เนื่องจากใช้ค่าพารามิเตอร์เริ่มต้น อย่างไรก็ตาม ในตัวอย่างนี้ คุณต้องกำหนดสถานะและส่งสถานะนั้นไปยังทั้งกล่องและตัวบ่งชี้เพื่อประสานการทำงาน

ผลลัพธ์

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

รูปที่ 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 ในคอมโพสิเบิลนี้ ตัวปรับเปลี่ยน pullToRefreshIndicator จะจัดการการจัดตำแหน่งและทริกเกอร์การรีเฟรช
• เช่นเดียวกับข้อมูลโค้ดก่อนหน้า ระบบได้ดึงข้อมูลอินสแตนซ์ PullToRefreshState ออกมาแล้ว จึงสามารถส่งอินสแตนซ์เดียวกันไปยังทั้ง PullToRefreshBox และ pullToRefreshModifier ได้
• ระบบจะใช้สีคอนเทนเนอร์และเกณฑ์ตำแหน่งจากคลาส PullToRefreshDefaults วิธีนี้ช่วยให้คุณนําลักษณะการทํางานเริ่มต้นและการจัดสไตล์จากคลัง Material มาใช้ซ้ำได้ พร้อมกับปรับแต่งเฉพาะองค์ประกอบที่สนใจ
• MyCustomIndicator ใช้ Crossfade เพื่อเปลี่ยนระหว่างไอคอนเมฆกับ CircularProgressIndicator ไอคอนเมฆจะขยายขึ้นเมื่อผู้ใช้ดึง และเปลี่ยนเป็น CircularProgressIndicator เมื่อการรีเฟรชเริ่มขึ้น
  • targetState ใช้ isRefreshing เพื่อกำหนดสถานะที่จะแสดง (ไอคอนเมฆหรือสัญญาณบอกสถานะความคืบหน้าแบบวงกลม)
  • animationSpec กำหนดภาพเคลื่อนไหว tween สำหรับการเปลี่ยน โดยมีระยะเวลาที่ระบุไว้คือ CROSSFADE_DURATION_MILLIS
  • state.distanceFraction แสดงถึงระยะที่ผู้ใช้เลื่อนลง โดยอยู่ในช่วง 0f (ไม่เลื่อน) ถึง 1f (เลื่อนลงจนสุด)
  • ตัวหลีก graphicsLayer จะแก้ไขขนาดและความโปร่งใส

ผลลัพธ์

วิดีโอนี้แสดงตัวบ่งชี้ที่กําหนดเองจากโค้ดก่อนหน้า

รูปที่ 3 การติดตั้งใช้งานการปัดเพื่อรีเฟรชพร้อมตัวบ่งชี้ที่กำหนดเอง

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

• PullToRefreshState