快速开始

环境要求

平台	最低要求
Android	minSdk 24
iOS、macOS	iOS 15、macOS 12、Swift 5.9
Windows	Windows 10 版本 1809（build 17763）、Windows App SDK 1.8、.NET 8
Web	支持 <canvas> 和自定义元素的任意浏览器

安装

npm

npm install @loader-kit/web

yarn

yarn add @loader-kit/web

pnpm

pnpm add @loader-kit/web

Android (Gradle)

dependencies {
    implementation("io.github.maitrungduc1410:loaderkit-core:<version>")
    // Jetpack Compose（已包含 loaderkit-core）：
    implementation("io.github.maitrungduc1410:loaderkit-compose:<version>")
}

Swift Package Manager

dependencies: [
    .package(url: "https://github.com/maitrungduc1410/loader-kit.git", from: "<version>"),
],
targets: [
    .target(name: "App", dependencies: [.product(name: "LoaderKit", package: "loader-kit")]),
]

CocoaPods

pod 'LoaderKit', :git => 'https://github.com/maitrungduc1410/loader-kit.git', :tag => '<version>'

NuGet

dotnet add package LoaderKit.WinUI

• 把 <version> 替换为 GitHub releases 中的最新版本。tag 不带 v 前缀。
• Android：两个 artifact 都发布在 Maven Central 上，所以 repositories 里必须有 mavenCentral()。
• Apple：在 Xcode 里也可以通过 File > Add Package Dependencies 输入仓库 URL 来添加。这个 pod 没有发布到 CocoaPods trunk，需要在 Podfile 里直接指向仓库和某个发布 tag。
• Windows：安装 LoaderKit.WinUI 时会一并带上 LoaderKit.Core。
• React Native：见 React Native。

第一个加载动画

内置加载动画还是进度指示器？

• 始终没有百分比（等待请求、下拉刷新）：用内置加载动画，就像下面的例子。有 50 种样式可选。
• 任务有进度，哪怕一开始还不知道（下载、上传、处理文件）：用进度指示器。先以不确定状态开始（value 为 null，Swift 中为 nil），知道进度后再设置 value。始终是同一个组件，其他代码都不用改。

下面每段代码都会显示一个紫色的 BallSpinFadeLoader，速度是默认的 1.5 倍。

React

import { LoaderKit } from '@loader-kit/web/react';

<LoaderKit indicator="BallSpinFadeLoader" color="#7c3aed" speed={1.5} />

Vue

<script setup lang="ts">
import { LoaderKit } from '@loader-kit/web/vue';
</script>

<template>
  <LoaderKit indicator="BallSpinFadeLoader" color="#7c3aed" :speed="1.5" />
</template>

Svelte

<script lang="ts">
  import { LoaderKit } from '@loader-kit/web/svelte';
</script>

<LoaderKit indicator="BallSpinFadeLoader" color="#7c3aed" speed={1.5} />

HTML

<script type="module">
  import '@loader-kit/web/element';
</script>

<loader-kit indicator="BallSpinFadeLoader" color="#7c3aed" speed="1.5"></loader-kit>

TypeScript

import { LoaderKitView } from '@loader-kit/web';

const view = new LoaderKitView(document.querySelector('#loader')!, {
  indicator: 'BallSpinFadeLoader',
  color: '#7c3aed',
  speed: 1.5,
});

Android XML

<io.github.maitrungduc1410.loaderkit.LoaderKitView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    app:indicator="BallSpinFadeLoader"
    app:indicatorColor="#7C3AED"
    app:speed="1.5" />

Kotlin (View)

import io.github.maitrungduc1410.loaderkit.LoaderKitView

val loader = LoaderKitView(context).apply {
    indicator = "BallSpinFadeLoader"
    color = Color.parseColor("#7C3AED")
    speed = 1.5
}
container.addView(loader)

Compose

import io.github.maitrungduc1410.loaderkit.compose.LoaderKitIndicator

LoaderKitIndicator(
    indicator = "BallSpinFadeLoader",
    modifier = Modifier.size(48.dp),
    color = Color(0xFF7C3AED),
    speed = 1.5,
)

Swift (UIKit)

import LoaderKit

let loader = LoaderKitView(indicator: "BallSpinFadeLoader")
loader.color = .systemPurple
loader.speed = 1.5
view.addSubview(loader)

SwiftUI

import LoaderKit
import SwiftUI

struct LoadingView: View {
    var body: some View {
        LoaderKitIndicator("BallSpinFadeLoader")
            .color(.purple)
            .speed(1.5)
            .frame(width: 48, height: 48)
    }
}

XAML

<Page xmlns:lk="using:LoaderKit.WinUI">
    <lk:LoaderKitIndicator Indicator="BallSpinFadeLoader" Color="#7C3AED" Speed="1.5" />
</Page>

C#

using LoaderKit.WinUI;
using Microsoft.UI;

var indicator = new LoaderKitIndicator
{
    Indicator = "BallSpinFadeLoader",
    Color = ColorHelper.FromArgb(255, 0x7C, 0x3A, 0xED),
    Speed = 1.5,
};

效果：

默认尺寸

如果不指定尺寸，每个视图都是 40 × 40（单位分别是 dp、point、有效像素或 CSS 像素）。加载动画会画在视图内能放下的最大正方形里，并且居中。所以视图再宽，动画也只是居中显示，不会被拉伸。

停止加载动画

加载动画一显示就开始播放。任务完成后，记得把它停掉。默认情况下，停止后的加载动画什么都不画。

TypeScript

view.stop();      // 或者 view.animating = false
view.destroy();   // 彻底移除时调用

Kotlin (View)

loader.stop()     // 或者 loader.isAnimating = false

Compose

LoaderKitIndicator("BallSpinFadeLoader", animating = isLoading)

Swift (UIKit)

loader.stopAnimating()   // 或者 loader.isAnimating = false

SwiftUI

LoaderKitIndicator("BallSpinFadeLoader").animating(isLoading)

C#

indicator.IsAnimating = false;

调整速度、定格某一帧以及减弱动态效果，见播放控制。

下一步

• 内置加载动画：挑一个加载动画。
• 进度指示器：显示任务完成了多少。
• 自定义：参数、颜色和尺寸。
• 各平台页面：Web、Android、iOS 与 macOS、Windows。