ذخیره‌سازی داده‌های سبک روی دستگاه (SharedPreferences)

Store key-value data on disk

آموزش ذخیره و بازیابی تنظیمات و داده‌های ساده به صورت کلید-مقدار روی حافظه دستگاه با بسته shared_preferences

فهرست مطالب این صفحه

اگر نیاز به ذخیره مقادیر ساده و سبک (مانند تنظیمات تم روشن/تاریک، زبان انتخابی کاربر یا وضعیت نمایش راهنمای اولیه) دارید که پس از بسته شدن کامل برنامه نیز باقی بمانند، بسته رسمی shared_preferences بهترین راهکار است.

۱. نصب بسته shared_preferences

دستور زیر را در ترمینال پروژه اجرا کنید:

Terminal / Bash
flutter pub add shared_preferences

۲. ذخیره، خواندن و حذف داده‌ها

عملیات دسترسی به حافظه دستگاه ناهمگام (Asynchronous) هستند و از طریق await انجام می‌شوند. انواع پشتیبانی‌شده شامل int، double، bool، String و List<String> هستند:

Dart
import 'package:shared_preferences/shared_preferences.dart';

class PreferencesService {
  static const String _darkModeKey = 'is_dark_mode';
  static const String _launchCountKey = 'launch_count';

  // ذخیره تنظیمات تم
  Future<void> setDarkMode(bool isDark) async {
    final prefs = await SharedPreferences.getInstance();
    await prefs.setBool(_darkModeKey, isDark);
  }

  // خواندن تنظیمات تم (با مقدار پیش‌فرض false)
  Future<bool> isDarkMode() async {
    final prefs = await SharedPreferences.getInstance();
    return prefs.getBool(_darkModeKey) ?? false;
  }

  // افزایش شمارنده دفعات اجرای برنامه
  Future<int> incrementLaunchCount() async {
    final prefs = await SharedPreferences.getInstance();
    final current = prefs.getInt(_launchCountKey) ?? 0;
    final updated = current + 1;
    await prefs.setInt(_launchCountKey, updated);
    return updated;
  }

  // حذف یک کلید مشخص
  Future<void> clearDarkModeSetting() async {
    final prefs = await SharedPreferences.getInstance();
    await prefs.remove(_darkModeKey);
  }
}

محدودیت امنیتی و حجمی: از SharedPreferences برای ذخیره داده‌های حجیم یا اطلاعات حساس (مانند رمز عبور خام یا توکن‌های بانکی) استفاده نکنید؛ برای داده‌های ساخت‌یافته حجیم از پایگاه‌داده محلی SQLite (sqflite) و برای توکن‌های امنیتی از flutter_secure_storage استفاده کنید.