หน้านี้จะอธิบายวิธีจัดการขนาดและจัดเลย์เอาต์ที่ยืดหยุ่นและตอบสนอง ด้วย Glance โดยใช้คอมโพเนนต์ Glance ที่มีอยู่
ใช้ Box, Column และ Row
Glance มีเลย์เอาต์ที่สามารถคอมโพสได้ 3 แบบหลักๆ ดังนี้
Box: วางองค์ประกอบซ้อนกัน ซึ่งจะแปลงเป็นRelativeLayoutColumn: วางองค์ประกอบต่อกันในแกนแนวตั้ง ซึ่งจะแปลเป็นLinearLayoutที่มีการวางแนวตั้งRow: วางองค์ประกอบต่อกันในแกนแนวนอน ซึ่งจะเปลี่ยนเป็นLinearLayoutที่มีการวางแนวนอน
Glance รองรับออบเจ็กต์ Scaffold วาง Composable Column, Row และ
Box ภายในออบเจ็กต์ Scaffold ที่กำหนด
Composable แต่ละรายการเหล่านี้ช่วยให้คุณกำหนดการจัดแนวแนวตั้งและแนวนอน ของเนื้อหา รวมถึงความกว้าง ความสูง น้ำหนัก หรือข้อจำกัดการเว้นวรรคโดยใช้ ตัวแก้ไขได้ นอกจากนี้ แต่ละวิดเจ็ตย่อยยังกำหนดตัวแก้ไขเพื่อเปลี่ยนช่องว่าง และการจัดวางภายในวิดเจ็ตหลักได้ด้วย
ตัวอย่างต่อไปนี้แสดงวิธีสร้าง Row ที่กระจาย
องค์ประกอบย่อยในแนวนอนอย่างสม่ำเสมอ ดังที่เห็นในรูปที่ 1
Row(modifier = GlanceModifier.fillMaxWidth().padding(16.dp)) { val modifier = GlanceModifier.defaultWeight() Text("first", modifier) Text("second", modifier) Text("third", modifier) }
Row จะเติมความกว้างสูงสุดที่มี และเนื่องจากแต่ละรายการมี
น้ำหนักเท่ากัน จึงใช้พื้นที่ว่างร่วมกันอย่างเท่าเทียม คุณกำหนดน้ำหนัก
ขนาด ระยะห่าง หรือการจัดแนวที่แตกต่างกันเพื่อปรับเลย์เอาต์ให้ตรงกับความต้องการได้
ใช้เลย์เอาต์ที่เลื่อนได้
อีกวิธีในการแสดงเนื้อหาที่ปรับเปลี่ยนตามอุปกรณ์คือการทำให้เนื้อหาเลื่อนได้ ซึ่งทำได้ด้วย LazyColumn ที่ประกอบได้ Composable นี้ช่วยให้คุณกำหนดชุด
รายการที่จะแสดงภายในคอนเทนเนอร์ที่เลื่อนได้ในวิดเจ็ตแอป
ข้อมูลโค้ดต่อไปนี้แสดงวิธีต่างๆ ในการกำหนดรายการภายใน
LazyColumn
คุณระบุจำนวนรายการได้ดังนี้
// Remember to import Glance Composables // import androidx.glance.appwidget.layout.LazyColumn LazyColumn { items(10) { index: Int -> Text( text = "Item $index", modifier = GlanceModifier.fillMaxWidth() ) } }
ระบุรายการแต่ละรายการ
LazyColumn { item { Text("First Item") } item { Text("Second Item") } }
ระบุรายการหรืออาร์เรย์ของสินค้า
LazyColumn { items(peopleNameList) { name -> Text(name) } }
คุณยังใช้ตัวอย่างก่อนหน้าผสมกันได้ด้วย
LazyColumn { item { Text("Names:") } items(peopleNameList) { name -> Text(name) } // or in case you need the index: itemsIndexed(peopleNameList) { index, person -> Text("$person at index $index") } }
โปรดทราบว่าข้อมูลโค้ดก่อนหน้านี้ไม่ได้ระบุ itemId การระบุ
itemId จะช่วยปรับปรุงประสิทธิภาพและรักษาตำแหน่งการเลื่อน
ผ่านการอัปเดตรายการและ appWidget ตั้งแต่ Android 12 เป็นต้นไป (เช่น เมื่อเพิ่มหรือนำรายการออกจากรายการ) ตัวอย่างต่อไปนี้
แสดงวิธีกำหนด itemId
items(items = peopleList, itemId = { person -> person.id.hashCode().toLong() }) { person -> Text(person.name) }
การเลื่อนแบบสแนป
การเลื่อนแบบสแนปคือภาพเคลื่อนไหวที่ช่วยให้เนื้อหาที่เลื่อนได้สแนปไปที่ด้านบน ของคอนเทนเนอร์วิดเจ็ต
หากต้องการใช้การเลื่อนแบบสแนป โปรดตรวจสอบว่าคุณมีคุณสมบัติตรงตามเงื่อนไขต่อไปนี้
- อัปเดต Dependency ของ Glance เป็น 1.3.0-alpha02 ขึ้นไป
- ตั้งค่า
compileSdkเป็น 37 ขึ้นไป เนื่องจากอุปกรณ์ที่ใช้ Android 17 ขึ้นไปรองรับการเลื่อนแบบสแนป - กำหนดค่า
LazyColumnด้วยVerticalScrollModeหากอุปกรณ์รองรับการเลื่อนแบบสแนป ให้ใช้SnapScrollMatchHeightหรือใช้Normal
หากคุณใช้การเลื่อนแบบสแนปกับรูปภาพ โปรดดูเลย์เอาต์ Canonical ของรูปภาพแบบเต็มขอบ จรดขอบ
@Composable fun SnapScrollLayout() { val height = LocalSize.current.height val items = listOf( ColorItem(Color.Red, "Red"), ColorItem(Color.Yellow, "Yellow"), ColorItem(Color.Blue, "Blue") ) val scrollMode = if (Build.VERSION.SDK_INT >= 37) { VerticalScrollMode.SnapScrollMatchHeight(height) } else { VerticalScrollMode.Normal } LazyColumn( verticalScrollMode = scrollMode ) { items(items) { item -> ColorCard(item, height) } } } @Composable private fun ColorCard(item: ColorItem, height: Dp) { Box( modifier = GlanceModifier .background(item.color) .fillMaxWidth() .height(height), contentAlignment = Alignment.Center ) { Text( text = item.name, modifier = GlanceModifier.background(Color.White) ) } }
กำหนดSizeMode
AppWidgetอาจมีขนาดแตกต่างกันไปตามอุปกรณ์ ตัวเลือกของผู้ใช้ หรือตัวเรียกใช้
ดังนั้นจึงควรระบุเลย์เอาต์ที่ยืดหยุ่นตามที่อธิบายไว้ในหน้าระบุ
เลย์เอาต์วิดเจ็ตที่ยืดหยุ่น Glance ช่วยลดความซับซ้อนด้วยSizeMode
คำจำกัดความและค่า LocalSize ส่วนต่อไปนี้จะอธิบายโหมดทั้ง 3
SizeMode.Single
SizeMode.Single เป็นโหมดเริ่มต้น ซึ่งหมายความว่ามีการระบุเนื้อหาเพียงประเภทเดียว กล่าวคือ แม้ว่าAppWidgetขนาดที่ใช้ได้จะเปลี่ยนไป
แต่ขนาดเนื้อหาจะไม่เปลี่ยนแปลง
class MyAppWidget : GlanceAppWidget() { override val sizeMode = SizeMode.Single override suspend fun provideGlance(context: Context, id: GlanceId) { // ... provideContent { MyContent() } } @Composable private fun MyContent() { // Size will be the minimum size or resizable // size defined in the App Widget metadata val size = LocalSize.current // ... } }
เมื่อใช้โหมดนี้ โปรดตรวจสอบว่า
- มีการกำหนดค่าข้อมูลเมตาขนาดต่ำสุดและสูงสุดอย่างถูกต้องตามขนาดเนื้อหา
- เนื้อหามีความยืดหยุ่นเพียงพอภายในช่วงขนาดที่คาดไว้
โดยทั่วไป คุณควรใช้โหมดนี้ในกรณีต่อไปนี้
ก) AppWidget มีขนาดคงที่ หรือ
ข) ไม่เปลี่ยนเนื้อหาเมื่อปรับขนาด
SizeMode.Responsive
โหมดนี้เทียบเท่ากับการระบุเลย์เอาต์ที่ตอบสนองตามอุปกรณ์ ซึ่งช่วยให้ GlanceAppWidget กำหนดชุดเลย์เอาต์ที่ตอบสนองตามอุปกรณ์ซึ่งมีขนาดที่เฉพาะเจาะจง สำหรับขนาดที่กำหนดแต่ละขนาด ระบบจะสร้างเนื้อหาและแมปกับขนาดที่เฉพาะเจาะจงเมื่อมีการสร้างหรืออัปเดต AppWidget จากนั้นระบบจะเลือก
ขนาดที่เหมาะสมที่สุดตามขนาดที่มี
ตัวอย่างเช่น ในปลายทาง AppWidget คุณสามารถกำหนดขนาด 3 ขนาดและเนื้อหาของขนาดเหล่านั้นได้ดังนี้
class MyAppWidget : GlanceAppWidget() { companion object { private val SMALL_SQUARE = DpSize(100.dp, 100.dp) private val HORIZONTAL_RECTANGLE = DpSize(250.dp, 100.dp) private val BIG_SQUARE = DpSize(250.dp, 250.dp) } override val sizeMode = SizeMode.Responsive( setOf( SMALL_SQUARE, HORIZONTAL_RECTANGLE, BIG_SQUARE ) ) override suspend fun provideGlance(context: Context, id: GlanceId) { // ... provideContent { MyContent() } } @Composable private fun MyContent() { // Size will be one of the sizes defined above. val size = LocalSize.current Column { if (size.height >= BIG_SQUARE.height) { Text(text = "Where to?", modifier = GlanceModifier.padding(12.dp)) } Row(horizontalAlignment = Alignment.CenterHorizontally) { Button() Button() if (size.width >= HORIZONTAL_RECTANGLE.width) { Button("School") } } if (size.height >= BIG_SQUARE.height) { Text(text = "provided by X") } } } }
ในตัวอย่างก่อนหน้า ระบบจะเรียกใช้เมธอด provideContent 3 ครั้งและ
แมปกับขนาดที่กำหนด
- ในการเรียกครั้งแรก ขนาดจะประเมินเป็น
100x100เนื้อหาไม่มีปุ่มเพิ่มเติม รวมถึงข้อความด้านบนและด้านล่าง - ในการเรียกครั้งที่ 2 ขนาดจะประเมินค่าเป็น
250x100เนื้อหาประกอบด้วย ปุ่มพิเศษ แต่ไม่มีข้อความด้านบนและด้านล่าง - ในการเรียกครั้งที่ 3 ขนาดจะประเมินเป็น
250x250เนื้อหาประกอบด้วย ปุ่มพิเศษและข้อความทั้ง 2 รายการ
SizeMode.Responsive เป็นการผสมผสานระหว่างอีก 2 โหมด และช่วยให้คุณ
กำหนดเนื้อหาที่ปรับเปลี่ยนตามพื้นที่โฆษณาภายในขอบเขตที่กำหนดไว้ล่วงหน้าได้ โดยทั่วไปแล้ว โหมดนี้จะทำงานได้ดีกว่าและช่วยให้การเปลี่ยนผ่านราบรื่นขึ้นเมื่อมีการปรับขนาด AppWidget
ตารางต่อไปนี้แสดงค่าของขนาด โดยขึ้นอยู่กับ SizeMode และขนาดที่พร้อมใช้งานของ AppWidget
| ขนาดที่มีจำหน่าย | 105 x 110 | 203 x 112 | 72 x 72 | 203 x 150 |
|---|---|---|---|---|
SizeMode.Single |
110 x 110 | 110 x 110 | 110 x 110 | 110 x 110 |
SizeMode.Exact |
105 x 110 | 203 x 112 | 72 x 72 | 203 x 150 |
SizeMode.Responsive |
80 x 100 | 80 x 100 | 80 x 100 | 150 x 120 |
| * ค่าที่แน่นอนมีไว้เพื่อการสาธิตเท่านั้น |
SizeMode.Exact
SizeMode.Exact เทียบเท่ากับการระบุเลย์เอาต์ที่แน่นอน ซึ่งจะขอเนื้อหา GlanceAppWidget ทุกครั้งที่ขนาด AppWidget ที่ใช้ได้เปลี่ยนไป (เช่น เมื่อผู้ใช้ปรับขนาด AppWidget ในหน้าจอหลัก)
เช่น ในวิดเจ็ตปลายทาง คุณสามารถเพิ่มปุ่มพิเศษได้หาก ความกว้างที่ใช้ได้มีค่ามากกว่าค่าหนึ่งๆ
class MyAppWidget : GlanceAppWidget() { override val sizeMode = SizeMode.Exact override suspend fun provideGlance(context: Context, id: GlanceId) { // ... provideContent { MyContent() } } @Composable private fun MyContent() { // Size will be the size of the AppWidget val size = LocalSize.current Column { Text(text = "Where to?", modifier = GlanceModifier.padding(12.dp)) Row(horizontalAlignment = Alignment.CenterHorizontally) { Button() Button() if (size.width > 250.dp) { Button("School") } } } } }
โหมดนี้มีความยืดหยุ่นมากกว่าโหมดอื่นๆ แต่ก็มีข้อควรระวังบางประการดังนี้
- ต้องสร้าง
AppWidgetใหม่ทั้งหมดทุกครั้งที่ขนาดเปลี่ยนแปลง ซึ่งอาจทำให้เกิดปัญหาด้านประสิทธิภาพและ UI กระโดดเมื่อเนื้อหามีความซับซ้อน - ขนาดที่ใช้ได้อาจแตกต่างกันไปตามการติดตั้งใช้งานของ Launcher เช่น หากตัวเรียกใช้ไม่ได้ระบุรายการขนาด ระบบจะใช้ขนาดขั้นต่ำ ที่เป็นไปได้
- ในอุปกรณ์ที่ใช้ Android เวอร์ชันก่อน 12 ตรรกะการคำนวณขนาดอาจไม่ทำงานในบางสถานการณ์
โดยทั่วไป คุณควรใช้โหมดนี้หากSizeMode.Responsiveใช้ไม่ได้
(กล่าวคือ เลย์เอาต์ที่ปรับเปลี่ยนตามพื้นที่โฆษณาจำนวนเล็กน้อยไม่สามารถใช้งานได้)
เข้าถึงแหล่งข้อมูล
ใช้ LocalContext.current เพื่อเข้าถึงทรัพยากร Android ตามที่แสดงในตัวอย่างต่อไปนี้
LocalContext.current.getString(R.string.glance_title)
เราขอแนะนําให้ระบุรหัสทรัพยากรโดยตรงเพื่อลดขนาดของออบเจ็กต์ RemoteViews สุดท้ายและเพื่อเปิดใช้ทรัพยากรแบบไดนามิก เช่น สีแบบไดนามิก
Composables และเมธอดยอมรับทรัพยากรโดยใช้ "ผู้ให้บริการ" เช่น
ImageProvider หรือใช้เมธอดโอเวอร์โหลด เช่น
GlanceModifier.background(R.color.blue) เช่น
Column( modifier = GlanceModifier.background(R.color.default_widget_background) ) { /**...*/ } Image( provider = ImageProvider(R.drawable.ic_logo), contentDescription = "My image", )
จัดการข้อความ
Glance 1.1.0 มี API สำหรับตั้งค่ารูปแบบข้อความ ตั้งค่ารูปแบบข้อความโดยใช้แอตทริบิวต์
fontSize, fontWeight หรือ fontFamily ของคลาส TextStyle
fontFamily รองรับแบบอักษรของระบบทั้งหมด ดังที่แสดงในตัวอย่างต่อไปนี้ แต่ไม่รองรับแบบอักษรที่กำหนดเองในแอป
Text(
style = TextStyle(
fontWeight = FontWeight.Bold,
fontSize = 18.sp,
fontFamily = FontFamily.Monospace
),
text = "Example Text"
)
เพิ่มปุ่มผสม
ปุ่มผสมเปิดตัวใน Android 12 Glance รองรับความเข้ากันได้แบบย้อนหลังสำหรับปุ่มผสมประเภทต่อไปนี้
ปุ่มผสมเหล่านี้แต่ละปุ่มจะแสดงมุมมองที่คลิกได้ซึ่งแสดงสถานะ "เลือก"
var isApplesChecked by remember { mutableStateOf(false) } var isEnabledSwitched by remember { mutableStateOf(false) } var isRadioChecked by remember { mutableIntStateOf(0) } CheckBox( checked = isApplesChecked, onCheckedChange = { isApplesChecked = !isApplesChecked }, text = "Apples" ) Switch( checked = isEnabledSwitched, onCheckedChange = { isEnabledSwitched = !isEnabledSwitched }, text = "Enabled" ) RadioButton( checked = isRadioChecked == 1, onClick = { isRadioChecked = 1 }, text = "Checked" )
เมื่อสถานะเปลี่ยนแปลง ระบบจะเรียกใช้ Lambda ที่ระบุ คุณจัดเก็บสถานะการเลือกได้ดังตัวอย่างต่อไปนี้
class MyAppWidget : GlanceAppWidget() { override suspend fun provideGlance(context: Context, id: GlanceId) { val myRepository = MyRepository.getInstance() provideContent { val scope = rememberCoroutineScope() val saveApple: (Boolean) -> Unit = { scope.launch { myRepository.saveApple(it) } } MyContent(saveApple) } } @Composable private fun MyContent(saveApple: (Boolean) -> Unit) { var isAppleChecked by remember { mutableStateOf(false) } Button( text = "Save", onClick = { saveApple(isAppleChecked) } ) } }
นอกจากนี้ คุณยังระบุแอตทริบิวต์ colors ให้กับ CheckBox, Switch และ
RadioButton เพื่อปรับแต่งสีได้ด้วย
CheckBox( // ... colors = CheckboxDefaults.colors( checkedColor = ColorProvider(day = colorAccentDay, night = colorAccentNight), uncheckedColor = ColorProvider(day = Color.DarkGray, night = Color.LightGray) ), checked = isChecked, onCheckedChange = { isChecked = !isChecked } ) Switch( // ... colors = SwitchDefaults.colors( checkedThumbColor = ColorProvider(day = Color.Red, night = Color.Cyan), uncheckedThumbColor = ColorProvider(day = Color.Green, night = Color.Magenta), checkedTrackColor = ColorProvider(day = Color.Blue, night = Color.Yellow), uncheckedTrackColor = ColorProvider(day = Color.Magenta, night = Color.Green) ), checked = isChecked, onCheckedChange = { isChecked = !isChecked }, text = "Enabled" ) RadioButton( // ... colors = RadioButtonDefaults.colors( checkedColor = ColorProvider(day = Color.Cyan, night = Color.Yellow), uncheckedColor = ColorProvider(day = Color.Red, night = Color.Blue) ), )
คอมโพเนนต์เพิ่มเติม
Glance 1.1.0 มีการเปิดตัวคอมโพเนนต์เพิ่มเติมตามที่อธิบายไว้ในตารางต่อไปนี้
| ชื่อ | รูปภาพ | ลิงก์ที่อ้างอิง | หมายเหตุเพิ่มเติม |
|---|---|---|---|
| ปุ่มแบบเติมสี |
|
คอมโพเนนต์ | |
| ปุ่มแบบเติมขอบ |
|
คอมโพเนนต์ | |
| ปุ่มไอคอน |
|
คอมโพเนนต์ | หลัก / รอง / ไอคอนเท่านั้น |
| แถบชื่อ |
|
คอมโพเนนต์ | |
| Scaffold | Scaffold และแถบชื่ออยู่ในเดโมเดียวกัน |
ดูข้อมูลเพิ่มเติมเกี่ยวกับการออกแบบที่เฉพาะเจาะจงได้ที่การออกแบบคอมโพเนนต์ในชุดเครื่องมือออกแบบนี้ใน Figma
ดูข้อมูลเพิ่มเติมเกี่ยวกับเลย์เอาต์มาตรฐานได้ที่เลย์เอาต์วิดเจ็ตมาตรฐาน