kuikly-assets-resource

Kuikly resource file management and loading

Resource directory structure

assets resources are stored in the shared/src/commonMain/assets directory,generally place resources in the corresponding page directory; resources shared by multiple pages go in the common/ directory:

shared/src/commonMain/
├── assets/
│   ├── MyPage/            # MyPage 页面资源（推荐，资源跟随页面）
│   │   ├── banner.png
│   │   └── icon.png
│   ├── OtherPage/         # OtherPage 页面资源
│   │   └── bg.png
│   └── common/            # 公共资源（多页面共享时使用）
│       └── logo.png
└── kotlin/               # 业务代码

---

ImageUri API

ImageUri is Kuikly's unified resource URI wrapper class, used to reference resources in components such as Image、PAG .

Factory method

// 页面 assets 资源（当前页面目录，最常用）
ImageUri.pageAssets("banner.png")
// 生成: assets://#pageName#/banner.png（运行时替换为实际页面名）

// 页面 assets 子目录资源
ImageUri.pageAssets("icons/star.png")
// 生成: assets://#pageName#/icons/star.png

// 公共 assets 资源（common 目录，多页面共享）
ImageUri.commonAssets("logo.png")
// 生成: assets://common/logo.png

// 本地文件路径
ImageUri.file("/path/to/image.png")
// 生成: file:///path/to/image.png

URI Scheme constant

Scheme	Value	Description
SCHEME_COMMON_ASSETS	assets://common/	Public resources
SCHEME_PAGE_ASSETS	assets://#pageName#/	Page resources (replaced at runtime)
SCHEME_FILE	file://	Local file
SCHEME_BASE64	data:image	Base64 image

---

Kuikly DSL resource loading

Load Assets images

// Image 组件引用 assets 资源
Image {
    attr {
        src(ImageUri.pageAssets("banner.png"))         // 页面资源（最常用）
    }
}
Image {
    attr {
        src(ImageUri.commonAssets("logo.png"))         // 公共资源
    }
}
        

---

Compose DSL resource loading

Compose DSL loads local assets resources through DrawableResource + ImageUri , and the directory structure and packaging configuration are exactly the same as Kuikly DSL.

Related import

import com.tencent.kuikly.compose.foundation.Image
import com.tencent.kuikly.compose.resources.painterResource
import com.tencent.kuikly.compose.resources.imageResource
import com.tencent.kuikly.compose.resources.DrawableResource
import com.tencent.kuikly.compose.resources.InternalResourceApi

Load Assets images

// 1. 定义 DrawableResource（需要 @OptIn InternalResourceApi）
@OptIn(InternalResourceApi::class)
private val bannerRes by lazy(LazyThreadSafetyMode.NONE) {
    DrawableResource(ImageUri.pageAssets("banner.png").toUrl(""))
}

// 2. 使用 painterResource 加载（返回 Painter，用于 Image 组件）
@Composable
fun MyImage() {
    Image(
        painter = painterResource(bannerRes),
        contentDescription = null,
        modifier = Modifier.size(200.dp, 100.dp),
    )
}

// 3. 使用 imageResource 加载（返回 ImageBitmap，用于 Canvas 绘制）
@Composable
fun MyCanvas() {
    val bitmap = imageResource(bannerRes)
    Canvas(Modifier.size(100.dp)) {
        drawImage(bitmap)
    }
}

---

Packaging configuration for each platform

Using assets resources for the first time requires packaging configuration, see PLATFORM_CONFIG.md

---