สร้างเลย์เอาต์รายละเอียดรายการ

รายละเอียดรายการเป็นรูปแบบ UI ที่ประกอบด้วยเลย์เอาต์แบบ 2 แผง โดยที่แผงหนึ่งแสดงรายการรายการต่างๆ และอีกแผงแสดงรายละเอียดของรายการที่เลือกจากรายการ

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

ใช้รูปแบบ UI ด้วย ListDetailPaneScaffold

ListDetailPaneScaffold เป็นส่วนประกอบที่ช่วยให้การติดตั้งใช้งานรูปแบบรายการแบบละเอียดในแอปของคุณง่ายขึ้น โครงสร้างพื้นฐานรายการแบบละเอียดอาจมีแผงได้สูงสุด 3 แผง ได้แก่ แผงรายการ แผงรายละเอียด และแผงเพิ่มเติมที่ไม่บังคับ Scaffold จะจัดการการคำนวณพื้นที่หน้าจอ เมื่อหน้าจอมีขนาดใหญ่เพียงพอ แผงรายละเอียดจะแสดงควบคู่ไปกับแผงรายการ ในหน้าจอขนาดเล็ก โครงสร้างพื้นฐานจะเปลี่ยนเป็นการแสดงรายการหรือแผงรายละเอียดแบบเต็มหน้าจอโดยอัตโนมัติ

รูปที่ 1 เมื่อมีขนาดหน้าจอเพียงพอ แผงรายละเอียดจะแสดงควบคู่ไปกับแผงรายการ

รูปที่ 2 เมื่อขนาดหน้าจอมีขีดจำกัด แผงรายละเอียด (เนื่องจากมีการเลือกรายการแล้ว) จะกินพื้นที่ทั้งหน้าจอ

ประกาศทรัพยากร Dependency

ListDetailPaneScaffold เป็นส่วนหนึ่งของไลบรารีเลย์เอาต์แบบปรับเปลี่ยนได้ของ Material 3

เพิ่ม 3 รายการต่อไปนี้ซึ่งเป็น Dependency ที่เกี่ยวข้องลงในไฟล์ build.gradle ของแอปหรือโมดูล

Kotlin

implementation("androidx.compose.material3.adaptive:adaptive")
implementation("androidx.compose.material3.adaptive:adaptive-layout")
implementation("androidx.compose.material3.adaptive:adaptive-navigation")

Groovy

implementation 'androidx.compose.material3.adaptive:adaptive'
implementation 'androidx.compose.material3.adaptive:adaptive-layout'
implementation 'androidx.compose.material3.adaptive:adaptive-navigation'

• ปรับเปลี่ยนได้ — องค์ประกอบพื้นฐานระดับล่าง เช่น HingeInfo และ Posture
• adaptive-layout — เลย์เอาต์แบบปรับอัตโนมัติ เช่น ListDetailPaneScaffold และ SupportingPaneScaffold
• adaptive-navigation — Composables สําหรับไปยังส่วนต่างๆ ภายในและระหว่างแผง

การใช้งานพื้นฐาน

ติดตั้งใช้งาน ListDetailPaneScaffold ดังนี้

1. ใช้คลาสที่แสดงถึงเนื้อหาที่จะเลือก คลาสนี้ควรเป็น Parcelable เพื่อรองรับการบันทึกและการกู้คืนรายการในลิสต์ที่เลือก ใช้ปลั๊กอิน kotlin-parcelize เพื่อสร้างโค้ดให้คุณ

   @Parcelize
   class MyItem(val id: Int) : Parcelable
   SampleListDetailPaneScaffold.kt

2. สร้าง ThreePaneScaffoldNavigator ด้วย rememberListDetailPaneScaffoldNavigator แล้วเพิ่ม BackHandler เครื่องมือนำทางนี้ใช้เพื่อไปยังส่วนต่างๆ ระหว่างรายการ รายละเอียด และแผงเพิ่มเติม การประกาศประเภททั่วไปจะทำให้เครื่องมือนำทางติดตามสถานะของสแคฟเฟิลด์ด้วย (นั่นคือ MyItem ที่แสดงอยู่) เนื่องจากประเภทนี้แบ่งออกเป็นส่วนๆ ได้ โปรแกรมนำทางจึงบันทึกและกู้คืนสถานะเพื่อจัดการการเปลี่ยนแปลงการกำหนดค่าโดยอัตโนมัติได้ BackHandler รองรับการนำทางกลับโดยใช้ท่าทางสัมผัสหรือการกดปุ่มย้อนกลับของระบบ ลักษณะการทํางานของปุ่มย้อนกลับสําหรับListDetailPaneScaffoldจะขึ้นอยู่กับขนาดหน้าต่างและค่าสแคฟเฟิลดปัจจุบัน หาก ListDetailPaneScaffold รองรับการย้อนกลับด้วยสถานะปัจจุบัน canNavigateBack() จะเป็น true ซึ่งจะเปิดใช้ BackHandler

   val navigator = rememberListDetailPaneScaffoldNavigator<MyItem>()
   
   BackHandler(navigator.canNavigateBack()) {
       navigator.navigateBack()
   }
   SampleListDetailPaneScaffold.kt

3. ส่ง scaffoldState จาก navigator ไปยังคอมโพสิเบิล ListDetailPaneScaffold

   ListDetailPaneScaffold(
       directive = navigator.scaffoldDirective,
       value = navigator.scaffoldValue,
       // ...
   )
   SampleListDetailPaneScaffold.kt

4. ระบุการติดตั้งใช้งานแผงรายการไปยัง ListDetailPaneScaffold ใช้ AnimatedPane เพื่อใช้ภาพเคลื่อนไหวของแผงเริ่มต้นระหว่างการไปยังส่วนต่างๆ จากนั้นใช้ ThreePaneScaffoldNavigator เพื่อไปยังแผงรายละเอียด ListDetailPaneScaffoldRole.Detail และแสดงรายการที่ส่ง

   ListDetailPaneScaffold(
       directive = navigator.scaffoldDirective,
       value = navigator.scaffoldValue,
       listPane = {
           AnimatedPane {
               MyList(
                   onItemClick = { item ->
                       // Navigate to the detail pane with the passed item
                       navigator.navigateTo(ListDetailPaneScaffoldRole.Detail, item)
                   }
               )
           }
       },
       // ...
   )
   SampleListDetailPaneScaffold.kt

5. ระบุการติดตั้งใช้งานแผงรายละเอียดใน ListDetailPaneScaffold เมื่อการนําทางเสร็จสมบูรณ์แล้ว currentDestination จะมีแผงที่แอปไปยัง รวมถึงเนื้อหาที่แสดงในแผง พร็อพเพอร์ตี้ content เป็นประเภทเดียวกับที่ระบุในคําเรียก remember เดิม (MyItem ในตัวอย่างนี้) คุณจึงเข้าถึงพร็อพเพอร์ตี้เพื่อดูข้อมูลที่ต้องการแสดงได้ด้วย

   ListDetailPaneScaffold(
       directive = navigator.scaffoldDirective,
       value = navigator.scaffoldValue,
       listPane =
       // ...
       detailPane = {
           AnimatedPane {
               navigator.currentDestination?.content?.let {
                   MyDetails(it)
               }
           }
       },
   )
   SampleListDetailPaneScaffold.kt

หลังจากทำตามขั้นตอนข้างต้นแล้ว โค้ดของคุณควรมีลักษณะดังนี้

val navigator = rememberListDetailPaneScaffoldNavigator<MyItem>()

BackHandler(navigator.canNavigateBack()) {
    navigator.navigateBack()
}

ListDetailPaneScaffold(
    directive = navigator.scaffoldDirective,
    value = navigator.scaffoldValue,
    listPane = {
        AnimatedPane {
            MyList(
                onItemClick = { item ->
                    // Navigate to the detail pane with the passed item
                    navigator.navigateTo(ListDetailPaneScaffoldRole.Detail, item)
                },
            )
        }
    },
    detailPane = {
        AnimatedPane {
            // Show the detail pane content if selected item is available
            navigator.currentDestination?.content?.let {
                MyDetails(it)
            }
        }
    },
)
SampleListDetailPaneScaffold.kt