משאבים בכתיבה

ל-Jetpack Compose יש גישה למשאבים שהוגדרו בפרויקט Android. במסמך הזה מוסבר על חלק מממשקי ה-API ש-Compose מציע לצורך כך.

משאבים הם הקבצים הנוספים והתוכן הסטטי שבהם הקוד שלכם משתמש, כמו קובצי bitmap, הגדרות פריסה, מחרוזות של ממשק משתמש, הוראות אנימציה ועוד. אם אתם לא יודעים איך משתמשים במשאבים ב-Android, כדאי לעיין במדריך הכללי בנושא משאבים של אפליקציות.

מיתרים

הסוג הנפוץ ביותר של משאבים הוא מחרוזות. משתמשים ב-API 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

צורות רבות של מחרוזת (ניסיוני)

משתמשים ב-API של 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, פרמטר הספירה הראשון בוחר את המחרוזת המתאימה לרבים ופרמטר הספירה השני מוכנס ל-placeholder‏ %1$d. אם מחרוזות הרבים לא כוללות עיצוב של מחרוזות, אין צורך להעביר את הפרמטר השלישי אל pluralStringResource.

למידע נוסף על צורות רבות, אפשר לעיין במסמכי התיעוד בנושא מחרוזות כמות.

מידות

באופן דומה, אפשר להשתמש ב-API 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 באפליקציה באופן מצטבר, תוכלו להשתמש ב-API ‏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 פועלת כמצופה עם צבעים סטטיים, אבל היא משטחת משאבים של רשימות מצבי צבע.

נכסי וקטורים ומשאבי תמונות

אפשר להשתמש ב-painterResource API כדי לטעון נכסים גרפיים וקטוריים או נכסים בפורמטים רסטריים כמו PNG. אין צורך לדעת מהו הסוג של ה-drawable, פשוט משתמשים ב-painterResource ב-composables של 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 מפענח ומנתח את תוכן המשאב בשרשור הראשי.

אנימציות של פריטים גרפיים וקטורים שניתן לשרטוט

משתמשים ב-API ‏AnimatedImageVector.animatedVectorResource כדי לטעון קובץ XML של וקטור מונפש שניתן לציור. השיטה מחזירה מופע של AnimatedImageVector. כדי להציג את התמונה האנימציה, משתמשים ב-method‏ rememberAnimatedVectorPainter כדי ליצור Painter שאפשר להשתמש בו ב-composables של 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 Icons ב-Compose. יש חמישה עיצובים שונים של סמלים: מלאים, מוארכים, מעוגלים, דו-גווניים וחדים. כל נושא מכיל את אותם הסמלים, אבל בסגנון חזותי ייחודי. בדרך כלל כדאי לבחור עיצוב אחד ולהשתמש בו בכל האפליקציה כדי לשמור על עקביות.

כדי לצייר סמל, אפשר להשתמש ב-composable‏ 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'
}

גופנים

כדי להשתמש בגופנים ב-Compose, מורידים את קובצי הגופנים ומקבצים אותם ישירות בחבילות ה-APK, על ידי הוספה שלהם לתיקייה res/font.

אפשר לטעון כל גופן באמצעות ה-API Font וליצור ממנו FontFamily שאפשר להשתמש בו במכונות TextStyle כדי ליצור Typography משלכם. הקוד הבא נלקח מדוגמת ה-compose של 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

במאמר גופנים שניתן להורדה מוסבר איך משתמשים בגופנים שניתן להורדה ב'כתיבה'.

מידע נוסף על טיפוגרפיה זמין במאמר חומר העזר בנושא עיצוב ב-Compose