Composable จะกำหนดโดยฟังก์ชันและมีคำอธิบายประกอบด้วย @Composable
:
@Composable fun SimpleComposable() { Text("Hello World") }
หากต้องการแสดงตัวอย่าง Composable นี้ ให้สร้าง Composable อื่นที่มีคำอธิบายประกอบ
กับ @Composable
และ @Preview
ตอนนี้ Composable ที่มีคำอธิบายประกอบใหม่นี้มี
Composable ที่คุณสร้างขึ้นในตอนแรก SimpleComposable
:
@Preview @Composable fun SimpleComposablePreview() { SimpleComposable() }
คำอธิบายประกอบ @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") } }
ตัวอย่างสีแบบไดนามิก
หากคุณเปิดใช้ไดนามิก
สีในแอปของคุณ
ใช้แอตทริบิวต์ 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)) }
ตั้งค่าสีพื้นหลัง
โดยค่าเริ่มต้น Composable จะแสดงพร้อมพื้นหลังโปร่งใส หากต้องการเพิ่ม
พื้นหลัง ให้เพิ่มพารามิเตอร์ showBackground
และ backgroundColor
เก็บใน
โปรดทราบว่า backgroundColor
เป็น ARGB Long
ไม่ใช่ Color
ค่า:
@Preview(showBackground = true, backgroundColor = 0xFF00FF00) @Composable fun WithGreenBackground() { Text("Hello World") }
UI ของระบบ
หากคุณต้องการแสดงแถบสถานะและแถบการดำเนินการในตัวอย่าง ให้เพิ่ม
พารามิเตอร์ showSystemUi
รายการ:
@Preview(showSystemUi = true) @Composable fun DecoratedComposablePreview() { Text("Hello World") }
![หน้าต่างแสดงตัวอย่างแสดงกิจกรรมพร้อมแถบสถานะและแถบการดำเนินการ](https://developer.android.com/static/develop/ui/compose/images/tooling-decorated-preview.png?authuser=9&hl=th)
โหมด 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!") } }
โต้ตอบกับ @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
คุณสามารถใช้คำอธิบายประกอบที่กำหนดเองนี้สำหรับ Composable ตัวอย่าง:
@FontScalePreviews @Composable fun HelloWorldPreview() { Text("Hello World") }
คุณสามารถรวมคำอธิบายประกอบแบบหลายตัวอย่างและคำอธิบายประกอบตัวอย่างปกติหลายรายการได้ เพื่อสร้างชุดตัวอย่างที่สมบูรณ์มากขึ้น การรวมคำอธิบายประกอบแบบหลายตัวอย่าง ไม่ได้หมายความว่าชุดค่าผสมทั้งหมดจะแสดง โดยแต่ละรายการ คำอธิบายประกอบ Multipreview จะทำงานอย่างอิสระและแสดงผลเฉพาะรูปแบบของตัวเอง
@Preview( name = "Spanish", group = "locale", locale = "es" ) @FontScalePreviews annotation class CombinedPreviews @CombinedPreviews @Composable fun HelloWorldPreview2() { MaterialTheme { Surface { Text(stringResource(R.string.hello_world)) } } }
ลักษณะการผสมและจับคู่ของการดูแบบหลายตัวอย่างและตัวอย่างแบบปกติ ช่วยให้คุณ ทดสอบพร็อพเพอร์ตี้จำนวนมากของโปรเจ็กต์ขนาดใหญ่อย่างครอบคลุม
@Preview
และชุดข้อมูลขนาดใหญ่
บ่อยครั้งที่คุณจำเป็นต้องส่งชุดข้อมูลขนาดใหญ่ไปยัง Composable
เวอร์ชันตัวอย่าง ในการดำเนินการนี้ เพียงส่งผ่านข้อมูลตัวอย่างไปยังฟังก์ชันแสดงตัวอย่างแบบประกอบได้โดย
การเพิ่มพารามิเตอร์ที่มี @PreviewParameter
หมายเหตุ
@Preview @Composable fun UserProfilePreview( @PreviewParameter(UserPreviewParameterProvider::class) user: User ) { UserProfile(user) }
หากต้องการจัดเตรียมข้อมูลตัวอย่าง ให้สร้างคลาสที่นำไปใช้
PreviewParameterProvider
และแสดงผล
สุ่มตัวอย่างข้อมูลเป็นลำดับ
class UserPreviewParameterProvider : PreviewParameterProvider<User> { override val values = sequenceOf( User("Elise"), User("Frank"), User("Julia") ) }
ระบบจะแสดงตัวอย่าง 1 ตัวอย่างต่อองค์ประกอบข้อมูลในลำดับดังนี้
คุณใช้คลาสผู้ให้บริการเดียวกันสำหรับตัวอย่างหลายรายการได้ จำกัดเวลา หากจำเป็น จำนวนตัวอย่างโดยการตั้งค่าพารามิเตอร์ลิมิต
@Preview @Composable fun UserProfilePreview2( @PreviewParameter(UserPreviewParameterProvider::class, limit = 2) user: User ) { UserProfile(user) }
ข้อจำกัดและแนวทางปฏิบัติแนะนำ
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, )
แหล่งข้อมูลเพิ่มเติม
หากต้องการอ่านเพิ่มเติมเกี่ยวกับวิธีที่ Android Studio โปรโมตการใช้งานง่ายของ @Preview
และดู
เคล็ดลับเพิ่มเติมเกี่ยวกับเครื่องมือ โปรดดูที่บล็อกเขียน
การใช้เครื่องมือ
แนะนำสำหรับคุณ
- หมายเหตุ: ข้อความลิงก์จะแสดงเมื่อ JavaScript ปิดอยู่
- ข้อมูลที่กำหนดขอบเขตเฉพาะพื้นที่ด้วย CompositionLocal
- ดีไซน์ Material 2 ใน Compose
- การใช้มุมมองในการเขียน