Skip to content

Files

Latest commit

 

History

History
455 lines (316 loc) · 15.6 KB

README.md

File metadata and controls

455 lines (316 loc) · 15.6 KB

logo_image Sketch Image Loader

Platform License version_icon QQ Group

Translations: 简体中文

Sketch is an image loading library specially designed for Compose Multiplatform and Android View. It has the following features:

  • Multiple sources: Supports loading images from multiple sources such as http, file, compose resource, android asset/content/resource, etc.
  • Powerful functions: Supports three-level caching, automatically cancels requests, automatically adjusts image size, automatically rotates images according to Exif Orientation, etc.
  • Rich functions: Supports Animated image, SVG images, Base64 images, and video frames
  • Easy to expand: Supports expansion of various aspects such as caching, decoding, transformation, transition, placeholder, etc.
  • Extended functions: Practical extensions such as pausing downloads when cellular data is provided, pausing loading during list scrolling, image type badges, download progress indicators, etc.
  • Modern: Completely based on Kotlin and Kotlin coroutine design

Sample App

Install

Published to mavenCentral

${LAST_VERSION}: Download (Not included 'v')

Compose Multiplatform:

Import the required Compose and network modules:

// Provides the core functions of Sketch as well as singletons and extension 
// functions that rely on singleton implementations
implementation("io.github.panpf.sketch4:sketch-compose:${LAST_VERSION}")

// Provides the ability to load network images
implementation("io.github.panpf.sketch4:sketch-http:${LAST_VERSION}")

Important

To improve the performance of compose, please copy compose_compiler_config.conf under the sketch-core module file to your project and configure it according to the Compose Stability Configuration documentation

Android View:

Import the required View and network modules:

// Provides the core functions of Sketch as well as singletons and extension 
// functions that rely on singleton implementations
implementation("io.github.panpf.sketch4:sketch-view:${LAST_VERSION}")

// Provides the ability to load network images
implementation("io.github.panpf.sketch4:sketch-http:${LAST_VERSION}")

Optional modules:

// Use Android or Skia's built-in decoder to decode gif animations and play them
implementation("io.github.panpf.sketch4:sketch-animated-gif:${LAST_VERSION}")

// [Android only] Use the GifDrawable of the android-gif-drawable library to decode and play gif animations
implementation("io.github.panpf.sketch4:sketch-animated-gif-koral:${LAST_VERSION}")

// [Android only] Android or Skia's built-in decoder decodes heif animations and plays them
implementation("io.github.panpf.sketch4:sketch-animated-heif:${LAST_VERSION}")

// Use Android or Skia's built-in decoder to decode webp animations and play them
implementation("io.github.panpf.sketch4:sketch-animated-webp:${LAST_VERSION}")

// Support accessing compose resources through uri or placeholder, fallback, error, etc.
implementation("io.github.panpf.sketch4:sketch-compose-resources:${LAST_VERSION}")
implementation("io.github.panpf.sketch4:sketch-extensions-compose-resources:${LAST_VERSION}")

// Provides practical functions such as download progress, image type icons, 
//  pausing loading during list scrolling, and saving cellular traffic.
implementation("io.github.panpf.sketch4:sketch-extensions-compose:${LAST_VERSION}")
implementation("io.github.panpf.sketch4:sketch-extensions-view:${LAST_VERSION}")

// [Android only] Support icon loading of apk files via file path 
implementation("io.github.panpf.sketch4:sketch-extensions-apkicon:${LAST_VERSION}")

// [Android only] Support loading icons of installed apps by package name and version code
implementation("io.github.panpf.sketch4:sketch-extensions-appicon:${LAST_VERSION}")

// [JVM only] Support using HttpURLConnection to access network images
implementation("io.github.panpf.sketch4:sketch-http-hurl:${LAST_VERSION}")

// [JVM only] Support using OkHttp to access network images
implementation("io.github.panpf.sketch4:sketch-http-okhttp:${LAST_VERSION}")

// Supports using ktor version 2.x to access network images
implementation("io.github.panpf.sketch4:sketch-http-ktor2:${LAST_VERSION}")

// Supports using ktor version 3.x to access network images
implementation("io.github.panpf.sketch4:sketch-http-ktor3:${LAST_VERSION}")

// Provides koin integration support, instead of sketch-compose and sketch-view, 
// and obtains Sketch instances from koin by default
implementation("io.github.panpf.sketch4:sketch-compose-koin:${LAST_VERSION}")
implementation("io.github.panpf.sketch4:sketch-view-koin:${LAST_VERSION}")

// Support SVG images
implementation("io.github.panpf.sketch4:sketch-svg:${LAST_VERSION}")

// [Android only] Use Android's built-in MediaMetadataRetriever class to decode video frames
implementation("io.github.panpf.sketch4:sketch-video:${LAST_VERSION}")

// [Android only] Decoding video frames using wseemann's FFmpegMediaMetadataRetriever library
implementation("io.github.panpf.sketch4:sketch-video-ffmpeg:${LAST_VERSION}")

Tip

  • sketch-compose, sketch-view Modules all depend on the singleton provided by the sketch-singleton module. If you don’t need the singleton, you can directly rely on their *-core version.
  • The sketch-http module depends on sketch-http-hurl on jvm platforms and sketch-http-ktor3 on non-jvm platforms.

Register component

Sketch supports automatic discovery and registration of Fetcher and Decoder components, which are implemented through ServiceLoader on the JVM platform and through the @EagerInitialization annotation on non-JVM platforms.

All built-in modules support automatic registration. If you want to disable automatic registration, please refer to the documentation for manual registration: 《Register component》

R8 / Proguard

  1. Android, iOS, Web and other platforms do not need to configure any obfuscation rules
  2. The following obfuscation rules are required for desktop platforms:
    # -------------------------- Sketch Privider ---------------------------- #
    -keep class * implements com.github.panpf.sketch.util.DecoderProvider { *; }
    -keep class * implements com.github.panpf.sketch.util.FetcherProvider { *; }
    
  3. It may also be necessary to add obfuscation configurations to the indirect dependencies of three-party libraries such as Kotlin Coroutines, OkHttp, Okio

Quickly Started

Compose Multiplatform:

// val imageUri = "/Users/my/Downloads/image.jpg"
// val imageUri = file:///compose_resource/composeResources/com.github.panpf.sketch.sample.resources/files/sample.png
val imageUri = "https://www.sample.com/image.jpg"

AsyncImage(
    uri = imageUri,
    contentDescription = "photo"
)

AsyncImage(
    uri = imageUri,
    state = rememberAsyncImageState(ComposableImageOptions {
        placeholder(Res.drawable.placeholder)
        error(Res.drawable.error)
        crossfade()
        // There is a lot more...
    }),
    contentDescription = "photo"
)

AsyncImage(
    rqeuest = ComposableImageRequest(imageUri) {
        placeholder(Res.drawable.placeholder)
        error(Res.drawable.error)
        crossfade()
        // There is a lot more...
    },
    contentDescription = "photo"
)

Image(
    painter = rememberAsyncImagePainter(
        request = ComposableImageRequest(imageUri) {
            placeholder(Res.drawable.placeholder)
            error(Res.drawable.error)
            crossfade()
            // There is a lot more...
        }
    ),
    contentDescription = "photo"
)

Tip

placeholder(Res.drawable.placeholder) needs to import the sketch-compose-resources module

Android View:

// val imageUri = "/sdcard/download/image.jpg"
// val imageUri = "file:///android_asset/image.jpg"
// val imageUri = "content://media/external/images/media/88484"
val imageUri = "https://www.sample.com/image.jpg"

imageView.loadImage(imageUri)

imageView.loadImage(imageUri) {
    placeholder(R.drawable.placeholder)
    error(R.drawable.error)
    crossfade()
    // There is a lot more...
}

val request = ImageRequest(context, imageUri) {
    placeholder(R.drawable.placeholder)
    error(R.drawable.error)
    crossfade()
    target(imageView)
    // There is a lot more...
}
context.sketch.enqueue(request)

Documents

Basic functions:

Featured functions:

Change log

Please review the CHANGELOG.md file

Test Platform

  • Android: Emulator; Arm64; API 21-34
  • Desktop: macOS; 14.6.1; JDK 17
  • iOS: iphone 16 simulator; iOS 18.1
  • Web: Chrome; 130

Run Sample App

Prepare the environment:

  1. Android Studio: Norwhal+ (2025.1.1+)
  2. JDK: 17+
  3. Use kdoctor to check the running environment and follow the prompts to install the required software
  4. Android Studio installs the Kotlin Multiplatform plugin

Run the sample app:

  1. Clone the project and open it using Android Studio
  2. After synchronization is completed, the Kotlin Multiplatform plug-in will automatically create a running configuration for each platform.
  3. Select the corresponding platform's running configuration, and then click Run

About version 4.0

  • The maven groupId is upgraded to io.github.panpf.sketch4, so versions 2.* and 3.* will not prompt for upgrade
  • Version 4.0 is specially built for Compose Multiplatform, so there are many breaking changes in the API, please upgrade with caution
  • Version 4.0 has made a lot of simplifications and is much simpler than version 3.0, please check the update log for details
  • Android minimum API raised to API 21
  • Kotlin version upgraded to 2.0.0

Special thanks

My Projects

The following are my other open source projects. If you are interested, you can learn about them:

  • zoomimage: Library for zoom images, supported Android View, Compose and Compose Multiplatform; supported double-click zoom, One or two fingers gesture zoom, single-finger drag, inertial sliding, positioning, rotation, super-large image subsampling and other functions.
  • assembly-adapter: A library on Android that provides multi-type Item implementations for various adapters. Incidentally, it also provides the most powerful divider for RecyclerView.
  • sticky-item-decoration: RecyclerView sticky item implementation

License

Apache 2.0. See the LICENSE file for details.