منابع در «نوشتن»

Jetpack Compose می‌تواند به منابع تعریف‌شده در پروژه Android شما دسترسی داشته باشد. این سند برخی‌از میاناهای برنامه‌سازی کاربردی را که 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)
)

‫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 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
    )
)

هنگام استفاده از روش 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)
)

رنگ‌ها

اگر Compose را به‌صورت افزایشی در برنامه‌تان به‌کار می‌برید، از colorResource API برای دریافت رنگ‌ها از فایل 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 استفاده کنید. نیازی نیست نوع drawable را بدانید، کافی است از 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 API برای بار کردن 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:2026.09.00')
  implementation composeBom

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

قلم

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

هر قلم را بااستفاده از Font API بار کنید و 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()
    }
}

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

در سند Theming in Compose درباره نویسه‌نگاری بیشتر بدانید