ทรัพยากรใน Compose

Jetpack Compose สามารถเข้าถึงทรัพยากรที่กําหนดไว้ในโปรเจ็กต์ Android เอกสารนี้อธิบาย 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 คุณต้องส่งจํานวน 2 ครั้งหากสตริงมีการจัดรูปแบบสตริงด้วยตัวเลข ตัวอย่างเช่น สําหรับสตริง %1$d minutes พารามิเตอร์การนับรายการแรกจะเลือกสตริงพหูพจน์ที่เหมาะสม และระบบจะแทรกพารามิเตอร์การนับรายการที่ 2 ลงในตัวยึดตําแหน่ง %1$d หากสตริงพหูพจน์ไม่มีการจัดรูปแบบสตริง คุณไม่จําเป็นต้องส่งพารามิเตอร์ที่ 3 ไปยัง 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 ทํางานตามที่คาดไว้กับสีแบบคงที่ แต่จะยุบทรัพยากรรายการสถานะสี

ชิ้นงานเวกเตอร์และแหล่งข้อมูลรูปภาพ

ใช้ 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
)
ResourcesSnippets.kt

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
)
ResourcesSnippets.kt

ไอคอน

Jetpack Compose มาพร้อมกับออบเจ็กต์ Icons ซึ่งเป็นจุดเริ่มต้นในการใช้ไอคอน Material ใน Compose ธีมไอคอนมี 5 ธีม ได้แก่ แบบเต็ม แบบมีเส้นขอบ แบบโค้งมน แบบ 2 สี และ แบบคมชัด ธีมแต่ละธีมมีไอคอนเดียวกัน แต่มีสไตล์ภาพที่แตกต่างกัน โดยปกติแล้ว คุณควรเลือกธีมเดียวและใช้กับแอปพลิเคชันทั้งหมดเพื่อความสอดคล้อง

หากต้องการวาดไอคอน คุณสามารถใช้คอมโพสิเบิล Icon ซึ่งจะใช้สีและกำหนดขนาดเลย์เอาต์ให้ตรงกับไอคอน

Icon(Icons.Rounded.Menu, contentDescription = "Localized description")
ResourcesSnippets.kt

ไอคอนที่ใช้กันมากที่สุดบางรายการมีให้ใช้งานเป็นส่วนหนึ่งของข้อกำหนดของ androidx.compose.material หากต้องการใช้ไอคอน Material อื่นๆ ให้เพิ่มmaterial-icons-extended Dependency ลงในไฟล์ build.gradle

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

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

แบบอักษร

หากต้องการใช้แบบอักษรในเครื่องมือเขียน ให้ดาวน์โหลดและรวมไฟล์แบบอักษรใน APK โดยตรงโดยวางไว้ในโฟลเดอร์ res/font

โหลดแบบอักษรแต่ละแบบโดยใช้ 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()
    }
}
ResourcesSnippets.kt

หากต้องการใช้แบบอักษรที่ดาวน์โหลดได้ใน Compose โปรดดูหน้าแบบอักษรที่ดาวน์โหลดได้

ดูข้อมูลเพิ่มเติมเกี่ยวกับการพิมพ์ในเอกสารประกอบธีมใน Compose