وقتی Compose را در یک برنامه موجود معرفی میکنید، باید تمهای XML متریال خود را برای استفاده از MaterialTheme برای کامپوننتهای Compose منتقل کنید. این بدان معناست که تمبندی برنامه شما دو منبع اعتبار خواهد داشت: تم مبتنی بر View و تم Compose. هرگونه تغییر در استایل شما باید در چندین مکان انجام شود. پس از انتقال کامل برنامه به Compose، تمبندی XML خود را حذف کنید.
شما میتوانید از ابزار Material Theme Builder برای انتقال رنگها استفاده کنید.
وقتی مهاجرت از XML به Compose را شروع میکنید، قالببندی را به قالببندی Material 3 Compose منتقل کنید.
واژهنامه
| مدت | تعریف |
|---|---|
MaterialTheme | تابع قابل ترکیب (composable) که تمبندی (رنگها، تایپوگرافی، شکلها) را برای کامپوننتهای رابط کاربری ترکیبشده فراهم میکند. |
Shape | یک شیء Compose که برای تعریف شکلهای کامپوننت سفارشی برای MaterialTheme استفاده میشود. |
Typography | یک شیء Compose که برای تعریف سبکهای متن سفارشی (خانوادههای فونت، اندازهها، وزنها) برای یک MaterialTheme استفاده میشود. |
Color | یک شیء Compose که برای تعریف طرحهای رنگی سفارشی برای MaterialTheme استفاده میشود. |
| قالب XML | سیستم قالببندی اندروید که در فایلهای XML تعریف شده و توسط سیستم View استفاده میشود. |
محدودیتها
قبل از مهاجرت، از محدودیتهای زیر آگاه باشید:
- این راهنما فقط بر مهاجرت به Material 3 تمرکز دارد. برای مهاجرت از سیستمهای طراحی جایگزین، به Material 2 یا سیستمهای طراحی سفارشی در Compose مراجعه کنید.
- هدف نهایی، مهاجرت کامل به Compose است که امکان حذف تمبندی XML را فراهم میکند. این راهنما نحوه مهاجرت را توضیح میدهد، اما نحوه حذف نهایی تمبندی XML را توضیح نمیدهد.
مرحله ۱: ارزیابی سیستم طراحی
مشخص کنید که از کدام سیستم طراحی در پروژه XML View استفاده شده است. مسیر مهاجرت و مراحل لازم برای مهاجرت سیستم طراحی موجود به Material 3 در Compose را تجزیه و تحلیل کنید.
مرحله ۲: شناسایی فایلهای منبع قالب
در XML شما ?attr/colorPrimary مینویسید. در Compose، با MaterialTheme.* به مقادیر قالب دسترسی پیدا میکنید:
تمام منابع و فایلهای XML لازم برای قالببندی را شناسایی و مکانیابی کنید: طرحها و توصیفکنندههای رنگی روشن و تیره، قالبها، شکلها، ابعاد، تایپوگرافی، سبکها و سایر فایلهای مرتبط.
منابعی مانند رشتهها میتوانند به همان صورت که هستند دوباره استفاده شوند و نیازی به انتقال ندارند.
مرحله ۳: انتقال رنگها
اصل کلیدی: XML از رنگهای هگز نامگذاری شده استفاده میکند. ماده ۳ از نقشهای معنایی (مثلاً primary ، onPrimary ، surface ) استفاده میکند. نامگذاری رنگها را بر اساس هگز آنها متوقف کنید؛ آنها را بر اساس نقششان نامگذاری کنید.
مثالها:
| نام رنگ XML | نقش ماده ۳ |
|---|---|
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 منتقل کنید.
مرحله ۴: انتقال شکلها و تایپوگرافی سفارشی
اگر برنامه شما از اشکال سفارشی استفاده میکند:
- در کد Compose خود، یک شیء
Shapeتعریف کنید تا تعاریف شکل XML شما را تکرار کند. این شیء
Shapeرا بهMaterialThemeخود ارائه دهید.برای جزئیات بیشتر، به شکلها مراجعه کنید.
- در کد Compose خود، یک شیء
اگر برنامه شما از تایپوگرافی سفارشی استفاده میکند:
- در کد Compose خود، یک شیء
Typographyدر کد Compose خود تعریف کنید تا سبکهای متن XML و تعاریف فونت شما را تکرار کند. این شیء
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 |
مرحله ۵: انتقال استایلها (styles.xml)
سیستم استایلهای XML (styles.xml) استایلها و ظاهر موارد زیر را تعریف میکند: ۱. ویجتها، کامپوننتها، تمها برای پنجرهها و پنجرههای محاورهای ۲. تایپوگرافی ۳. تمها و پوششها ۴. شکلها
نماها و کامپوننتهای XML چندین ویژگی را برای ایجاد یک سبک ترکیب میکنند. آنها سبکهای خود را از styles.xml به دو روش مختلف تنظیم میکنند: ۱. تنظیم "style="@style/... به طور مستقیم و صریح در نمای XML ۲. تنظیم سبک به طور غیرمستقیم و ضمنی برای یک کامپوننت به عنوان بخشی از یک تم بزرگتر (theme.xml)
استایلها معادل مستقیمی در Compose ندارند - در عوض استایلها به صورت زیر ارسال میشوند: پارامترهایی به composableها، تعریف شده در AppTheme، یا با ایجاد تغییرات لایهای و قابل استفاده مجدد composable با استایل تعریف شده.
توابع @Composable جداگانهای را با نامهای متناسب با سبک و کامپوننت پایه ارائه دهید تا تفاوت در سبکبندی و موارد استفاده برای آن کامپوننتها را نشان دهند.
- الگو: اگر یک عنصر XML از یک سبک سفارشی استفاده میکند (مثلاً
style="@style/MyPrimaryButton")، سعی نکنید آن سبک را به صورت درونخطی تکرار کنید. در عوض، پیشنهاد دهید یک composable خاص ایجاد شود. - مثال:
- XML:
<Button style="@style/MyPrimaryButton" ... /> - نوشتن:
MyPrimaryButton(onClick = { ... })
- XML:
- گروههای ویژگی مشترک: اگر یک استایل، اصلاحکنندههای مشترکی (مانند padding + height) را تنظیم میکند، آنها را در یک ویژگی افزونهی خوانا یا یک متغیر اصلاحکنندهی مشترک استخراج کنید.
مثالهای رایج
| XML | نوشتن |
|---|---|
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 |
مرحله ۶: اعتبارسنجی انتقال قالب
همیشه از مقادیر تم موجود در تم XML اصلی به عنوان منبع حقیقت برای تم متریال جدید در Compose استفاده کنید. هرگز در طول مهاجرت مقادیر تم جدیدی اختراع نکنید تا ثبات برند حفظ شود و از پسرفت بصری جلوگیری شود.
تأیید کنید که تمام مقادیر جدید تم Compose با مقادیر XML موجود مطابقت دارند. هیچ مقدار منتقل شدهای را hardcode نکنید.