@datacomvn/progress-and-modal

🚀 Thư viện hiển thị Progress Loading, Lottie Animation và Toast thông minh cho React Native

Được phát triển bởi Datacom Vietnam | Powered by Nitro Modules

📚 Documentation • 🎯 Examples • 💬 Support

✨ Tính năng nổi bật

• 🎯 Native Performance - Sử dụng Nitro Modules cho hiệu suất tối ưu
• 🎨 Lottie Animations - Hỗ trợ animation Lottie native mượt mà
• 🍞 Smart Toast - Toast tùy chỉnh với hình ảnh và animation
• ⚙️ Highly Customizable - Tùy chỉnh màu sắc, kích thước, thời gian
• 📱 Cross Platform - Hoạt động native trên cả iOS và Android
• 🎛️ Easy Configuration - Cấu hình đơn giản, sử dụng linh hoạt
• 🔥 TypeScript Support - Type definitions đầy đủ
• 🎪 Multiple Loading States - Spinner mặc định và Lottie loading
• 🛑 Force Hide Control - Khả năng ẩn tất cả loading trong trường hợp khẩn cấp

📦 Cài đặt

Cài đặt package

# NPM
npm install @datacomvn/progress-and-modal react-native-nitro-modules

# Yarn
yarn add @datacomvn/progress-and-modal react-native-nitro-modules

# PNPM
pnpm add @datacomvn/progress-and-modal react-native-nitro-modules

iOS Setup

cd ios && pod install

Android Setup

Không cần cấu hình thêm cho Android.

💡 Lưu ý quan trọng: react-native-nitro-modules là dependency bắt buộc. Tìm hiểu thêm tại Nitro Documentation

🚀 Sử dụng cơ bản

import {
  configure,
  showLoading,
  hideLoading,
  showLottie,
  hideLottie,
  forceHideLoading,
  showToast,
} from '@datacomvn/progress-and-modal';

// Import types (nếu cần)
import type {
  PAM_ConfigParams,
  PAM_LottieLoadingParams,
  PAM_ToastParams,
} from '@datacomvn/progress-and-modal';

// Cấu hình toàn cục (tùy chọn)
configure({
  backgroundAlpha: 0.3,
  indicatorColor: '#FF6B35',
});

// Hiển thị loading đơn giản
showLoading();

// Ẩn loading
hideLoading();

// Hiển thị toast
showToast({
  message: 'Thao tác thành công! 🎉',
  backgroundColor: '#4CAF50',
  textColor: '#FFFFFF',
  duration: 3000,
});

🎯 Examples

🔄 Basic Loading

const handleBasicLoading = async () => {
  showLoading();
  
  try {
    await someAsyncOperation();
    showToast({
      message: 'Hoàn thành!',
      backgroundColor: '#4CAF50',
      textColor: '#FFFFFF',
    });
  } catch (error) {
    showToast({
      message: 'Có lỗi xảy ra!',
      backgroundColor: '#F44336',
      textColor: '#FFFFFF',
    });
  } finally {
    hideLoading();
  }
};

🎨 Lottie Loading với Custom Animation

const handleLottieLoading = async () => {
  showLottie({
    lottie: require('./assets/loading_animation.json'),
    title: 'Đang xử lý dữ liệu',
    subtitle: 'Vui lòng chờ trong giây lát...',
  });
  
  await processData();
  
  hideLottie({ 
    lottie: require('./assets/done_animation.json'),
    title: 'Hoàn thành!',
  });
};

🍞 Advanced Toast với Icon

const showSuccessToast = () => {
  showToast({
    message: 'Đã lưu thành công',
    backgroundColor: '#4CAF50',
    textColor: '#FFFFFF',
    fontSize: 16,
    image: require('./assets/ic_success.png'), // Truyền ảnh từ local bundle
    imageSize: 24,
    duration: 2500,
  });
};

const showErrorToast = () => {
  showToast({
    message: 'Không thể kết nối server',
    backgroundColor: '#F44336',
    textColor: '#FFFFFF',
    image: require('./assets/ic_error.png'),
    imageSize: 24,
  });
};

🛑 Force Hide Loading

const handleForceStop = () => {
  // Trong trường hợp khẩn cấp, ẩn tất cả loading hiện tại
  forceHideLoading();
  
  showToast({
    message: 'Đã dừng tất cả loading',
    backgroundColor: '#FF9800',
    textColor: '#FFFFFF',
  });
};

// Sử dụng khi cần reset trạng thái loading
const handleReset = async () => {
  forceHideLoading(); // Đảm bảo không có loading nào đang hiển thị
  
  // Bắt đầu lottie loading mới
  showLottie({ 
    lottie: require('./assets/reset_animation.json'),
    title: 'Đang reset...' 
  });
  
  await resetApplication();
  hideLottie({ 
    lottie: require('./assets/success_animation.json'),
    title: 'Reset thành công!' 
  });
};

🎛️ Custom Configuration

// Cấu hình cho giao diện tối
configure({
  backgroundAlpha: 0.8,
  indicatorColor: '#BB86FC',
});

// Hoặc cấu hình cho giao diện sáng
configure({
  backgroundAlpha: 0.2,
  indicatorColor: '#6200EE',
});

📖 API Reference

configure(params: PAM_ConfigParams)

Cấu hình toàn cục cho loading indicators.

interface PAM_ConfigParams {
  backgroundAlpha?: number; // 0.0 - 1.0, mặc định: 0.16
  indicatorColor?: string;  // Hex color, mặc định: '#666666'
}

showLoading()

Hiển thị spinner loading mặc định ở giữa màn hình.

hideLoading()

Ẩn spinner loading mặc định.

showLottie(params: PAM_LottieParams)

Hiển thị loading với Lottie animation.

interface PAM_LottieParams {
  lottie: any | string;      // require('./animation.json') hoặc tên asset native
  title?: string;            // Tiêu đề
  subtitle?: string;         // Phụ đề
}

// Sử dụng
showLottie({ 
  lottie: require('./my_animation.json'), 
  title: 'Đang tải...' 
});

hideLottie(params: PAM_LottieParams)

Ẩn Lottie loading (thường dùng để hiển thị "Success/Done" animation trước khi đóng hẳn).

hideLottie({ 
  lottie: require('./done.json'),
  title: 'Xong!'
});

forceHideLoading()

Ẩn tất cả loading indicators hiện tại (bao gồm cả loading mặc định và Lottie).

forceHideLoading(); // Ẩn tất cả loading đang hiển thị

showToast(params: PAM_ToastParams)

Hiển thị toast notification.

interface PAM_ToastParams {
  message: string;           // Nội dung toast (bắt buộc)
  backgroundColor: string;   // Màu nền (bắt buộc)
  textColor: string;        // Màu chữ (bắt buộc)
  fontSize?: number;        // Kích thước font (dp)
  image?: any | string;     // Truyền require('./image.png') 
  imageSize?: number;       // Kích thước ảnh (dp), mặc định: 24
  duration?: number;        // Thời gian hiển thị (ms), mặc định: 2000
}

🎨 Cấu hình Assets

[!TIP] Bạn khuyến khích truyền thẳng require('./path/to/asset') qua params của thư viện để tận dụng Hot Reload và giảm dung lượng Native Bundle. Nếu bạn dùng string cũ tích hợp bằng tay vào Native Asset, hãy bỏ qua mục này để xem tham khảo.

🛠️ Troubleshooting

❌ Common Issues

Metro bundler không tìm thấy module:

# Clear cache và restart
npx react-native start --reset-cache

iOS build lỗi sau khi install:

cd ios && pod install --clean-install

Android build lỗi:

cd android && ./gradlew clean

Lottie animation không hiển thị:

• ✅ Kiểm tra file .json đã được thêm vào native project
• ✅ Tên file không chứa ký tự đặc biệt
• ✅ File size không quá lớn (khuyến nghị < 500KB)

Toast icon không hiển thị:

• ✅ Kiểm tra tên file không có extension
• ✅ File đã được thêm vào đúng thư mục native
• ✅ Rebuild app sau khi thêm assets

📋 Example App

Xem example app đầy đủ trong thư mục /example để tham khảo implementation chi tiết.

# Chạy example app
cd example
npm install
npx react-native run-ios
# hoặc
npx react-native run-android

🤝 Contributing

Chúng tôi rất hoan nghênh các đóng góp! Xem CONTRIBUTING.md để biết thêm chi tiết.

Development Setup

# Clone repository
git clone https://github.com/DeveloperDtc/react-native-progress-and-modal.git
cd react-native-progress-and-modal

# Install dependencies
yarn install

# Setup example app
cd example
yarn install
npx pod-install ios # Chỉ cho iOS

📋 Requirements

• React Native >= 0.70.0
• iOS >= 11.0
• Android API Level >= 21
• Node.js >= 16

📄 License

MIT License - xem LICENSE để biết thêm chi tiết.

🙏 Credits

• Nitro Modules - margelo.com
• React Native Builder Bob - callstack.com
• Lottie React Native - lottiefiles.com

Made with ❤️ by Datacom Vietnam

🌟 Star us on GitHub • 🐛 Report Issues • 💬 Discussions