منابع در Compose

Jetpack Compose می تواند به منابع تعریف شده در پروژه اندروید شما دسترسی داشته باشد. این سند برخی از API های Compose را برای انجام این کار توضیح می دهد.

منابع فایل‌های اضافی و محتوای ثابتی هستند که کد شما از آنها استفاده می‌کند، مانند بیت مپ، تعاریف طرح‌بندی، رشته‌های رابط کاربری، دستورالعمل‌های انیمیشن و غیره. اگر با منابع در Android آشنایی ندارید، راهنمای نمای کلی منابع برنامه را بررسی کنید.

رشته ها

رایج ترین نوع منابع رشته های شما هستند. از stringResource API برای بازیابی رشته ای که به صورت ایستا در منابع 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 API برای بارگیری یک جمع با مقدار مشخصی استفاده کنید.

// 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 API برای دریافت ابعاد از یک فایل 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 API برای دریافت رنگ ها از یک فایل 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 تعریف شوند که می‌توان از قابلیت‌های composable شما مانند MaterialTheme.colors.primary به آن دسترسی داشت. در مورد این در اسناد طراحی در Compose اطلاعات بیشتری کسب کنید.

دارایی های برداری و منابع تصویر

از painterResource API برای بارگیری قالب‌های ترسیمی برداری یا قالب‌های دارایی شطرنجی شده مانند PNG استفاده کنید. شما نیازی به دانستن نوع ترسیم ندارید، به سادگی painterResource در Image composables یا paint modifier استفاده کنید.

// 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 API برای بارگذاری یک XML قابل ترسیم بردار متحرک استفاده کنید. متد یک نمونه AnimatedImageVector را برمی گرداند. برای نمایش تصویر متحرک، از متد rememberAnimatedVectorPainter برای ایجاد یک Painter استفاده کنید که می تواند در Image و Icon composable استفاده شود. پارامتر بولی 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 Icons در Compose است. پنج تم نماد متمایز وجود دارد: پر شده ، مشخص شده ، گرد ، دو رنگ و شارپ . هر تم حاوی نمادهای یکسان است، اما با سبک بصری متمایز. شما معمولاً باید یک موضوع را انتخاب کنید و از آن در سراسر برنامه خود برای ثبات استفاده کنید.

برای ترسیم یک نماد، می توانید از Icon composable استفاده کنید که رنگ را اعمال می کند و اندازه طرح مطابق با نماد را ارائه می دهد.

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.09.03')
  implementation composeBom

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

توجه: آیکون ها همان نام های تعریف شده توسط Material را حفظ می کنند، اما نام snake_case آنها به PascalCase تبدیل شده است. به عنوان مثال، add_alarm تبدیل به AddAlarm می شود. نمادهایی که با یک عدد شروع می شوند، مانند 360، با پیشوند _ و تبدیل به _360 می شوند.

هشدار: material-icons-extended یک کتابخانه بزرگ است و می تواند بر اندازه APK شما تأثیر بگذارد. به همین دلیل، استفاده از R8/Proguard را در ساخت‌های تولیدی برای حذف منابعی که استفاده نمی‌شوند، در نظر بگیرید. علاوه بر این، به دلیل اندازه بزرگ، زمان ساخت پروژه شما و زمان بارگذاری پیش نمایش اندروید استودیو می تواند در طول توسعه افزایش یابد. از سوی دیگر، material-icons-extended به شما امکان می‌دهد با دسترسی سریع به آخرین نسخه‌های همه نمادها، با سرعت بیشتری تکرار کنید. همچنین می‌توانید از این کتابخانه برای کپی کردن کد منبع نماد استفاده کنید تا یک نسخه ثابت در برنامه خود داشته باشید، یا در عوض، نمادها را با استفاده از ویژگی Import vector asset Android Studio وارد کنید.

فونت ها

برای استفاده از فونت‌ها در Compose، فایل‌های فونت را مستقیماً در APK خود با قرار دادن آنها در پوشه res/font دانلود و دسته‌بندی کنید.

هر فونت را با استفاده از Font API بارگیری کنید و با آنها یک FontFamily ایجاد کنید که می توانید از آن در نمونه های TextStyle برای ایجاد Typography خود استفاده کنید. کد زیر از نمونه Crane compose و فایل 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

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

در مستندات Theming in Compose درباره تایپوگرافی بیشتر بیاموزید

{% کلمه به کلمه %} {% آخر کلمه %}