ย้ายข้อมูลธีม 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
Shapes	ออบเจ็กต์ Compose ที่ใช้เพื่อกำหนดรูปร่างคอมโพเนนต์ที่กำหนดเองสำหรับ MaterialTheme
Typography	ออบเจ็กต์ Compose ที่ใช้เพื่อกำหนดรูปแบบข้อความที่กำหนดเอง (ตระกูลแบบอักษร ขนาด ความหนา) สำหรับ MaterialTheme
ColorScheme	ออบเจ็กต์ Compose ที่ใช้เพื่อกำหนดรูปแบบสีที่กำหนดเองสำหรับ MaterialTheme
ธีม XML	ระบบการกำหนดธีม Android ที่กำหนดไว้ในไฟล์ XML ซึ่งระบบ View ใช้

ข้อจำกัด

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

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

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

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

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

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

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

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

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

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

เขียนบทบาท	ชื่อ 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 จะรวมแอตทริบิวต์หลายรายการเพื่อสร้างสไตล์ โดยจะกำหนดสไตล์จาก styles.xml ใน 2 วิธีที่แตกต่างกัน ดังนี้

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

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

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

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

ตัวอย่างที่พบบ่อย

XML	เขียน
Theme.Material3.*	MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium	TextStyle(...) ที่กำหนดไว้ใน Typography(bodyMedium = ...)
ShapeAppearance.*.SmallComponent	Shapes(small = RoundedCornerShape(X.dp))
Widget.Material3.Button	Button(colors = ButtonDefaults.buttonColors(...))
Widget.Material3.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 ที่มีอยู่ อย่าฮาร์ดโค้ดค่าที่ย้ายข้อมูล