สร้าง UI ด้วยข้อมูลโดยย่อ

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

ใช้ Box, Column และ Row

Glance มีเลย์เอาต์ที่สร้างได้ 3 แบบหลักๆ ดังนี้

  • Box: วางองค์ประกอบซ้อนทับกัน ซึ่งจะแปลเป็น RelativeLayout

  • Column: วางองค์ประกอบต่อกันตามแกนแนวตั้ง ซึ่งจะแปลเป็น LinearLayout ที่มีทิศทางแนวตั้ง

  • Row: วางองค์ประกอบต่อกันตามแกนแนวนอน ซึ่งจะแปลเป็น LinearLayout ที่มีการวางแนวแนวนอน

Glance รองรับ Scaffold ออบเจ็กต์ วางคอมโพเนนต์ Column, Row และ Box ไว้ในออบเจ็กต์ Scaffold ที่กำหนด

เลย์เอาต์แบบคอลัมน์ แถว และกล่อง
รูปที่ 1 ตัวอย่างเลย์เอาต์ที่มี Column, Row และ Box

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

ตัวอย่างต่อไปนี้แสดงวิธีสร้าง Row ที่กระจายคอมโพเนนต์ย่อยตามแนวนอนอย่างเท่าๆ กัน ดังที่แสดงในรูปที่ 1

Row(modifier = GlanceModifier.fillMaxWidth().padding(16.dp)) {
    val modifier = GlanceModifier.defaultWeight()
    Text("first", modifier)
    Text("second", modifier)
    Text("third", modifier)
}

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

ใช้เลย์เอาต์ที่เลื่อนได้

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

ข้อมูลโค้ดต่อไปนี้แสดงวิธีต่างๆ ในการกำหนดรายการภายใน 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)
}

การเลื่อนแบบสแนป

การเลื่อนแบบสแนปคือภาพเคลื่อนไหวที่ช่วยให้เนื้อหาที่เลื่อนได้จัดพอดีกับด้านบนของคอนเทนเนอร์วิดเจ็ต

วิดีโอ 1 ด้านซ้ายแสดงรายการที่ไม่ได้สแนปเข้าที่ขณะเลื่อน ส่วนด้านขวาสแนปเข้าที่


หากต้องการใช้การเลื่อนแบบสแนป โปรดตรวจสอบว่าคุณมีคุณสมบัติตรงตามเงื่อนไขต่อไปนี้

  • อัปเดตการขึ้นต่อกันของ Glance dependency เป็น 1.3.0-alpha02 ขึ้นไป
  • ตั้งค่า compileSdk เป็น 37 ขึ้นไป เนื่องจากระบบรองรับการเลื่อนแบบสแนปในอุปกรณ์ที่ใช้ Android 17 ขึ้นไป
  • กำหนดค่า LazyColumn ด้วย VerticalScrollMode หากอุปกรณ์รองรับการเลื่อนแบบสแนป ให้ใช้ SnapScrollMatchHeight หากไม่รองรับ ให้ใช้ Normal

หากคุณใช้การเลื่อนแบบสแนปกับรูปภาพ โปรดดูเลย์เอาต์มาตรฐานของรูปภาพแบบเต็มขอบ

@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 ขนาดอาจแตกต่างกันไปตามอุปกรณ์ ตัวเลือกของผู้ใช้ หรือ Launcher ดังนั้นจึงควรจัดเลย์เอาต์ที่ยืดหยุ่นตามที่อธิบายไว้ในหน้าจัด เลย์เอาต์วิดเจ็ตที่ยืดหยุ่น 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 เช่น หาก Launcher ไม่ได้ระบุรายการขนาด ระบบจะใช้ขนาดต่ำสุดที่เป็นไปได้
  • ในอุปกรณ์ที่ใช้ Android เวอร์ชันก่อน Android 12 ตรรกะการคำนวณขนาดอาจใช้ไม่ได้ในบางสถานการณ์

โดยทั่วไป คุณควรใช้โหมดนี้หากใช้ SizeMode.Responsive ไม่ได้ (นั่นคือ การจัดเลย์เอาต์ที่ปรับเปลี่ยนตามอุปกรณ์ได้จำนวนเล็กน้อยไม่สามารถทำได้)

เข้าถึงทรัพยากร

ใช้ LocalContext.current เพื่อเข้าถึงทรัพยากร Android ใดก็ได้ ดังที่แสดงในตัวอย่างต่อไปนี้

LocalContext.current.getString(R.string.glance_title)

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

คอมโพเนนต์และเมธอดยอมรับทรัพยากรโดยใช้ "ผู้ให้บริการ" เช่น 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"
)

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

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 มีการเปิดตัวคอมโพเนนต์เพิ่มเติมตามที่อธิบายไว้ในตารางต่อไปนี้

ชื่อ รูปภาพ ลิงก์ที่อ้างอิง หมายเหตุเพิ่มเติม
ปุ่มแบบเติมสี alt_text คอมโพเนนต์
ปุ่มแบบเติมขอบ alt_text คอมโพเนนต์
ปุ่มไอคอน alt_text คอมโพเนนต์ หลัก / รอง / ไอคอนเท่านั้น
แถบชื่อ alt_text คอมโพเนนต์
Scaffold Scaffold และแถบชื่ออยู่ในเดโมเดียวกัน

ดูข้อมูลเพิ่มเติมเกี่ยวกับรายละเอียดการออกแบบได้ที่การออกแบบคอมโพเนนต์ในชุดการออกแบบนี้ใน Figma

ดูข้อมูลเพิ่มเติมเกี่ยวกับเลย์เอาต์มาตรฐานได้ที่ เลย์เอาต์มาตรฐานของวิดเจ็ต

ก่อนหน้า
จัดการและอัปเดต GlanceAppWidget
ถัดไป
ใช้ธีมข้อมูลโดยย่อ