MaterialApp — چیست، پیکربندی و نقش ویجت ریشه

MaterialApp در Flutter چیست؟

MaterialApp — یک ویجت wrapper است که Material Design را در برنامه Flutter راه‌اندازی می‌کند. این ویجت ریشه Widget Tree است و به ویجت‌های فرزند دسترسی به سرویس‌های سیستمی می‌دهد: ناوبری، تم، پرس‌وجوهای رسانه و بومی‌سازی. بدون MaterialApp، برنامه سبک استاندارد Material را نخواهد داشت و نمی‌تواند از ویجت‌هایی مانند Scaffold، AppBar، FloatingActionButton و BottomNavigationBar استفاده کند.

MaterialApp چه چیزی به Widget Tree اضافه می‌کند

هنگام استفاده از MaterialApp، Flutter به طور خودکار چندین ویجت کلیدی به ریشه درخت اضافه می‌کند: Navigator (پشته صفحات برای ناوبری)، Theme (طرح رنگ و سبک‌ها)، MediaQuery (اطلاعات دستگاه)، Localizations (رشته‌های بومی‌سازی شده)، Directionality (جهت متن). این ویجت‌ها به عنوان InheritedWidget پیاده‌سازی شده و از طریق BuildContext در هر نقطه از برنامه قابل دسترس هستند.

استفاده پایه

پیکربندی حداقلی MaterialApp فقط به پارامتر home نیاز دارد — ویجتی که در صفحه اصلی نمایش داده می‌شود. Flutter به طور خودکار home را در Scaffold می‌پیچد، اگر Scaffold نباشد، از طریق مکانیزم WidgetsBinding. هنگام اجرای برنامه با runApp(MaterialApp(home: MyHomePage()))، Flutter Widget Tree ریشه را با MaterialApp به عنوان ریشه ایجاد می‌کند.

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: "My Application",
      theme: ThemeData(
        primarySwatch: Colors.blue,
        fontFamily: "Roboto",
      ),
      darkTheme: ThemeData(
        brightness: Brightness.dark,
        primarySwatch: Colors.blue,
      ),
      home: const MyHomePage(),
    );
  }
}

در این مثال، MaterialApp تم پایه (روشن و تاریک)، عنوان و صفحه اصلی را پیکربندی می‌کند. پارامتر title برای عنوان پنجره (در دسکتاپ) و دسترس‌پذیری استفاده می‌شود. پارامترهای theme و darkTheme ظاهر برنامه را در حالت‌های مختلف تعیین می‌کنند.

ساختار و پارامترهای MaterialApp

MaterialApp بیش از 30 پارامتر می‌پذیرد که به دسته‌هایی تقسیم می‌شوند: تنظیمات Material Design، مسیریابی، تم‌بندی، بومی‌سازی، رفتار خطا و تنظیمات برای پلتفرم‌های خاص. دانستن پارامترهای کلیدی امکان پیکربندی انعطاف‌پذیر برنامه را بدون نوشتن کد اضافی فراهم می‌کند.

پارامترهای اصلی پیکربندی

پارامتر title نام برنامه را برای عنوان پنجره و دسترس‌پذیری تعیین می‌کند. color رنگ برنامه را برای تغییر دهنده وظایف در Android مشخص می‌کند. debugShowCheckedModeBanner بنر حالت اشکال‌زدایی را در نسخه انتشار پنهان می‌کند. showPerformanceOverlay پوشش اطلاعات عملکرد را فعال می‌کند. supportDarkTheme نشان می‌دهد که آیا برنامه از تم تاریک پشتیبانی می‌کند.

پارامترهای پلتفرم‌های خاص

MaterialApp پارامترهایی برای پیکربندی رفتار در پلتفرم‌های مختلف ارائه می‌دهد: restorationScopeId برای ذخیره حالت برنامه هنگام راه‌اندازی مجدد در Android، scrollBehavior برای پیکربندی رفتار اسکرول در سیستم‌عامل‌های مختلف، useMaterial3 برای فعال‌سازی Material 3 (Material You). Material 3 رنگ‌های پویا، کامپوننت‌های جدید و سبک‌های به‌روز شده اضافه می‌کند.

تم‌بندی با theme و darkTheme

تم‌بندی — یکی از پارامترهای اصلی MaterialApp است. پارامتر theme یک شیء ThemeData دریافت می‌کند که پالت رنگ، تایپوگرافی، اشکال کامپوننت‌ها و آیکون‌نگاری را برای تم روشن تعیین می‌کند. پارامتر darkTheme — پیکربندی مشابه برای تم تاریک. Flutter به طور خودکار تم را بر اساس تنظیمات سیستم دستگاه تغییر می‌دهد.

ThemeData: طرح رنگ

ThemeData شامل primarySwatch (رنگ اصلی)، colorScheme (طرح رنگ گسترده Material 3)، brightness (روشن یا تاریک)، fontFamily (فونت پیش‌فرض)، textTheme (سبک‌های متن)، cardTheme، appBarTheme، buttonTheme و ده‌ها پارامتر دیگر برای پیکربندی کامپوننت‌های خاص است. برای Material 3 از colorScheme و برای Material 2 از primarySwatch استفاده کنید.

رنگ‌های پویای Material 3

Material 3 (Material You) از رنگ‌های پویا پشتیبانی می‌کند که از والپیپر دستگاه در Android 12+ استخراج می‌شوند. برای فعال‌سازی، useMaterial3: true را تنظیم کنید و از colorScheme.fromSeed یا colorScheme.fromImageProvider استفاده کنید. رنگ‌های پویا به طور خودکار یک پالت هماهنگ از 5 تن تولید می‌کنند: primary، secondary، tertiary، neutral و neutralVariant.

دسترسی به تم در ویجت‌ها

هر ویجتی می‌تواند از طریق Theme.of(context) به تم فعلی دسترسی پیدا کند. Theme.of یک ThemeData برمی‌گرداند که از آن می‌توان colors، textTheme و سایر پارامترها را دریافت کرد. برای اشتراک تغییرات تم (مثلاً هنگام جابجایی بین روشن و تاریک)، از context درون متد build استفاده کنید — Flutter به طور خودکار ویجت را هنگام تغییر تم بازسازی می‌کند.

Container(
  color: Theme.of(context).colorScheme.primary,
  child: Text(
    "نمونه متن با تم",
    style: Theme.of(context).textTheme.headlineMedium,
  ),
)

در این مثال، Theme.of(context) تم فعلی را از نزدیک‌ترین MaterialApp دریافت می‌کند. رنگ پس‌زمینه و سبک متن به طور خودکار با تم فعلی (روشن یا تاریک) مطابقت دارند. هنگام تغییر تم، Container و Text با مقادیر جدید از ThemeData به‌روز شده بازسازی می‌شوند.

مسیریابی و ناوبری در MaterialApp

MaterialApp Navigator را یکپارچه می‌کند — یک ناوگر پشته‌ای که انتقال بین صفحات را مدیریت می‌کند. پارامترهای initialRoute، routes و onGenerateRoute تعیین می‌کنند که Flutter چگونه ناوبری را پردازش می‌کند. Navigator.push و Navigator.pushReplacement امکان تغییر برنامه‌ریزی شده صفحات را فراهم می‌کنند و Navigator.pop — بازگشت به عقب.

مسیرهای نام‌گذاری شده (routes)

پارامتر routes یک Map دریافت می‌کند که در آن کلید نام مسیر (رشته) و مقدار تابعی است که ویجت صفحه را ایجاد می‌کند. مسیرهای نام‌گذاری شده برای ناوبری ایستا مناسب هستند: '/' (مسیر ریشه) معمولاً مطابق با home است، '/settings'، '/profile' — صفحات دیگر. Navigator.pushNamed(context, '/settings') به صفحه تنظیمات می‌رود.

تولید مسیر (onGenerateRoute)

onGenerateRoute — تابعی است که وقتی مسیر در routes یافت نمی‌شود فراخوانی می‌شود. این تابع RouteSettings را دریافت می‌کند و MaterialPageRoute برمی‌گرداند. این رویکرد برای ناوبری پویا مفید است، زمانی که مسیرها به داده‌ها بستگی دارند (مثلاً /user/42). onGenerateRoute نام مسیر را تجزیه می‌کند، پارامترها را استخراج می‌کند و صفحه مربوطه را ایجاد می‌کند.

لینک‌های عمیق و مسیریابی نام‌گذاری شده

برای پشتیبانی از لینک‌های عمیق (deep links)، از پارامترهای onGenerateInitialRoute و onGenerateRoute با هم استفاده کنید. لینک‌های عمیق امکان باز کردن یک صفحه خاص از برنامه را از طریق URL فراهم می‌کنند (مثلاً https://example.com/promo). Flutter لینک‌های عمیق را در Android (از طریق intent filters) و iOS (از طریق universal links) پردازش می‌کند و مسیر را به onGenerateRoute منتقل می‌کند.

MaterialApp(
  initialRoute: "/",
  routes: {
    "/": (context) => const HomePage(),
    "/settings": (context) => const SettingsPage(),
  },
  onGenerateRoute: (settings) {
    if (settings.name?.startsWith("/user/") == true) {
      final userId = settings.name!.split("/").last;
      return MaterialPageRoute(
        builder: (_) => UserPage(userId: userId),
      );
    }
    return null;
  },
)

در این مثال، onGenerateRoute مسیرهای پویا با فرمت /user/42 را پردازش می‌کند. اگر مسیر در routes ایستا یافت نشود و با الگوی پویا مطابقت نداشته باشد، Flutter صفحه خطایی را نمایش می‌دهد که می‌توان از طریق onUnknownRoute پیکربندی کرد.

بومی‌سازی و بین‌المللی‌سازی

MaterialApp پشتیبانی داخلی از بومی‌سازی را از طریق پارامترهای localizationsDelegates و supportedLocales فراهم می‌کند. LocalizationsDelegates رشته‌های بومی‌سازی شده را بارگذاری می‌کنند و supportedLocales تعیین می‌کند که برنامه از چه زبان‌هایی پشتیبانی می‌کند. Flutter به طور خودکار زبان دستگاه را تشخیص می‌دهد و منابع بومی‌سازی شده مربوطه را بارگذاری می‌کند.

پیکربندی supportedLocales و localizationsDelegates

پارامتر supportedLocales یک لیست از Localeهایی که برنامه پشتیبانی می‌کند دریافت می‌کند: [const Locale('en')، const Locale('ru')، const Locale('de')]. localizationsDelegates — لیستی از نمایندگانی که رشته‌های بومی‌سازی شده را بارگذاری می‌کنند. برای Material Design، GlobalMaterialLocalizations.delegate، GlobalWidgetsLocalizations.delegate و GlobalCupertinoLocalizations.delegate را اضافه کنید.

بومی‌سازی رشته‌های برنامه

برای بومی‌سازی رشته‌های خود، از کلاس AppLocalizations ایجاد شده از طریق flutter_localizations یا بسته intl استفاده کنید. AppLocalizations متدهای استاتیک برای دسترسی به رشته‌های بومی‌سازی شده ارائه می‌دهد: AppLocalizations.of(context)!.helloMessage. MaterialApp به طور خودکار Localizations را به Widget Tree منتقل می‌کند و آنها را از طریق context قابل دسترس می‌سازد.

• flutter_localizations — بسته رسمی برای بومی‌سازی ویجت‌های Material و رشته‌های سیستمی.
• intl — بسته بین‌المللی‌سازی: قالب‌بندی اعداد، تاریخ‌ها، ارزها و جمع‌بندی.
• فایل‌های ARB — فرمت ذخیره‌سازی رشته‌های بومی‌سازی شده که توسط flutter_localizations و intl استفاده می‌شود.

MaterialApp در مقابل CupertinoApp در مقابل WidgetsApp

Flutter سه ویجت ریشه برای پلتفرم‌های مختلف ارائه می‌دهد: MaterialApp (Material Design برای Android و وب)، CupertinoApp (سبک iOS) و WidgetsApp (ویجت پایه بدون استایل‌دهی). انتخاب ویجت ریشه ظاهر کل برنامه و در دسترس بودن کامپوننت‌های پلتفرم را تعیین می‌کند.

MaterialApp: انتخاب جهانی

MaterialApp برای اکثر برنامه‌ها به لطف پشتیبانی از Material Design که در Android، وب و دسکتاپ خوب به نظر می‌رسد مناسب است. Material Design یک کتابخانه غنی از کامپوننت‌ها ارائه می‌دهد: Scaffold، AppBar، BottomNavigationBar، Drawer، SnackBar، Dialog و بسیاری دیگر. MaterialApp همچنین از Material 3 با رنگ‌های پویا پشتیبانی می‌کند.

CupertinoApp: سبک iOS

CupertinoApp از Cupertino Design مطابق با Human Interface Guidelines اپل استفاده می‌کند. این ویجت CupertinoPageScaffold، CupertinoNavigationBar، CupertinoTabBar و سایر کامپوننت‌های با سبک iOS را ارائه می‌دهد. برای برنامه‌های iOS یا برنامه‌هایی که از سبک اپل در همه پلتفرم‌ها پیروی می‌کنند از CupertinoApp استفاده کنید.

WidgetsApp: ریشه حداقلی

WidgetsApp — یک ویجت ریشه پایه بدون استایل‌دهی است. این ویجت Navigator، MediaQuery و Localizations را اضافه می‌کند، اما تم‌ها یا کامپوننت‌های Material/Cupertino را ارائه نمی‌دهد. WidgetsApp برای سیستم‌های طراحی سفارشی، بازی‌ها یا برنامه‌هایی با استایل‌دهی خاص که Material یا Cupertino اضافی هستند مناسب است.