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

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

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

מיתרים

סוג המשאב הנפוץ ביותר הוא String (מחרוזות). משתמשים ב-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 מפענח ומנתח את תוכן המשאב ב-thread הראשי.

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

משתמשים ב-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

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

אפשר לקרוא מידע נוסף על טיפוגרפיה במסמכי העזרה בנושא עיצוב פנים