ดูตัวอย่าง UI ด้วยตัวอย่างที่เขียนได้ด้วย Compose

Composable จะกำหนดโดยฟังก์ชันและมีคำอธิบายประกอบด้วย @Composable:

@Composable
fun SimpleComposable() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

องค์ประกอบข้อความง่ายๆ ที่มีคำว่า "Hello World"

หากต้องการเปิดใช้ตัวอย่างของ Composable นี้ ให้สร้าง Composable อื่นซึ่งมีคำอธิบายประกอบด้วย @Composable และ @Preview ตอนนี้ Composable ที่มีคำอธิบายประกอบใหม่นี้มี Composable ที่คุณสร้างไว้ในตอนแรก SimpleComposable:

@Preview
@Composable
fun SimpleComposablePreview() {
    SimpleComposable()
}
AndroidStudioComposeSnippets.kt

คําอธิบายประกอบ @Preview บอก Android Studio ว่าคอมโพสิชันนี้ควรแสดงในมุมมองการออกแบบของไฟล์นี้ คุณจะเห็นการอัปเดตตัวอย่างแบบคอมโพสแบบเรียลไทม์ขณะทำการแก้ไข

GIF แสดงการอัปเดตแบบเรียลไทม์โดยใช้ Compose เวอร์ชันตัวอย่าง

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

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

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

กําหนด@Preview

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

ขนาด

โดยค่าเริ่มต้น ระบบจะเลือกมิติข้อมูล @Preview โดยอัตโนมัติเพื่อตัดเนื้อหา หากต้องการตั้งค่ามิติข้อมูลด้วยตนเอง ให้เพิ่มพารามิเตอร์ heightDp และ widthDp ระบบจะตีความค่าเหล่านั้นเป็น dp อยู่แล้ว คุณจึงไม่ต้องเพิ่ม .dp

@Preview(widthDp = 50, heightDp = 50)
@Composable
fun SquareComposablePreview() {
    Box(Modifier.background(Color.Yellow)) {
        Text("Hello World")
    }
}
AndroidStudioComposeSnippets.kt

สี่เหลี่ยมจัตุรัสสีเหลืองที่มีคำว่า "สวัสดี โลก"

ตัวอย่างสีแบบไดนามิก

หากเปิดใช้สีแบบไดนามิกในแอป ให้ใช้แอตทริบิวต์ wallpaper เพื่อเปลี่ยนวอลเปเปอร์และดูว่า UI ตอบสนองต่อวอลเปเปอร์ที่ผู้ใช้แต่ละรายเลือกอย่างไร เลือกจากธีมวอลเปเปอร์ต่างๆ ที่คลาสWallpaperมีให้บริการ ฟีเจอร์นี้ต้องใช้ Compose 1.4.0 ขึ้นไป

ใช้กับอุปกรณ์อื่น

ใน Android Studio Flamingo คุณสามารถแก้ไขพารามิเตอร์ device ของคำอธิบายประกอบ Preview เพื่อกำหนดการกำหนดค่าสำหรับคอมโพสิชันในอุปกรณ์ต่างๆ ได้

ตัวอย่างฟังก์ชันที่ประกอบกันได้

เมื่อพารามิเตอร์อุปกรณ์มีสตริงว่าง (@Preview(device = "")) คุณจะเรียกใช้การเติมข้อความอัตโนมัติได้โดยกด Ctrl + Space จากนั้นคุณสามารถกําหนดค่าของพารามิเตอร์แต่ละรายการได้

การแก้ไขฟังก์ชันตัวอย่าง

จากการเติมข้อความอัตโนมัติ คุณจะเลือกตัวเลือกอุปกรณ์ใดก็ได้จากรายการ เช่น @Preview(device = "id:pixel_4") หรือจะป้อนอุปกรณ์ที่กําหนดเองก็ได้โดยเลือก spec:width=px,height=px,dpi=int… เพื่อกําหนดค่าแต่ละค่าของพารามิเตอร์แต่ละรายการ

รายการข้อมูลจำเพาะ

หากต้องการใช้ ให้กด Enter หรือยกเลิกด้วย Esc

หากคุณกำหนดค่าไม่ถูกต้อง ระบบจะขีดเส้นใต้การประกาศเป็นสีแดงและอาจมีการแก้ไข (Alt + Enter (⌥ + ⏎ สำหรับ macOS) > แทนที่ด้วย ... การตรวจสอบจะพยายามแก้ไขซึ่งใกล้เคียงกับข้อมูลที่คุณป้อนมากที่สุด

ตัวอย่างค่าที่ไม่ถูกต้อง

ภาษา

หากต้องการทดสอบภาษาที่ต่างกันของผู้ใช้ ให้เพิ่มพารามิเตอร์ locale ดังนี้

@Preview(locale = "fr-rFR")
@Composable
fun DifferentLocaleComposablePreview() {
    Text(text = stringResource(R.string.greeting))
}
AndroidStudioComposeSnippets.kt

องค์ประกอบข้อความง่ายๆ ที่มีคำว่า "Bonjour" พร้อมธงชาติฝรั่งเศส

ตั้งค่าสีพื้นหลัง

โดยค่าเริ่มต้น คอมโพสิเบิลจะแสดงโดยมีพื้นหลังโปร่งใส หากต้องการเพิ่มพื้นหลัง ให้เพิ่มพารามิเตอร์ showBackground และ backgroundColor โปรดทราบว่า backgroundColor คือ ARGB Long ไม่ใช่ค่า Color

@Preview(showBackground = true, backgroundColor = 0xFF00FF00)
@Composable
fun WithGreenBackground() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

สี่เหลี่ยมผืนผ้าสีเขียวที่มีคำว่า "Hello World"

UI ของระบบ

หากต้องการแสดงสถานะและแถบการดำเนินการภายในตัวอย่างเพลง ให้เพิ่มพารามิเตอร์ showSystemUi ดังนี้

@Preview(showSystemUi = true)
@Composable
fun DecoratedComposablePreview() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

หน้าต่างแสดงตัวอย่างแสดงกิจกรรมพร้อมแถบสถานะและแถบการดำเนินการ

โหมด UI

พารามิเตอร์ uiMode สามารถใช้ค่าคงที่ Configuration.UI_* ใดก็ได้และให้คุณเปลี่ยนลักษณะการทํางานของตัวอย่างเพลงได้ตามต้องการ ตัวอย่างเช่น คุณตั้งค่าตัวอย่างเป็นโหมดกลางคืนเพื่อดูการตอบสนองของธีมได้

UI ของตัวอย่างการเขียน

LocalInspectionMode

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

วิธีนี้ยังช่วยให้คุณหลีกเลี่ยงข้อจำกัดได้ด้วย เช่น การแสดงข้อมูลตัวอย่างแทนการเรียกคําขอเครือข่าย

@Composable
fun GreetingScreen(name: String) {
    if (LocalInspectionMode.current) {
        // Show this text in a preview window:
        Text("Hello preview user!")
    } else {
        // Show this text in the app:
        Text("Hello $name!")
    }
}
AndroidStudioComposeSnippets.kt

โต้ตอบกับ @Preview

Android Studio มีฟีเจอร์ที่ช่วยให้คุณโต้ตอบกับตัวอย่างเพลงที่กําหนดไว้ได้ การโต้ตอบนี้จะช่วยให้คุณเข้าใจลักษณะการทํางานรันไทม์ของตัวอย่างเพลง และช่วยให้คุณไปยังส่วนต่างๆ ของ UI โดยใช้ตัวอย่างเพลงได้ดียิ่งขึ้น

โหมดอินเทอร์แอกทีฟ

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

ผู้ใช้คลิกปุ่ม "อินเทอร์แอกทีฟ" ของตัวอย่าง

วิดีโอที่ผู้ใช้โต้ตอบกับตัวอย่าง

การไปยังส่วนต่างๆ ของโค้ดและเค้าโครงแบบคอมโพสิเบิล

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

ผู้ใช้วางเมาส์เหนือตัวอย่าง ซึ่งทำให้ Studio แสดงโครงร่างของคอมโพสิเบิล

แสดงตัวอย่าง

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

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

ผู้ใช้คลิกปุ่ม "แสดงตัวอย่าง" ของตัวอย่าง

วิดีโอแสดงพรีวิวของผู้ใช้ในอุปกรณ์

คัดลอกการแสดงภาพ @Preview

ตัวอย่างที่แสดงทั้งหมดสามารถคัดลอกเป็นรูปภาพได้ด้วยการคลิกขวาที่รูปภาพ

ผู้ใช้คลิกตัวอย่างเพื่อคัดลอกเป็นรูปภาพ

ตัวอย่างคำอธิบายประกอบ @Preview เดียวกันหลายรายการ

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

เทมเพลตตัวอย่างเพลงหลายรายการ

androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01 ขึ้นไปจะเปิดตัวเทมเพลต API แบบหลายตัวอย่าง ได้แก่ @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark และ @PreviewDynamicColors เพื่อให้คุณแสดงตัวอย่าง UI ของ Compose ในสถานการณ์ทั่วไปได้ด้วยการกำกับเนื้อหาเพียงรายการเดียว

แสดงตัวอย่างแบบอักษรและขนาดหน้าจอต่างๆ โดยใช้เทมเพลต

สร้างคำอธิบายประกอบตัวอย่างเพลงหลายรายการที่กำหนดเอง

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

เริ่มต้นด้วยการสร้างคลาสคำอธิบายประกอบที่กำหนดเองของคุณเอง โดยทำดังนี้

@Preview(
    name = "small font",
    group = "font scales",
    fontScale = 0.5f
)
@Preview(
    name = "large font",
    group = "font scales",
    fontScale = 1.5f
)
annotation class FontScalePreviews
AndroidStudioComposeSnippets.kt

คุณใช้คำอธิบายประกอบที่กำหนดเองนี้กับคอมโพสิเบิลตัวอย่างได้

@FontScalePreviews
@Composable
fun HelloWorldPreview() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

แท็บการออกแบบของ Android Studio ที่แสดง Composable ที่มีแบบอักษรขนาดเล็กและขนาดใหญ่

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

@Preview(
    name = "Spanish",
    group = "locale",
    locale = "es"
)
@FontScalePreviews
annotation class CombinedPreviews

@CombinedPreviews
@Composable
fun HelloWorldPreview2() {
    MaterialTheme { Surface { Text(stringResource(R.string.hello_world)) } }
}
AndroidStudioComposeSnippets.kt

แท็บการออกแบบของ Android Studio ที่แสดงคอมโพสิเบิลในการกําหนดค่าทั้งหมด

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

@Preview และชุดข้อมูลขนาดใหญ่

บ่อยครั้งที่คุณต้องส่งชุดข้อมูลขนาดใหญ่ไปยังตัวอย่างที่คอมโพสิเบิล ซึ่งทำได้ง่ายๆ เพียงส่งข้อมูลตัวอย่างไปยังฟังก์ชัน "ตัวอย่างแบบประกอบได้" โดยการเพิ่มพารามิเตอร์ที่มีคำอธิบายประกอบ @PreviewParameter

@Preview
@Composable
fun UserProfilePreview(
    @PreviewParameter(UserPreviewParameterProvider::class) user: User
) {
    UserProfile(user)
}

AndroidStudioComposeSnippets.kt

หากต้องการระบุข้อมูลตัวอย่าง ให้สร้างคลาสที่ใช้ PreviewParameterProvider และแสดงผลข้อมูลตัวอย่างเป็นลําดับ

class UserPreviewParameterProvider : PreviewParameterProvider<User> {
    override val values = sequenceOf(
        User("Elise"),
        User("Frank"),
        User("Julia")
    )
}
AndroidStudioComposeSnippets.kt

ซึ่งจะแสดงตัวอย่าง 1 รายการต่อองค์ประกอบข้อมูลในลําดับ

ตัวอย่างแสดง Elise, Frank และ Julia Composable

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

@Preview
@Composable
fun UserProfilePreview2(
    @PreviewParameter(UserPreviewParameterProvider::class, limit = 2) user: User
) {
    UserProfile(user)
}
AndroidStudioComposeSnippets.kt

ข้อจํากัดและแนวทางปฏิบัติแนะนำ

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

ข้อจํากัดของตัวอย่างเพลง

ตัวอย่างเพลงมีน้ำหนักเบาและไม่ต้องใช้เฟรมเวิร์ก Android ทั้งหมดในการเรนเดอร์ เนื่องจากวิธีแสดงตัวอย่างเพลงภายใน Android Studio แต่มีข้อจํากัดดังนี้

  • ไม่มีสิทธิ์เข้าถึงเครือข่าย
  • ไม่มีสิทธิ์เข้าถึงไฟล์
  • Context API บางรายการอาจยังไม่พร้อมใช้งานอย่างเต็มรูปแบบ

ตัวอย่างเพลงและ ViewModels

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

เมื่อคุณพยายามแสดงตัวอย่างคอมโพสิเบิลด้วย ViewModel Android Studio จะแสดงข้อผิดพลาดเมื่อแสดงผลคอมโพสิเบิลนั้นๆ ดังนี้

แผงปัญหาของ Android Studio พร้อมข้อความ &quot;สร้างอินสแตนซ์ `ViewModel` ไม่สําเร็จ&quot;

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

@Composable
fun AuthorColumn(viewModel: AuthorViewModel = viewModel()) {
  AuthorColumn(
    name = viewModel.authorName,
    // ViewModel sends the network requests and makes posts available as a state
    posts = viewModel.posts
  )
}

@Preview
@Composable
fun AuthorScreenPreview(
  // You can use some sample data to preview your composable without the need to construct the ViewModel
  name: String = sampleAuthor.name,
  posts: List<Post> = samplePosts[sampleAuthor]
) {
  AuthorColumn(...) {
    name = NameLabel(name),
    posts = PostsList(posts)
  }
}

คลาสคำอธิบายประกอบ @Preview

คุณสามารถ "ctrl หรือ ⌘ + คลิก" คําอธิบายประกอบ @Preview ใน Android Studio ได้ทุกเมื่อเพื่อดูรายการพารามิเตอร์ทั้งหมดที่ปรับได้เมื่อปรับแต่งตัวอย่างเพลง

annotation class Preview(
    val name: String = "",
    val group: String = "",
    @IntRange(from = 1) val apiLevel: Int = -1,
    val widthDp: Int = -1,
    val heightDp: Int = -1,
    val locale: String = "",
    @FloatRange(from = 0.01) val fontScale: Float = 1f,
    val showSystemUi: Boolean = false,
    val showBackground: Boolean = false,
    val backgroundColor: Long = 0,
    @UiMode val uiMode: Int = 0,
    @Device val device: String = Devices.DEFAULT,
    @Wallpaper val wallpaper: Int = Wallpapers.NONE,
)
AndroidStudioComposeSnippets.kt

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

หากต้องการอ่านเพิ่มเติมเกี่ยวกับวิธีที่ Android Studio ส่งเสริม@Previewความง่ายในการใช้งาน และดูเคล็ดลับเพิ่มเติมเกี่ยวกับเครื่องมือต่างๆ โปรดไปที่บล็อก Compose Tooling

ถัดไป
แสดงตัวอย่างและแก้ไขข้อบกพร่องภาพเคลื่อนไหว