เลย์เอาต์วิดเจ็ต Canonical

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

ข้อความ

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

ข้อความเท่านั้น

เหมาะสำหรับชื่อ การอัปเดตสถานะ คำอธิบายสั้นๆ หรือสถานการณ์ใดก็ตาม ที่ข้อความบรรทัดเดียวสื่อสารข้อความได้อย่างมีประสิทธิภาพ

ข้อความและรูปภาพ

ใส่รูปภาพเพื่อเพิ่มผลกระทบด้านภาพ ดูข้อมูลเพิ่มเติมได้ที่ จุดพัก เพื่อดูวิธีปรับเลย์เอาต์นี้ให้เหมาะกับหน้าจอขนาดต่างๆ

แถบเครื่องมือ

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

แถบเครื่องมือค้นหา

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

แถบเครื่องมือ

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

รายการ

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

รายการข้อความและรูปภาพ

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

เช็กลิสต์

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

รายการการกระทำ

จัดกลุ่มการควบคุมที่ใช้งานง่ายด้วยรายการการกระทำ ซึ่งสถานะเปิด/ปิด แบบภาพจะให้ความคิดเห็นทันทีเกี่ยวกับสถานะของรายการ

รูปภาพแบบเต็มพื้นที่

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

ตารางกริด

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

รูปภาพเท่านั้น

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

รูปภาพและข้อความ

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

ตัวอย่างโค้ด

ตารางต่อไปนี้แสดงการแมปเลย์เอาต์ Canonical แต่ละรายการกับการใช้งาน Jetpack Glance ที่เกี่ยวข้องใน ที่เก็บ Android Platform Samples บน GitHub

เลย์เอาต์ Canonical ไฟล์อ้างอิง คำแนะนำ
เลย์เอาต์แบบรายการการกระทำ
  • จัดการการกระทำของรายการด้วยการเรียกกลับการกระทำของ Glance และตรวจสอบว่ามีการอัปเดตสถานะอย่างเหมาะสม
เลย์เอาต์แบบรายการ
  • ใช้พารามิเตอร์การกระทำหรือการเรียกกลับเพื่อสลับสถานะช่องทำเครื่องหมายเพื่ออัปเดตรายการคอลเล็กชัน
  • ใช้การเรียกกลับการทำงานของ Glance เช่น `actionRunCallback`, `ActionCallback(actionParametersOf(...))` หรือ `actionStartActivity(...)` สำหรับพารามิเตอร์ `onClick` ของวิดเจ็ตเพื่อจัดการกิจกรรมการคลิก เช่น การแตะช่องทำเครื่องหมาย
เลย์เอาต์แถบเครื่องมือที่แสดงลักษณะของเสียง
  • หลีกเลี่ยงข้อผิดพลาดในการนำเข้า `ColorProvider` โดยนำเข้า `androidx.glance.unit.ColorProvider` และใช้ `androidx.glance.color.ColorProvider(dayColor, nightColor)`
  • ใช้ `GlanceModifier.background(Color)` โดยตรงสำหรับสีพื้นหลังทึบแทน `ColorProvider`
เลย์เอาต์ตารางกริดรูปภาพ
  • ใช้สีทึบ (`GlanceModifier.background`) หรือ Drawable ในเครื่องสำหรับรายการรูปภาพ เว้นแต่จะมีการกำหนดค่าหรือขอใช้ไลบรารีการโหลดรูปภาพ
เลย์เอาต์แบบรายการรูปภาพและข้อความ
  • Use Case ทั่วไป ได้แก่ ฟีดข่าว รายการบทความ ประวัติการออกกำลังกาย ฟีดข้อความ และรายการภาพขนาดย่อแนวตั้ง
  • ปรับความสูงของแถวรายการและการตัดข้อความให้สมดุลเมื่อรวมรูปภาพภาพขนาดย่อกับข้อความหลัก/รอง
เลย์เอาต์ข้อความยาว
  • หากคุณคูณค่า `Dp` เช่น `2 * padding` ให้นำเข้า `androidx.compose.ui.unit.times`
  • ปฏิบัติตามกฎการปรับขนาด โดยใช้ขนาดจาก `dimens.xml` สำหรับ การปรับขนาดการจัดวางข้อความและการพิมพ์
เลย์เอาต์แถบเครื่องมือค้นหา
  • หลีกเลี่ยงข้อผิดพลาดในการนำเข้า `ColorProvider` โดยนำเข้า `androidx.glance.unit.ColorProvider` และใช้ `androidx.glance.color.ColorProvider(dayColor, nightColor)`
  • ใช้ `GlanceModifier.background(Color)` โดยตรงสำหรับสีพื้นหลังทึบแทน ColorProvider
เลย์เอาต์รูปภาพแบบเต็มพื้นที่ / การเลื่อนแบบสแนป
  • ตั้งค่า `verticalScrollMode = VerticalScrollMode.SnapScrollMatchHeight(size.height)` ใน LazyColumn สำหรับการเลื่อนแบบสแนป
  • หากคุณใช้การเลื่อนแบบสแนป คุณต้องใช้ Glance 1.3.0-alpha02 ขึ้นไป, Compile SDK 37 (Baklava) ขึ้นไป และปลั๊กอิน Android Gradle (AGP) 9.1.0 ขึ้นไป
  • ตั้งค่า `override val sizeMode: SizeMode = SizeMode.Exact` ในคลาสผู้ให้บริการวิดเจ็ต
เลย์เอาต์แถบเครื่องมือมาตรฐาน
  • ดูการแก้ปัญหาเพื่อหลีกเลี่ยงข้อผิดพลาดในการนำเข้า `ColorProvider` โดยใช้ `androidx.glance.color.ColorProvider(dayColor, nightColor)`
  • ใช้ `GlanceModifier.background(Color)` โดยตรงสำหรับสีพื้นหลังทึบแทน `ColorProvider`
เลย์เอาต์ข้อความพร้อมรูปภาพ
  • ปฏิบัติตามกฎการปรับขนาดเลย์เอาต์ที่ปรับเปลี่ยนตามอุปกรณ์เพื่อรองรับข้อความและรูปภาพที่แสดงคู่กันหรือซ้อนกันตามขนาดวิดเจ็ตที่ใช้ได้