@Environment في SwiftUI — ما هو، المفاهيم الرئيسية والآلية

ما هو @Environment في SwiftUI؟

@Environment هو property wrapper في SwiftUI مصمم لقراءة القيم من بيئة النظام. البيئة هي حاوية هرمية من القيم يقوم SwiftUI بتوزيعها تلقائياً من العروض الأب إلى العروض الفرعية. كل قيمة بيئة تتم تحديدها بواسطة مفتاح — نوع يتوافق مع بروتوكول EnvironmentKey.

تشبه آلية البيئة حقن التبعيات (dependency injection) على مستوى الإطار: يوفر النظام مجموعة محددة من القيم — نمط الألوان (فاتح/داكن)، الإعدادات المحلية، حجم الخط، managedObjectContext لـ Core Data، dismiss لإغلاق الشاشات، وغيرها الكثير. العرض (View) الذي يعلن @Environment بمفتاح محدد يتلقى تلقائياً القيمة الحالية ويعاد رسمه عند تغييرها.

تعتمد معمارية بيئة SwiftUI على بروتوكول EnvironmentValues — هيكل يحتوي على جميع قيم النظام. كل قيمة تخزن كخاصية لهذا الهيكل مع getter و setter. يستخدم @Environment key path للوصول إلى خاصية محددة: @Environment(\.colorScheme) — الوصول إلى نمط الألوان، @Environment(\.locale) — الوصول إلى الإعدادات المحلية.

@Environment كـ Property Wrapper

ينفذ property wrapper @Environment آليتين رئيسيتين: قراءة قيمة من البيئة والاشتراك في تغييراتها. عند إنشاء عرض (View)، يمر SwiftUI على جميع خصائص @Environment ويربطها بالقيم المقابلة من السياق الحالي. إذا قام عرض أب بتغيير قيمة عبر المعدل .environment()، فإن جميع العروض الفرعية التي تقرأ تلك القيمة تعاد رسمها تلقائياً.

ميزة مهمة: @Environment يدعم القيم الاختيارية. إذا لم تكن القيمة معينة في التسلسل، يتم إرجاع القيمة الافتراضية المحددة في EnvironmentKey. لمفاتيح النظام، القيمة الافتراضية دائماً معقولة — على سبيل المثال، نمط الألوان الافتراضي هو .light. أما بالنسبة لـ المفاتيح المخصصة، فالمطور يحدد القيمة الافتراضية في طريقة defaultValue لبروتوكول EnvironmentKey.

struct EnvironmentReaderView: View {
    @Environment(\.colorScheme) var colorScheme
    @Environment(\.locale) var locale
    @Environment(\.sizeCategory) var sizeCategory

    var body: some View {
        VStack {
            Text("Current scheme: \(colorScheme == .dark ? "Dark" : "Light")")
            Text("Locale: \(locale.identifier)")
            Text("Font size: \(sizeCategory)")
        }
    }
}

في المثال، يقرأ العرض ثلاث قيم بيئة نظامية. عندما يتغير colorScheme — على سبيل المثال، قام المستخدم بتفعيل الوضع الداكن في الإعدادات — يعاد رسم العرض تلقائياً بالقيمة الجديدة. بشكل مماثل عند تغيير المنطقة أو حجم الخط (Dynamic Type). لا حاجة للعرض للاشتراك في الإشعارات أو استدعاء refresh — SwiftUI يدير ذلك تلقائياً.

قيم البيئة النظامية

يوفر SwiftUI عشرات قيم البيئة النظامية تغطي جوانب مختلفة من الواجهة والسلوك. نمط الألوان (\.colorScheme) هو واحد من أكثر القيم استخداماً، مما يسمح للواجهة بالتكيف مع الموضوعين الفاتح والداكن. الإعدادات المحلية (\.locale) تحتوي على إعدادات المستخدم الإقليمية لتنسيق التواريخ والأرقام والعملات.

لـ Core Data، يتم استخدام managedObjectContext (\.managedObjectContext) — سياق يتم تمريره عبر البيئة من حاوية الاستمرارية. للتنقل، يتوفر dismiss (\.dismiss) لإغلاق الشاشة الحالية و isPresented (\.isPresented) للعروض المشرطة. بالنسبة للتقويم والمنطقة الزمنية — calendar و timeZone على التوالي.

للوصول إلى قيم النظام، استخدم key path مع نقطة: @Environment(\.dismiss) var dismiss. يتحقق المجمع من وجود key path في EnvironmentValues، لذا فإن المفتاح الخاطئ سيؤدي إلى خطأ في وقت الترجمة. تضيف Apple قيمًا نظامية جديدة مع كل إصدار من iOS — القائمة الكاملة متاحة في توثيق EnvironmentValues.

@Environment vs @EnvironmentObject

على الرغم من الأسماء المتشابهة، فإن @Environment و @EnvironmentObject يخدمان أغراضًا مختلفة. @Environment يقرأ قيم النظام أو القيم المخصصة المسجلة عبر EnvironmentKey. @EnvironmentObject هو property wrapper لـ ObservableObject يتم تمريره عبر البيئة حسب النوع، دون مفتاح صريح.

يستخدم @EnvironmentObject لحقن التبعيات: يقوم العرض الأب بإنشاء كائن (على سبيل المثال، ViewModel) ويمرره إلى العروض الفرعية عبر المعدل .environmentObject(). تتلقاه العروض الفرعية عبر @EnvironmentObject ويمكنها كتابة وقراءة خصائصه. @Environment من ناحية أخرى هو لـ القراءة فقط لقيم النظام ولا يدعم التغذية الراجعة.

في الممارسة: استخدم @Environment للوصول إلى معلمات النظام (الموضوع، الإعدادات المحلية، حجم الخط) والتكوينات المخصصة التي لا تتغير في وقت التنفيذ. استخدم @EnvironmentObject لتمرير ViewModel أو خدمة عبر تسلسل العروض عندما تحتاج الحالة إلى التعديل من مكونات فرعية.

أمثلة كود @Environment

دعنا ننظر إلى إنشاء قيمة بيئة مخصصة. للقيام بذلك، تحتاج إلى تعريف هيكل يتوافق مع بروتوكول EnvironmentKey وتوسيع EnvironmentValues بخاصية جديدة. يسمح هذا بتمرير تكوين الموضوع أو إعدادات التطبيق عبر شجرة العروض بأكملها دون حاجة للخصائص (props).

struct AppThemeKey: EnvironmentKey {
    static let defaultValue: AppTheme = .system
}

extension EnvironmentValues {
    var appTheme: AppTheme {
        get { self[AppThemeKey.self] }
        set { self[AppThemeKey.self] = newValue }
    }
}

enum AppTheme { case system, light, dark }

يتطلب بروتوكول EnvironmentKey تنفيذ الخاصية الثابتة defaultValue — القيمة التي ستستخدم إذا لم يقم العرض الأب بتعيين بيئة مخصصة. يضيف توسيع EnvironmentValues خاصية محسوبة appTheme باستخدام subscript مع المفتاح. بعد ذلك، يمكن لأي عرض قراءة القيمة عبر @Environment(\.appTheme).

استخدام @Environment مع مفتاح مخصص

struct ThemedView: View {
    @Environment(\.appTheme) var appTheme
    @Environment(\.colorScheme) var colorScheme

    var body: some View {
        VStack {
            if appTheme == .dark || (appTheme == .system && colorScheme == .dark) {
                Text("Dark mode active")
                    .foregroundStyle(.white)
                    .background(Color.black)
            } else {
                Text("Light mode active")
                    .foregroundStyle(.black)
                    .background(Color.white)
            }
        }
    }
}

struct ContentView: View {
    @State private var selectedTheme = AppTheme.system

    var body: some View {
        ThemedView()
            .environment(\.appTheme, selectedTheme)
    }
}

يقرأ ThemedView بيئتين: appTheme المخصصة و colorScheme النظامية. تسمح المجموعة بتكوين مرن للموضوع: يمكن للمستخدم اختيار الموضوع الفاتح، الداكن أو النظامي. إذا تم تحديد نظامي، تؤخذ القيمة من colorScheme، التي تتغير تلقائياً عند تبديل الموضوع في إعدادات iOS. يقوم العرض الأب (ContentView) بتعيين قيمة appTheme عبر المعدل .environment().

استخدام dismiss لإغلاق شاشة

struct ModalView: View {
    @Environment(\.dismiss) var dismiss
    @State private var name = ""

    var body: some View {
        NavigationStack {
            Form {
                TextField("Your name", text: $name)
                Button("Save") { dismiss() }
            }
            .navigationTitle("Edit Profile")
        }
    }
}

يوضح هذا المثال الاستخدام العملي لـ dismiss — مثال من DismissAction من البيئة. يؤدي استدعاء dismiss() كدالة إلى إغلاق الشاشة المشرطة أو العودة في NavigationLink. الشرط الوحيد هو أن يتم عرض العرض بشكل مشرط أو يكون داخل NavigationStack. يتم تحديد dismiss تلقائياً من السياق: إذا تم فتح العرض كشيت (sheet) — يتم إغلاق الشيت، وإذا كان كـ popover — يتم إغلاق popover.