chaoperty_floating_loader

Global transparent overlay loader for Flutter — works from anywhere via a global navigatorKey.
Supports once, ping‑pong, and loop‑wrap motions, with optional dim background and card.
ไทยอยู่ด้านล่าง ⬇️

Dart Flutter Platforms License

✨ Features

  • Global overlay loader (no BuildContext needed)
  • Motions: once, ping‑pong, loop‑wrap
  • Start/end positions, ranges, edge bounce
  • Optional dim backdrop and card
  • Bundle‑friendly GIF (or your own assets)
  • Horizontal, vertical, and diagonal patterns (via v* params)

📦 Installation

dependencies:
  chaoperty_floating_loader: ^0.1.0

If you want to use the bundled GIF that ships with the package, you don’t need to add anything to your app’s assets.
For your own GIFs, declare them under your app’s flutter/assets and pass asset: 'images/your.gif' to show(...).

⚙️ Setup (required)

Register the global navigatorKey:

import 'package:flutter/material.dart';
import 'package:chaoperty_floating_loader/chaoperty_floating_loader.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: ChaoAppLoader.navigatorKey, // ✅ required
      home: const MyHome(),
    );
  }
}

🚀 Quick Usage

ElevatedButton(
  onPressed: () {
    ChaoAppLoader.show(
      asset: 'assets/images/my_duck.png', // หรือ .gif ก็ได้
      assetFromPackage: false, // สำคัญ! บอกว่าไม่ใช่ของแพ็กเกจ
      packAsset: ChaoPackAsset.duckFrontWalkGif,
      message: 'กำลังโหลด...',         // text under the GIF
      slideAcross: true,               // enable horizontal motion
      motion: Motion.pingPong,         // once | pingPong | loopWrap
      rangeMinAt: 0.2,                 // 0.0..1.0
      rangeMaxAt: 0.8,                 // 0.0..1.0
      slideMs: 2000,                   // bigger = slower
      verticalFactor: 0.7,             // 0.0(top) → 1.0(bottom)
      // asset: 'images/my_loader.gif', // use your own asset
    );
    Future.delayed(const Duration(seconds: 2), ChaoAppLoader.hide);
  },
  child: const Text('Show Loader'),
);

Hide anytime:

ChaoAppLoader.hide();

🧭 Motion Examples

1) Once (custom start → end)

ChaoAppLoader.show(
  message: 'Once: 0.20 → 0.85',
  slideAcross: true,
  motion: Motion.once,
  fromAt: 0.20,
  toAt: 0.85,
  bounceAtEdges: true, // small bounce on edge
  slideMs: 5200,
  verticalFactor: 0.70,
);

2) Ping‑Pong (within a range)

ChaoAppLoader.show(
  message: 'Ping-Pong: 0.30 ↔ 0.80',
  slideAcross: true,
  motion: Motion.pingPong,
  rangeMinAt: 0.30,
  rangeMaxAt: 0.80,
  bounceAtEdges: true,
  slideMs: 1400,
  verticalFactor: 0.66,
);

3) Loop‑Wrap (Left → Right)

ChaoAppLoader.show(
  message: 'Loop wrap (L→R)',
  slideAcross: true,
  motion: Motion.loopWrap,
  slideToRight: true,
  startAt: 0.15, // or Random().nextDouble()
  slideMs: 2400,
  verticalFactor: 0.72,
);

4) Vertical only (Top → Bottom)

ChaoAppLoader.show(
  message: 'Vertical once: 0.10 → 0.85',
  vSlideAcross: true,
  vMotion: Motion.once,
  vFromAt: 0.10,
  vToAt: 0.85,
  slideMs: 2600,
);

5) Diagonal (loop X + ping‑pong Y)

ChaoAppLoader.show(
  message: 'Diagonal: loop X + ping-pong Y',
  slideAcross: true,
  motion: Motion.loopWrap,
  slideToRight: true,
  startAt: 0.2,
  vSlideAcross: true,
  vMotion: Motion.pingPong,
  vRangeMinAt: 0.65,
  vRangeMaxAt: 0.80,
  slideMs: 2400, // controls both axes
);

⚙️ API

Param Type Default Description (EN / TH)
message String 'กำลังโหลด...' Text under GIF / ข้อความใต้ GIF
size double 72 Base loader size / ขนาดฐาน
gifWidth / gifHeight double? null Force GIF width/height / กำหนดกว้าง/สูงของ GIF
dimBackground bool false Dim backdrop / ทำฉากหลังมืด
useCard bool false White card behind GIF / แสดงการ์ดพื้นขาว
asset String? bundled GIF Custom asset path / พาธรูปของคุณ
slideAcross bool false Enable horizontal motion / เปิดการวิ่งแนวนอน
motion Motion Motion.once once / pingPong / loopWrap
slideMs int 3500 Duration per cycle (ms) / ยิ่งมากยิ่งช้า
verticalFactor double 0.5 Anchor Y (0=top..1=bottom) when moving horizontally / จุดยึดแกน Y
startAt double? null Start (0..1, null=random) / จุดเริ่ม (สุ่มถ้าไม่ระบุ)
slideToRight bool? null Direction: right/left (null=auto) / ทิศทาง (อัตโนมัติถ้าไม่ระบุ)
bounceAtEdges bool false Tiny bounce at edges / เด้งเล็กน้อยที่ขอบ
edgeBouncePx double 14.0 Bounce offset in px / ระยะเด้ง (px)
fromAt / toAt double? – Exact start/end for once / จุดเริ่ม-จบโหมด once
rangeMinAt / rangeMaxAt double? – Range for pingPong / ช่วงวิ่งไป-กลับ
vSlideAcross bool false Enable vertical motion / เปิดการวิ่งแนวตั้ง
vMotion Motion Motion.once Vertical motion mode / โหมดแนวตั้ง
vFromAt / vToAt double? – Start/end for vertical once / จุดเริ่ม-จบแนวตั้ง
vRangeMinAt / vRangeMaxAt double? – Range for vertical pingPong / ช่วงแนวตั้ง

Tips

  • Make it slower/faster → change slideMs (bigger = slower).
  • Start anywhere → use startAt: Random().nextDouble() or fromAt/toAt.
  • Use packaged GIF → the default bundled GIF just works; pass asset: to override.

🧪 Local page-only overlay

class LoadingOverlay extends StatelessWidget {
  final bool loading;
  final Widget child;

  const LoadingOverlay({super.key, required this.loading, required this.child});

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        child,
        if (loading)
          const Positioned.fill(
            child: DuckLoading(message: 'Loading...'),
          ),
      ],
    );
  }
}

🇹🇭 ภาษาไทย (Thai)

chaoperty_floating_loader คือ ตัวโหลดแบบโอเวอร์เลย์โปร่งใส ที่เรียกได้จากทุกที่ (ไม่ต้องมี BuildContext) ผ่าน navigatorKey ระดับแอป
รองรับการเคลื่อนไหว ครั้งเดียว (once), ไป–กลับ (ping‑pong) และ วนรอบ (loop‑wrap)
ปรับ จุดเริ่ม/สิ้นสุด, ช่วงการวิ่ง, เด้งตอนชนขอบ, ใส่ ฉากหลังมืด และ การ์ด ได้

วิธีตั้งค่า (จำเป็น)

ใส่ navigatorKey: ChaoAppLoader.navigatorKey ใน MaterialApp

ตัวอย่างใช้งานเร็ว

ดูตัวอย่างด้านบนในส่วน Quick Usage ได้เลย

ทิป

  • ให้ช้าลง/เร็วขึ้น: แก้ slideMs
  • เริ่มตรงไหนก็ได้: startAt หรือ fromAt/toAt
  • ใช้ GIF จากแพ็กเกจ: ค่าเริ่มต้นทำงานได้เลย หรือส่ง asset: เป็นของคุณเอง

📄 License

MIT © Chaoperty

Libraries

chaoperty_floating_loader