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

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

ประโยชน์สำคัญอย่างหนึ่งของการใช้ 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 ของเวอร์ชันตัวอย่างได้ เพื่อระบุการกำหนดค่าสำหรับ 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

เมื่อคุณพยายามแสดงตัวอย่าง Composable ด้วย ViewModel Android Studio จะแสดง เมื่อแสดงผล Composable เฉพาะ:

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