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

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

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

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

อภิธานศัพท์

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

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

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

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

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 ที่มีอยู่ อย่าฮาร์ดโค้ดค่าที่ย้ายข้อมูล