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

‫Jetpack Compose می‌تواند به منابع تعریف‌شده در پروژه Android شما دسترسی داشته باشد. این سند برخی‌از میاناهای برنامه‌سازی کاربردی را که «نوشتن» برای انجام این کار ارائه می‌دهد توضیح می‌دهد.

منابع فایل‌های اضافی و محتوای ثابتی هستند که کد شما از آن‌ها استفاده می‌کند، مثل نقشه‌های بیتی، تعریف‌های چیدمان، رشته‌های میانای کاربر، دستورالعمل‌های پویانمایی، و غیره. اگر با منابع در 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 API برای بار کردن دارایی‌های برداری یا قالب‌های دارایی شطرنجی‌شده مثل 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 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-icons-extended را به فایل build.gradle اضافه کنید.

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

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

قلم

برای استفاده از قلم‌ها در «نوشتن»، فایل‌های قلم را مستقیماً در فایل‌های 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()
    }
}

برای استفاده از قلم‌های قابل‌بارگیری در «نوشتن»، صفحه قلم‌های قابل‌بارگیری را ببینید.

در سند «زمینه‌سازی در Compose» درباره نویسه‌نگاری بیشتر بدانید