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

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

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

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

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

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

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

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

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

กําหนด@Preview

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

ขนาด

โดยค่าเริ่มต้น ระบบจะเลือกมิติข้อมูล @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

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

โดยค่าเริ่มต้น คอมโพสิเบิลจะแสดงโดยมีพื้นหลังโปร่งใส หากต้องการเพิ่มพื้นหลัง ให้เพิ่มพารามิเตอร์ showBackground และ backgroundColor โปรดทราบว่า backgroundColor คือ ARGB Long ไม่ใช่ค่า 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 เพื่อดูว่าคอมโพสิเบิลแสดงผลในตัวอย่างหรือไม่ (ภายในคอมโพเนนต์ที่ตรวจสอบได้) หากคอมโพสชันแสดงผลในตัวอย่าง 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 โดยใช้ตัวอย่างเพลงได้ดียิ่งขึ้น

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

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

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

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

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

คุณสามารถเรียกใช้ @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

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

@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 และชุดข้อมูลขนาดใหญ่

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

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

หากต้องการดูตัวอย่างคอมโพสิเบิลที่ใช้ 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