الموارد في Compose

يمكن أن يصل Jetpack Compose إلى الموارد المحدّدة في مشروع Android. يوضّح هذا المستند بعض واجهات برمجة التطبيقات التي يوفّرها Compose لإجراء ذلك.

الموارد هي الملفات الإضافية والمحتوى الثابت الذي يستخدمه الرمز البرمجي، مثل الصور النقطية وتعريفات التصميم وسلاسل واجهة المستخدم وتعليمات الرسوم المتحركة وغير ذلك. إذا لم تكن معتادًا على الموارد في Android، يمكنك الاطّلاع على دليل نظرة عامة على موارد التطبيق.

آلات وترية

النوع الأكثر شيوعًا من الموارد هو السلاسل. استخدِم واجهة برمجة التطبيقات stringResource لاسترداد سلسلة محدّدة بشكل ثابت في موارد XML.

// In the res/values/strings.xml file
// <string name="compose">Jetpack Compose</string>

// In your Compose code
Text(
    text = stringResource(R.string.compose)
)
ResourcesSnippets.kt

يعمل stringResource أيضًا مع التنسيق الموضعي.

// In the res/values/strings.xml file
// <string name="congratulate">Happy %1$s %2$d</string>

// In your Compose code
Text(
    text = stringResource(R.string.congratulate, "New Year", 2021)
)
ResourcesSnippets.kt

صيغ الجمع للسلاسل (ميزة تجريبية)

استخدِم واجهة برمجة التطبيقات pluralStringResource لتحميل صيغة الجمع بكمية معيّنة.

// In the res/strings.xml file
// <plurals name="runtime_format">
//    <item quantity="one">%1$d minute</item>
//    <item quantity="other">%1$d minutes</item>
// </plurals>

// In your Compose code
Text(
    text = pluralStringResource(
        R.plurals.runtime_format,
        quantity,
        quantity
    )
)
ResourcesSnippets.kt

عند استخدام طريقة pluralStringResource، عليك تمرير العدد مرتين إذا كانت السلسلة تتضمّن تنسيق سلسلة مع رقم. على سبيل المثال، بالنسبة إلى السلسلة %1$d minutes، يختار مَعلمة العدد الأولى سلسلة الجمع المناسبة، ويتم إدراج مَعلمة العدد الثانية في العنصر النائب %1$d. إذا كانت سلاسل صيغة الجمع لا تتضمّن تنسيق السلسلة، لن تحتاج إلى تمرير المَعلمة الثالثة إلى pluralStringResource.

لمزيد من المعلومات حول صيغ الجمع، يمكنك الاطّلاع على مستندات سلاسل الكمية.

الأبعاد

وبالمثل، استخدِم واجهة برمجة التطبيقات dimensionResource للحصول على السمات من ملف XML خاص بمورد.

// In the res/values/dimens.xml file
// <dimen name="padding_small">8dp</dimen>

// In your Compose code
val smallPadding = dimensionResource(R.dimen.padding_small)
Text(
    text = "...",
    modifier = Modifier.padding(smallPadding)
)
ResourcesSnippets.kt

الألوان

إذا كنت تستخدم Compose بشكل تدريجي في تطبيقك، استخدِم واجهة برمجة التطبيقات colorResource للحصول على الألوان من ملف XML للموارد.

// In the res/colors.xml file
// <color name="purple_200">#FFBB86FC</color>

// In your Compose code
Divider(color = colorResource(R.color.purple_200))
ResourcesSnippets.kt

تعمل السمة colorResource على النحو المتوقّع مع الألوان الثابتة، ولكنها تعمل على تسوية موارد قائمة حالات الألوان.

مواد عرض متّجهة وموارد صور

استخدِم واجهة برمجة التطبيقات painterResource لتحميل الرسومات المتجهة أو تنسيقات الأصول النقطية، مثل ملفات PNG. لست بحاجة إلى معرفة نوع العنصر القابل للرسم، ما عليك سوى استخدام painterResource في دوال Image التركيبية أو معدِّلات paint.

// Files in res/drawable folders. For example:
// - res/drawable-nodpi/ic_logo.xml
// - res/drawable-xxhdpi/ic_logo.png

// In your Compose code
Icon(
    painter = painterResource(id = R.drawable.ic_logo),
    contentDescription = null // decorative element
)
ResourcesSnippets.kt

تعمل painterResource على فك ترميز محتوى المورد وتحليله في سلسلة التعليمات الرئيسية.

متّجهات قابلة للرسم متحركة

استخدِم واجهة برمجة التطبيقات AnimatedImageVector.animatedVectorResource لتحميل ملف XML لرسومات متجهة متحركة. تعرض الطريقة مثيلاً من AnimatedImageVector. لعرض الصورة المتحركة، استخدِم طريقة rememberAnimatedVectorPainter لإنشاء Painter يمكن استخدامه في عناصر Image وIcon القابلة للإنشاء. تشير المَعلمة المنطقية atEnd للطريقة rememberAnimatedVectorPainter إلى ما إذا كان يجب رسم الصورة في نهاية جميع الصور المتحركة. إذا تم استخدامها مع حالة قابلة للتغيير، تؤدي التغييرات في هذه القيمة إلى تشغيل الرسوم المتحركة المقابلة.

// Files in res/drawable folders. For example:
// - res/drawable/ic_hourglass_animated.xml

// In your Compose code
val image =
    AnimatedImageVector.animatedVectorResource(R.drawable.ic_hourglass_animated)
val atEnd by remember { mutableStateOf(false) }
Icon(
    painter = rememberAnimatedVectorPainter(image, atEnd),
    contentDescription = null // decorative element
)
ResourcesSnippets.kt

الرموز

تتضمّن Jetpack Compose العنصر Icons الذي يمثّل نقطة الدخول لاستخدام رموز Material في Compose. تتوفّر خمسة مظاهر مختلفة للرموز: ممتلئ ومخطّط ومستدير وثنائي اللون وحاد. يحتوي كل مظهر على الرموز نفسها، ولكن بأسلوب مرئي مميز. ننصحك عادةً باختيار مظهر واحد واستخدامه في جميع أنحاء تطبيقك للحفاظ على الاتساق.

لرسم رمز، يمكنك استخدام العنصر Icon القابل للإنشاء الذي يطبّق اللون ويوفّر حجم التنسيق المطابق للرمز.

Icon(Icons.Rounded.Menu, contentDescription = "Localized description")
ResourcesSnippets.kt

تتوفّر بعض الأيقونات الأكثر استخدامًا كجزء من حزمة androidx.compose.material. لاستخدام أي من رموز Material الأخرى، أضِف التبعية material-icons-extended إلى ملف build.gradle.

dependencies {
  def composeBom = platform('androidx.compose:compose-bom:2025.05.00')
  implementation composeBom

  implementation 'androidx.compose.material:material-icons-extended'
}

الخطوط

لاستخدام الخطوط في Compose، نزِّل ملفات الخطوط وضمِّنها مباشرةً في حِزم APK من خلال وضعها في المجلد res/font.

حمِّل كل خط باستخدام واجهة برمجة التطبيقات Font وأنشئ FontFamily باستخدامها، ويمكنك استخدامها في مثيلات TextStyle لإنشاء Typography خاص بك. في ما يلي رمز مأخوذ من نموذج Crane البرمجي الخاص بإنشاء التطبيقات وملف Typography.kt.

// Define and load the fonts of the app
private val light = Font(R.font.raleway_light, FontWeight.W300)
private val regular = Font(R.font.raleway_regular, FontWeight.W400)
private val medium = Font(R.font.raleway_medium, FontWeight.W500)
private val semibold = Font(R.font.raleway_semibold, FontWeight.W600)

// Create a font family to use in TextStyles
private val craneFontFamily = FontFamily(light, regular, medium, semibold)

// Use the font family to define a custom typography
val craneTypography = Typography(
    titleLarge = TextStyle(
        fontFamily = craneFontFamily
    ) /* ... */
)

// Pass the typography to a MaterialTheme that will create a theme using
// that typography in the part of the UI hierarchy where this theme is used
@Composable
fun CraneTheme(content: @Composable () -> Unit) {
    MaterialTheme(typography = craneTypography) {
        content()
    }
}
ResourcesSnippets.kt

لمعرفة كيفية استخدام الخطوط القابلة للتنزيل في Compose، راجِع صفحة الخطوط القابلة للتنزيل.

مزيد من المعلومات حول أسلوب الخط في مستندات تصميم المظاهر في Compose