Использование мультиплатформенных ресурсов в приложении

Изображения

Вы можете обращаться к ресурсам Drawable как к обычным изображениям, растровым изображениям или векторной графике XML. Изображения SVG поддерживаются на всех платформах, кроме Android.

• Чтобы обращаться к ресурсам Drawable как к изображениям Painter, используйте функцию painterResource():

  @Composable
  fun painterResource(resource: DrawableResource): Painter {...}
  

  Функция painterResource() принимает путь к ресурсу и возвращает значение Painter. На всех целевых платформах, кроме веб-платформы, функция работает синхронно. На веб-платформе она возвращает пустой Painter при первой рекомпозиции; в последующих рекомпозициях он заменяется загруженным изображением.

  • painterResource() загружает либо BitmapPainter для растровых форматов изображений, например .png, .jpg, .bmp, .webp, либо VectorPainter для формата векторных Drawable Android XML.

  • Векторные Drawable XML имеют тот же формат, что и Android, за исключением того, что они не поддерживают внешние ссылки на ресурсы Android.

• Чтобы обращаться к ресурсам Drawable как к растровым изображениям ImageBitmap, используйте функцию imageResource():

  @Composable
  fun imageResource(resource: DrawableResource): ImageBitmap {...}
  

• Чтобы обращаться к ресурсам Drawable как к векторной графике Android XML ImageVector, используйте функцию vectorResource():

  @Composable
  fun vectorResource(resource: DrawableResource): ImageVector {...}
  

Вот пример доступа к изображениям из кода Compose Multiplatform:

Image(
    painter = painterResource(Res.drawable.my_image),
    contentDescription = null
)

val myImageRaster = imageResource(Res.drawable.my_image_raster)
val myImageVectorPainter = rememberVectorPainter(vectorResource(Res.drawable.my_image_vector))

Canvas(modifier = Modifier.fillMaxSize()) {
    // Inside the lambda, `this` is an instance of `DrawScope`, which provides `drawImage()` and `translate()`
    drawImage(image = myImageRaster, topLeft = Offset(20f, 20f))
    translate(left = 20f, top = myImageRaster.height + 40f) {
        // The `Painter.draw()` function uses both the `DrawScope` and `Painter` as receivers
        with(myImageVectorPainter) {
            draw(Size(200f, 200f))
        }
    }
}

Значки

Вы можете использовать векторные значки Android XML из библиотеки Material Symbols:

1. Откройте галерею значков Google Fonts, выберите значок, перейдите на вкладку Android и нажмите Download.

2. Добавьте загруженный файл значка XML в каталог drawable мультиплатформенных ресурсов.

3. Откройте файл значка XML и задайте для android:fillColor значение #000000. Удалите все остальные атрибуты Android, специфичные для настройки цвета, например android:tint.

   До:

   <vector xmlns:android="http://schemas.android.com/apk/res/android"
        android:width="24dp"
        android:height="24dp"
        android:viewportWidth="960"
        android:viewportHeight="960"
        android:tint="?attr/colorControlNormal">
        <path
            android:fillColor="@android:color/white"
            android:pathData="..."/>
    </vector>
   

   После:

   <vector xmlns:android="http://schemas.android.com/apk/res/android"
        android:width="24dp"
        android:height="24dp"
        android:viewportWidth="960"
        android:viewportHeight="960">
        <path
            android:fillColor="#000000"
            android:pathData="..."/>
   </vector>
   

4. Соберите проект, чтобы сгенерировать средства доступа к ресурсам, или позвольте плагину Kotlin Multiplatform для IDE сделать это автоматически.

Вот пример доступа к значку и настройки его цветов с помощью параметра colorFilter в коде Compose Multiplatform:

Image(
    painter = painterResource(Res.drawable.ic_sample_icon),
    contentDescription = "Sample icon",
    modifier = Modifier.size(24.dp),
    colorFilter = ColorFilter.tint(Color.Blue)
)

Строки

Храните все строковые ресурсы в XML-файлах в каталогах composeResources/values. Для каждого элемента в каждом файле генерируется статическое средство доступа.

Compose Multiplatform поддерживает сокращенный синтаксис в стиле Emmet для добавления строковых ресурсов, массивов строк и строк для множественного числа непосредственно в XML-файлы. Например, если ввести test{Example} или s.test{Example} в strings.xml и нажать Tab, запись автоматически развернется в <string name="test">Example</string>.

Чтобы узнать, как локализовать строки для разных языковых стандартов, ознакомьтесь с руководством по локализации строк.

<resources>
    <string name="app_name">My awesome app</string>
    <string name="title">Some title</string>
</resources>

@Composable
fun stringResource(resource: StringResource): String {...}

@Composable
fun stringResource(resource: StringResource, vararg formatArgs: Any): String {...}

Text(stringResource(Res.string.app_name))

suspend fun getString(resource: StringResource): String

suspend fun getString(resource: StringResource, vararg formatArgs: Any): String

coroutineScope.launch {
    val appName = getString(Res.string.app_name)
}

<resources>
    <string name="str_template">Hello, %2$s! You have %1$d new messages.</string>
</resources>

Text(stringResource(Res.string.str_template, 100, "User_name"))

Text(stringResource(Res.string.str_template, "User_name", 100.1f))

<resources>
    <string name="app_name">My awesome app</string>
    <string name="title">Some title</string>
    <string-array name="str_arr">
        <item>item \u2605</item>
        <item>item \u2318</item>
        <item>item \u00BD</item>
    </string-array>
</resources>

@Composable
fun stringArrayResource(resource: StringArrayResource): List<String> {...}

val arr = stringArrayResource(Res.array.str_arr)
if (arr.isNotEmpty()) Text(arr[0])

suspend fun getStringArray(resource: StringArrayResource): List<String>

coroutineScope.launch {
    val appName = getStringArray(Res.array.str_arr)
}

<resources>
    <string name="app_name">My awesome app</string>
    <string name="title">Some title</string>
    <plurals name="new_message">
        <item quantity="one">%1$d new message</item>
        <item quantity="other">%1$d new messages</item>
    </plurals>
</resources>

@Composable
fun pluralStringResource(resource: PluralStringResource, quantity: Int): String {...}

@Composable
fun pluralStringResource(resource: PluralStringResource, quantity: Int, vararg formatArgs: Any): String {...}

Text(pluralStringResource(Res.plurals.new_message, 1, 1))

suspend fun getPluralString(resource: PluralStringResource, quantity: Int): String

suspend fun getPluralString(resource: PluralStringResource, quantity: Int, vararg formatArgs: Any): String

coroutineScope.launch {
    val appName = getPluralString(Res.plurals.new_message, 1, 1)
}

Шрифты

Храните пользовательские шрифты в каталоге composeResources/font. Compose Multiplatform поддерживает форматы шрифтов TTF, OTF, TTC и вариативные шрифты на всех платформах. Форматы WOFF и WOFF2 доступны только в веб-версии и macOS.

Чтобы загрузить шрифт как тип Font, используйте компонуемую функцию Font():

@Composable
fun Font(
    resource: FontResource,
    weight: FontWeight = FontWeight.Normal,
    style: FontStyle = FontStyle.Normal
): Font

Например:

В веб-приложениях специальные символы, например эмодзи и символы арабского письма, поддерживаются автоматически благодаря автоматическому подбору шрифта, который при необходимости загружает шрифты Noto.

Если вам нужно полностью контролировать используемый шрифт, включите в пакет определенный шрифт и зарегистрируйте его вручную с помощью API предварительной загрузки.

Файлы Raw

Чтобы загрузить любой файл Raw в виде массива байтов, используйте функцию Res.readBytes(path):

suspend fun readBytes(path: String): ByteArray

Файлы Raw можно размещать в каталоге composeResources/files и создавать внутри него любую иерархию.

Например, для доступа к файлам Raw используйте следующий код:

var bytes by remember {
    mutableStateOf(ByteArray(0))
}
LaunchedEffect(Unit) {
    bytes = Res.readBytes("files/myDir/someFile.bin")
}
Text(bytes.decodeToString())

coroutineScope.launch {
    val bytes = Res.readBytes("files/myDir/someFile.bin")
}

// bytes = Res.readBytes("files/example.png")
Image(bytes.decodeToImageBitmap(), null)

// bytes = Res.readBytes("files/example.xml")
Image(bytes.decodeToImageVector(LocalDensity.current), null)

// bytes = Res.readBytes("files/example.svg")
Image(bytes.decodeToSvgPainter(LocalDensity.current), null)

Сгенерированные карты ресурсов и строковых идентификаторов

Для удобства Compose Multiplatform также сопоставляет ресурсы со строковыми идентификаторами. Обращаться к ним можно, используя имя файла в качестве ключа:

val Res.allDrawableResources: Map<String, DrawableResource>
val Res.allStringResources: Map<String, StringResource>
val Res.allStringArrayResources: Map<String, StringArrayResource>
val Res.allPluralStringResources: Map<String, PluralStringResource>
val Res.allFontResources: Map<String, FontResource>

Пример передачи сопоставленного ресурса компонуемому элементу:

Image(painterResource(Res.allDrawableResources["compose_multiplatform"]!!), null)

Мультиплатформенные ресурсы Compose в качестве ресурсов Android

Начиная с Compose Multiplatform 1.7.0 все мультиплатформенные ресурсы упаковываются в ресурсы Android. Благодаря этому Android Studio может создавать предварительный просмотр компонуемых элементов Compose Multiplatform в исходных наборах Android.

Использование мультиплатформенных ресурсов в качестве ресурсов Android также позволяет напрямую обращаться к ним из WebView и компонентов медиаплеера Android, поскольку к ресурсам можно перейти по простому пути, например Res.getUri("files/index.html").

Пример компонуемого элемента Android, отображающего HTML-страницу ресурса со ссылкой на изображение из ресурсов:

В примере используется следующий простой HTML-файл:

Оба файла ресурсов в этом примере находятся в исходном наборе commonMain:

Доступ к мультиплатформенным ресурсам из внешних библиотек

Если вы хотите обрабатывать мультиплатформенные ресурсы с помощью других библиотек, подключённых к проекту, можно передавать в эти API пути к файлам, специфичные для платформы. Чтобы получить путь, специфичный для платформы, вызовите функцию Res.getUri(), указав путь проекта к ресурсу:

val uri = Res.getUri("files/my_video.mp4")

Теперь, когда переменная uri содержит абсолютный путь к файлу, любая внешняя библиотека может использовать этот путь для доступа к файлу удобным для неё способом.

Для задач, специфичных для Android, мультиплатформенные ресурсы также упаковываются как ресурсы Android.

Удалённые файлы

В контексте библиотеки ресурсов ресурсами считаются только файлы, являющиеся частью приложения.

Для загрузки удалённых файлов из интернета по URL можно использовать специализированные библиотеки:

• Compose ImageLoader

• Kamel

• Клиент Ktor

Если вы вручную скачиваете изображение или считываете его байты, воспользуйтесь функциями декодирования библиотеки ресурсов, чтобы преобразовать их. Пример загрузки изображений из сети в настольном приложении см. в разделе Использование изображений в Compose Multiplatform для настольных приложений.

Если вы самостоятельно скачиваете изображение или считываете его байты, преобразуйте их в изображение с помощью функций декодирования библиотеки ресурсов. Пример загрузки изображений из сети в настольном приложении см. в руководстве по использованию изображений в Compose Multiplatform для настольных приложений.

Использование ресурсов Java

Хотя ресурсы Java можно использовать с Compose Multiplatform, они не поддерживают расширенные возможности платформы: генерируемые средства доступа, поддержку нескольких модулей, локализацию и так далее. Чтобы воспользоваться этими возможностями, рассмотрите возможность полного перехода на библиотеку мультиплатформенных ресурсов.

В Compose Multiplatform 1.7.0 API ресурсов, доступный в пакете compose.ui, объявлен устаревшим. Если вам по-прежнему нужно работать с ресурсами Java, скопируйте в проект следующую реализацию, чтобы код продолжал работать после обновления до Compose Multiplatform 1.7.0 или более поздней версии: