الموارد في 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)
)

تعمل دالة 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)
)

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

استخدِم واجهة برمجة التطبيقات 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
    )
)

عند استخدام طريقة 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)
)

الألوان

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

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

// In your Compose code
HorizontalDivider(color = colorResource(R.color.purple_200))

تعمل السمة 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
)

يفكّ 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
)

الرموز

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

لرسم رمز، يمكنك استخدام الدالة المركّبة Icon التي تطبّق تدرجًا لونيًا وتوفّر حجم تنسيق يتطابق مع الرمز.

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

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

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

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

الخطوط

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

حمِّل كل خط باستخدام واجهة برمجة التطبيقات Font وأنشئ FontFamily باستخدامها يمكنك استخدامها في مثيلات TextStyle لإنشاء Typography الخاصة بك. في ما يلي رمز برمجي مأخوذ من نموذج Compose في 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()
    }
}

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

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