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

Composable จะกำหนดโดยฟังก์ชันและกำกับเนื้อหาด้วย @Composable ดังนี้

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

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

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

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

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

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

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

กำหนด@Preview

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

ขนาด

โดยค่าเริ่มต้น ระบบจะเลือกขนาด @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 เพื่อกำหนดการกำหนดค่าสำหรับ Composable ในอุปกรณ์ต่างๆ ได้

เมื่อพารามิเตอร์อุปกรณ์มีสตริงว่าง (@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

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

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

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

UI ของระบบ

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

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

โหมด UI

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

LocalInspectionMode

คุณสามารถอ่านจาก LocalInspectionMode CompositionLocal เพื่อดูว่า Composable แสดงผลในตัวอย่างหรือไม่ (ภายในคอมโพเนนต์ที่ตรวจสอบได้) หากคอมโพสิชันแสดงผลในตัวอย่าง 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

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

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

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

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

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

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

คุณคัดลอกตัวอย่างที่แสดงผลแต่ละรายการเป็นรูปภาพได้โดยคลิกขวาที่ตัวอย่างนั้น

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

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

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

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

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

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

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

@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

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

@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

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

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

บ่อยครั้งที่จำเป็นต้องส่งชุดข้อมูลขนาดใหญ่ไปยังตัวอย่างที่ประกอบกันได้ โดยในการดำเนินการ เพียงส่งข้อมูลจากการสุ่มตัวอย่างไปยังฟังก์ชัน Composable 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 รายการต่อองค์ประกอบข้อมูลในลำดับ ดังนี้

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

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

ตัวอย่างที่ใช้ @PreviewParameter จะได้รับการตั้งชื่อโดยค่าเริ่มต้นโดยใช้ดัชนีพารามิเตอร์และชื่อพร็อพเพอร์ตี้ (ผู้ใช้ 0, ผู้ใช้ 1, ผู้ใช้ 2 และอื่นๆ) ซึ่งอาจทำให้แยกความแตกต่างได้ยาก หากต้องการปรับปรุงความชัดเจนของตัวอย่าง คุณสามารถระบุชื่อที่แสดงที่กำหนดเองสำหรับตัวอย่างแต่ละรายการได้โดยลบล้าง getDisplayName() ใน PreviewParameterProvider ซึ่งจะช่วยแยกความแตกต่างระหว่างรูปแบบข้อมูลหรือสถานะ UI ต่างๆ ตัวอย่างเช่น คุณสามารถติดป้ายกำกับตัวอย่างตามข้อมูลที่ป้อนได้ดังนี้

class UserAgePreviewParameterProvider : PreviewParameterProvider<User> {
    // Using a List internally for efficient index-based access
    private val userList = listOf(
        User(name = "Elise", age = 30),
        User(name = "Frank", age = 31),
        User(name = "Julia", age = 40)
    )

    override val values = userList.asSequence()

    override fun getDisplayName(index: Int): String? {
        // Return null or an empty string to use the default index-based name
        val user = userList.getOrNull(index) ?: return null
        return "${user.name} - ${user.age}"
    }
}
AndroidStudioComposeSnippets.kt

การสร้างตัวอย่างที่มีการใช้งาน AI

AI Agent ใน Android Studio สามารถสร้างตัวอย่าง Compose สำหรับ Composable โดยอัตโนมัติ คลิกขวาที่ฟังก์ชันที่ประกอบกันได้ แล้วเลือก AI > สร้างตัวอย่างสำหรับ [ชื่อฟังก์ชันที่ประกอบกันได้] Agent จะวิเคราะห์ Composable เพื่อสร้างต้นแบบ @Preview ที่จำเป็นพร้อมพารามิเตอร์ที่ถูกต้อง ซึ่งจะช่วยให้คุณยืนยันได้อย่างรวดเร็วว่า UI แสดงผลตามที่คาดไว้

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

ข้อจำกัดของตัวอย่าง

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

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

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

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

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

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

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

@Composable
fun AuthorScreen(
  name: NameLabel,
  posts: PostsList
) {
  // ...
}

@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]
) {
  AuthorScreen(
      name = NameLabel(name),
      posts = PostsList(posts)
  )
}

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

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