الموارد في 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 على النحو المتوقّع مع الألوان الثابتة، ولكنه يُسطِّح موارد قائمة حالة اللون.

تحذير: يُفضّل استخدام ألوان من المظهر بدلاً من الألوان المضمّنة في الرمز البرمجي. على الرغم من أنّه من الممكن الوصول إلى الألوان باستخدام الدالة colorResource، ننصح بتحديد ألوان تطبيقك في MaterialTheme يمكن الوصول إليها من العناصر القابلة للتجميع مثل MaterialTheme.colors.primary. يمكنك الاطّلاع على مزيد من المعلومات حول هذا الموضوع في مستندات أنظمة التصميم في Compose.

مواد عرض المتجهات ومراجع الصور

استخدِم واجهة برمجة التطبيقات 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 يفكّ ترميز محتوى المرجع ويحلّله في السلسلة الأساسية.

ملاحظة: على عكس Context.getDrawable، يمكن لسمة painterResource تحميل نوعَي منصّة Drawable BitmapDrawable و VectorDrawable فقط.

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

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

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

ملاحظة: تحتفظ الرموز بالأسماء نفسها التي حدّدتها Material، ولكن مع تحويل اسم snake_case إلى PascalCase. على سبيل المثال، تصبح add_alarm AddAlarm. يتمّ وضع البادئة _ أمام الرموز التي تبدأ برقم، مثل 360، ليصبح _360.

تحذير: material-icons-extended هي مكتبة كبيرة ويمكن أن تؤثّر في حجم حزمة APK. لهذا السبب، ننصحك باستخدام R8/Proguard في عمليات إنشاء الإصدارات العلنية لإزالة الموارد غير المستخدَمة. بالإضافة إلى ذلك، بسبب الحجم الكبير، قد يزداد وقت إنشاء مشروعك ووقت تحميل معاينات "استوديو Android" أثناء التطوير. من ناحية أخرى، يتيح لك material-icons-extended إجراء عمليات تكرار بشكل أسرع من خلال الوصول السريع إلى أحدث إصدارات من جميع الرموز. يمكنك أيضًا استخدام هذه المكتبة لنسخ رمز المصدر للرمز للحصول على نسخة ثابتة في تطبيقك، أو استيراد الرموز باستخدام ميزة "استيراد مادة عرض رسومات متجهية" في "استوديو Android".

خطوط

لاستخدام الخطوط في ميزة "الإنشاء"، عليك تنزيل حِزم ملفات الخطوط وتجميعها مباشرةً في ملفاتك 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

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

اطّلِع على مزيد من المعلومات حول تنسيقات النصوص في مستندات تخصيص المظهر في ميزة "الإنشاء".