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

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

แพลตฟอร์ม 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.pullToRefresh(
            state = state,
            isRefreshing = isRefreshing,
            threshold = PositionalThreshold,
            onRefresh = {

            }
        ),
        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 ที่ไลบรารีมีให้ ข้อมูลโค้ดนี้จะสร้าง Composable ของสัญญาณบอกสถานะที่กำหนดเองชื่อ 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 การติดตั้งใช้งานการดึงเพื่อรีเฟรชพร้อมสัญญาณบอกสถานะที่กำหนดเอง

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