الموارد في 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
Divider(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 الذي يمثّل نقطة الدخول لاستخدام رموز Material في 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:2024.10.01')
  implementation composeBom

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

خطوط

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

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

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