ย้ายข้อมูลธีม XML ไปยัง Material 3 ใน Compose

เมื่อนำ Compose มาใช้ในแอปที่มีอยู่ คุณต้องย้ายข้อมูลธีม Material XML เพื่อใช้ MaterialTheme กับคอมโพเนนต์ Compose ซึ่งหมายความว่าการกำหนดธีมของแอปจะมีแหล่งข้อมูลที่เชื่อถือได้ 2 แหล่ง ได้แก่ ธีมที่อิงตาม View และธีม Compose คุณต้องทำการเปลี่ยนแปลงการจัดรูปแบบในหลายๆ ที่ เมื่อย้ายข้อมูลแอปไปยัง Compose อย่างสมบูรณ์แล้ว ให้นำการกำหนดธีม XML ออก

คุณสามารถใช้เครื่องมือ Material Theme Builder เพื่อย้ายข้อมูลสี

เมื่อเริ่มย้ายข้อมูลจาก XML ไปยัง Compose ให้ย้ายข้อมูลการกำหนดธีมไปยังการกำหนดธีม Material 3 Compose

อภิธานศัพท์

คำศัพท์	คำจำกัดความ
MaterialTheme	ฟังก์ชันที่ประกอบกันได้ซึ่งกำหนดธีม (สี การพิมพ์ รูปทรง) ให้กับคอมโพเนนต์ UI ของ Compose
Shape	ออบเจ็กต์ Compose ที่ใช้กำหนดรูปทรงคอมโพเนนต์ที่กำหนดเองสำหรับ MaterialTheme
Typography	ออบเจ็กต์ Compose ที่ใช้กำหนดรูปแบบข้อความที่กำหนดเอง (ตระกูลฟอนต์ ขนาด น้ำหนัก) สำหรับ MaterialTheme
Color	ออบเจ็กต์ Compose ที่ใช้กำหนดรูปแบบสีที่กำหนดเองสำหรับ MaterialTheme
ธีม XML	ระบบการกำหนดธีมของ Android ที่กำหนดไว้ในไฟล์ XML ซึ่งระบบ View ใช้

ข้อจำกัด

โปรดทราบข้อจำกัดต่อไปนี้ก่อนย้ายข้อมูล

• คู่มือนี้มุ่งเน้นที่การย้ายข้อมูลไปยัง Material 3 เท่านั้น หากต้องการย้ายข้อมูลจาก ระบบการออกแบบอื่น โปรดดู Material 2 หรือ ระบบการออกแบบที่กำหนดเองใน Compose
• เป้าหมายสูงสุดคือการย้ายข้อมูลไปยัง Compose อย่างสมบูรณ์ ซึ่งจะช่วยให้คุณนำการกำหนดธีม XML ออกได้ คู่มือนี้จะอธิบายวิธีย้ายข้อมูล แต่ไม่ได้อธิบายวิธีนำการกำหนดธีม XML ออกในขั้นตอนสุดท้าย

ขั้นตอนที่ 1: ประเมินระบบการออกแบบ

ระบุระบบการออกแบบที่ใช้ในโปรเจ็กต์ XML View วิเคราะห์เส้นทางการย้ายข้อมูลและขั้นตอนที่จำเป็นในการย้ายข้อมูลระบบการออกแบบที่มีอยู่ไปยัง Material 3 ใน Compose

ขั้นตอนที่ 2: ระบุไฟล์แหล่งที่มาของธีม

ใน XML คุณจะเขียน ?attr/colorPrimary ใน Compose คุณจะเข้าถึงค่าธีมด้วย MaterialTheme.*

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

คุณสามารถใช้ทรัพยากร เช่น สตริง ซ้ำได้เลยโดยไม่ต้องย้ายข้อมูล

ขั้นตอนที่ 3: ย้ายข้อมูลสี

หลักการสำคัญ: XML ใช้สีเลขฐานสิบหกที่มีชื่อ Material 3 ใช้ บทบาทเชิงความหมาย (เช่น primary, onPrimary, surface) หยุดตั้งชื่อสีตามเลขฐานสิบหก แต่ให้ตั้งชื่อตามบทบาท

ตัวอย่าง

ชื่อสี XML	บทบาท Material 3
colorPrimary	primary
colorPrimaryDark / colorPrimaryVariant	primaryContainer หรือ secondary
colorAccent	secondary หรือ tertiary
colorOnPrimary	onPrimary
android:colorBackground	background
colorSurface	surface
colorOnSurface	onSurface
colorError	error
colorOnError	onError
colorOutline	outline
colorSurfaceVariant	surfaceVariant
colorOnSurfaceVariant	onSurfaceVariant

---

ย้ายข้อมูลรูปแบบสีเข้มและสีอ่อนจาก XML ไปยังรูปแบบที่เทียบเท่าใน Material 3 Compose

ขั้นตอนที่ 4: ย้ายข้อมูลรูปทรงและการพิมพ์ที่กำหนดเอง

• หากแอปใช้รูปทรงที่กำหนดเอง ให้ทำดังนี้

  1. กำหนดออบเจ็กต์ Shape ในโค้ด Compose เพื่อจำลองคำจำกัดความของรูปทรง XML

  2. ระบุออบเจ็กต์ Shape นี้ให้กับ MaterialTheme

     ดูรายละเอียดเพิ่มเติมได้ที่ รูปทรง

• หากแอปใช้การพิมพ์ที่กำหนดเอง ให้ทำดังนี้

  1. ในโค้ด Compose ให้กำหนดออบเจ็กต์ Typography เพื่อจำลองรูปแบบข้อความและคำจำกัดความของฟอนต์ XML

  2. ระบุออบเจ็กต์ Typography นี้ให้กับ MaterialTheme

     ดูรายละเอียดเพิ่มเติมได้ที่การพิมพ์

บทบาท Compose	ชื่อ XML
displayLarge	TextAppearance.Material3.DisplayLarge
displayMedium	TextAppearance.Material3.DisplayMedium
displaySmall	TextAppearance.Material3.DisplaySmall
headlineLarge	TextAppearance.Material3.HeadlineLarge
headlineMedium	TextAppearance.Material3.HeadlineMedium
headlineSmall	TextAppearance.Material3.HeadlineSmall
titleLarge	TextAppearance.Material3.TitleLarge
titleMedium	TextAppearance.Material3.TitleMedium
titleSmall	TextAppearance.Material3.TitleSmall
bodyLarge	TextAppearance.Material3.BodyLarge
bodyMedium	TextAppearance.Material3.BodyMedium
bodySmall	TextAppearance.Material3.BodySmall
labelLarge	TextAppearance.Material3.LabelLarge
labelMedium	TextAppearance.Material3.LabelMedium
labelSmall	TextAppearance.Material3.LabelSmall

ขั้นตอนที่ 5: ย้ายข้อมูลรูปแบบ (styles.xml)

ระบบรูปแบบ XML (styles.xml) กำหนดรูปแบบและลักษณะที่ปรากฏของสิ่งต่อไปนี้ 1. วิดเจ็ต คอมโพเนนต์ ธีมสำหรับหน้าต่างและกล่องโต้ตอบ 2. การพิมพ์ 3. ธีมและการวางซ้อน 4. รูปทรง

XML View และคอมโพเนนต์จะรวมแอตทริบิวต์หลายรายการเพื่อสร้างรูปแบบ โดยจะตั้งค่ารูปแบบจาก styles.xml ด้วย 2 วิธีที่แตกต่างกัน ดังนี้ 1. ตั้งค่า "style="@style/..." โดยตรงและอย่างชัดแจ้งใน XML View 2. ตั้งค่ารูปแบบโดยอ้อมและโดยนัยสำหรับคอมโพเนนต์ซึ่งเป็นส่วนหนึ่งของธีมที่ใหญ่ขึ้น (theme.xml)

รูปแบบไม่มีรายการที่เทียบเท่าโดยตรงใน Compose แต่จะส่งรูปแบบเป็นพารามิเตอร์ไปยังคอมโพเนนต์ที่ประกอบกันได้ ซึ่งกำหนดไว้ใน AppTheme หรือโดยการสร้างคอมโพเนนต์ที่ประกอบกันได้แบบเลเยอร์และใช้ซ้ำได้ด้วยรูปแบบที่กำหนด

ระบุฟังก์ชัน @Composable แยกต่างหากซึ่งตั้งชื่อตามรูปแบบและคอมโพเนนต์พื้นฐาน เพื่อแสดงความแตกต่างในการจัดรูปแบบและกรณีการใช้งานสำหรับคอมโพเนนต์เหล่านั้น

• รูปแบบ: หากองค์ประกอบ XML ใช้รูปแบบที่กำหนดเอง (เช่น style="@style/MyPrimaryButton") อย่าพยายามจำลองรูปแบบในบรรทัด แต่ให้แนะนำให้สร้างคอมโพเนนต์ที่ประกอบกันได้ที่เฉพาะเจาะจง
• ตัวอย่าง
  • XML: <Button style="@style/MyPrimaryButton" ... />
  • Compose: MyPrimaryButton(onClick = { ... })
• กลุ่มแอตทริบิวต์ทั่วไป: หากรูปแบบตั้งค่าตัวปรับแต่งทั่วไป (เช่น ระยะขอบภายใน + ความสูง) ให้แยกตัวปรับแต่งเหล่านั้นออกเป็นพร็อพเพอร์ตี้ส่วนขยายที่อ่านได้หรือตัวแปรตัวปรับแต่งที่แชร์

ตัวอย่างทั่วไป

XML	Compose
Theme.MaterialComponents.*	MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium	TextStyle(...) ที่กำหนดไว้ใน Typography(bodyMedium = ...)
ShapeAppearance.*.SmallComponent	Shapes(small = RoundedCornerShape(X.dp))
Widget.MaterialComponents.Button	Button(colors = ButtonDefaults.buttonColors(...))
Widget.MaterialComponents.CardView	Card(shape=..., elevation=..., colors=...)
Widget.*.TextInputLayout.OutlinedBox	OutlinedTextField(colors = OutlinedTextFieldDefaults.colors(...))
Widget.*.Chip.Filter	FilterChip(colors = FilterChipDefaults.filterChipColors(...))
Widget.*.Toolbar.Primary	TopAppBar(colors = TopAppBarDefaults.topAppBarColors(...))
Widget.*.FloatingActionButton	FloatingActionButton(containerColor = ...)
backgroundTint	containerColor ใน ComponentDefaults.ComponentColors()
android:textColor	contentColor ใน ComponentDefaults.ComponentColors()
cornerRadius	shape = RoundedCornerShape(X.dp)
android:elevation	elevation = ComponentDefaults.elevation(defaultElevation = X.dp)
android:padding	contentPadding = PaddingValues(...) หรือ Modifier.padding()
android:minHeight	Modifier.heightIn(min = X.dp)
strokeColor + strokeWidth	border = BorderStroke(width, color)
android:textSize	fontSize = X.sp ใน TextStyle

ขั้นตอนที่ 6: ตรวจสอบการย้ายข้อมูลธีม

ใช้ค่าธีมที่มีอยู่จากธีม XML เดิมเป็นแหล่งข้อมูลที่เชื่อถือได้สำหรับธีม Material ใหม่ใน Compose เสมอ อย่าสร้างค่าธีมใหม่ระหว่างการย้ายข้อมูล เพื่อรักษาความสอดคล้องของแบรนด์และหลีกเลี่ยงการถดถอยของภาพ

ตรวจสอบว่าค่าธีม Compose ใหม่ทั้งหมดตรงกับค่า XML ที่มีอยู่ อย่าฮาร์ดโค้ดค่าที่ย้ายข้อมูล