انتقال زمینه‌های XML به Material 3 در Compose

وقتی Compose را در برنامه موجودی معرفی می‌کنید، باید زمینه‌های XML ‏Material خود را انتقال دهید تا از MaterialTheme برای مؤلفه‌های Compose استفاده کنید. این یعنی زمینه‌سازی برنامه‌تان دو منبع حقیقت خواهد داشت: زمینه مبتنی بر 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 تعریف شده است و توسط سیستم «نما» استفاده می‌شود.

محدودیت‌ها

قبل‌از انتقال، از محدودیت‌های زیر آگاه باشید:

• این راهنما فقط روی انتقال به Material 3 تمرکز دارد. برای انتقال از سیستم‌های طراحی جایگزین، به Material 2 یا سیستم‌های طراحی سفارشی در Compose مراجعه کنید.
• هدف نهایی انتقال کامل به Compose است که امکان حذف زمینه‌سازی XML را فراهم می‌کند. این راهنما نحوه انتقال را توضیح می‌دهد، اما نحوه حذف نهایی زمینه‌سازی XML را توضیح نمی‌دهد.

مرحله ۱: ارزیابی سیستم طراحی

تشخیص اینکه کدام سیستم طراحی در پروژه XML View استفاده شده است. مسیر انتقال و مراحل لازم برای انتقال سیستم طراحی موجود به Material 3 در Compose را تجزیه‌وتحلیل کنید.

مرحله ۲: شناسایی فایل‌های منبع زمینه

در XML، ?attr/colorPrimary را می‌نویسید. در Compose، با MaterialTheme.* به مقادیر زمینه دسترسی پیدا می‌کنید:

همه منابع و فایل‌های XML لازم برای زمینه‌سازی را شناسایی و مکان‌یابی کنید: آرایش رنگ‌ها و شناساننده‌های روشن و تیره، زمینه‌ها، شکل‌ها، ابعاد، نویسه‌نگاری، سبک‌ها، و دیگر فایل‌های مربوطه.

منابعی مانند رشته‌ها می‌توانند همان‌طور که هستند دوباره استفاده شوند و نیازی به انتقال ندارند.

مرحله ۳: انتقال رنگ‌ها

اصل کلیدی: XML از رنگ‌های hex نام‌گذاری‌شده استفاده می‌کند. ‫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 منتقل کنید.

توجه: نام‌گذاری Material 3 با نام‌گذاری رنگ Material 2 متفاوت است.

مرحله ۴: انتقال شکل‌ها و حروف‌چینی سفارشی

• اگر برنامه‌تان از شکل‌های سفارشی استفاده می‌کند:

  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

مرحله ۵: انتقال سبک‌ها (styles.xml)

سیستم سبک‌های XML‏ (styles.xml) سبک‌ها و ظاهر موارد زیر را تعریف می‌کند:

1. ابزاره‌ها، مؤلفه‌ها، زمینه‌ها برای پنجره‌ها و کادرهای گفتگو
2. نویسه‌نگاری
3. طرح‌های زمینه و هم‌پوشانی‌ها
4. شکل‌ها

«نماهای XML» و مؤلفه‌ها چندین مشخصه را برای ایجاد سبک ترکیب می‌کنند. آن‌ها سبک‌هایشان را از styles.xml به دو روش مختلف تنظیم می‌کنند:

1. تنظیم «style="@style/...» به‌طور مستقیم و صریح در XML View
2. تنظیم سبک به‌طور غیرمستقیم و ضمنی برای یک مؤلفه به‌عنوان بخشی از یک «زمینه» بزرگ‌تر (theme.xml)

سبک‌ها معادل مستقیمی در Compose ندارند - درعوض سبک‌ها به‌عنوان: پارامترها یا اصلاح‌کننده‌ها به composableها، بااستفاده از Styles API جدید و آزمایشی تعریف‌شده در AppTheme، یا با ایجاد انواع composable لایه‌بندی‌شده و قابل‌استفاده مجدد با سبک تعریف‌شده ارسال می‌شوند.

توابع ‎ @Composable جداگانه‌ای ارائه دهید که براساس سبک و مؤلفه پایه نام‌گذاری شده‌اند تا تفاوت در سبک و موارد استفاده برای آن مؤلفه‌ها را نشان دهند.

• الگو: اگر عنصر XML از سبک سفارشی استفاده می‌کند (مثلاً style="@style/MyPrimaryButton")، سعی نکنید سبک را به‌صورت درون‌خطی تکرار کنید. درعوض، پیشنهاد دهید که یک ترکیب‌پذیر خاص ایجاد شود.
• مثال:
  • 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

مرحله ۶: اعتبارسنجی انتقال زمینه

همیشه از مقادیر زمینه موجود از زمینه XML اصلی به‌عنوان منبع حقیقت برای «زمینه Material» جدید در Compose استفاده کنید. برای حفظ ثبات نمانام و جلوگیری از پس‌رفت‌های دیداری، هرگز مقادیر زمینه جدیدی را درطول انتقال ایجاد نکنید.

تأیید کنید که همه مقادیر جدید زمینه Compose با مقادیر XML موجود مطابقت داشته باشد. هیچ مقدار انتقال‌یافته‌ای را کدگذاری سخت نکنید.