أضف خمسة مصاريف، وأغلق Pocket Budget، ثم افتحه مجدّدًا، وستجد القائمة فارغة. كل شيء كان يعيش في الذاكرة. يتوقّع المستخدمون أن تصمد بياناتهم أمام إعادة التشغيل والتحديثات وهاتف نفدت بطاريته أثناء الحفظ. SwiftData هو إطار الحفظ الدائم (persistence) من Apple المصمّم لـ Swift: تصف نموذجك في الكود، ويتولّى هو قاعدة البيانات والمخطّط وإبقاء SwiftUI متزامنًا.
\nimport Foundation\nimport SwiftData\n\n@Model\nfinal class Expense {\n var title: String\n var amount: Decimal\n var category: Category\n var date: Date\n var note: String = \"\"\n\n init(title: String, amount: Decimal, category: Category, date: Date = .now) {\n self.title = title\n self.amount = amount\n self.category = category\n self.date = date\n }\n}تغيّر أمران عن الـ struct الذي تستخدمه منذ قسم التصميم. أولًا، @Model يتطلّب class. فالمصروف المحفوظ له هوية واحدة: يجب أن ترى القائمة وشاشة التفاصيل ونموذج التعديل كلها السجلّ نفسه، وهذا هو سلوك المرجع الذي تعلّمت أن تلجأ إليه حين تكون البيانات مشتركة. ثانيًا، تكتب المُهيِّئ بنفسك، لأن الـ classes لا تحصل على memberwise initializer.
يجعل @Model الـ class يتوافق مع PersistentModel، الذي يجلب معه Identifiable وHashable، فيستمر ForEach وNavigationLink(value:) في العمل دون تغيير. ويحتاج الـ enum المسمّى Category إلى التوافق مع Codable حتى يُخزَّن؛ أضفه إلى تعريفه. ويمكنك حذف خاصية id: يعطي SwiftData كل نموذج معرّفًا دائمًا.
@main\nstruct PocketBudgetApp: App {\n var body: some Scene {\n WindowGroup {\n ExpensesScreen()\n }\n .modelContainer(for: Expense.self)\n }\n}الـ model container (حاوية النماذج) يملك ملف قاعدة البيانات والمخطّط. وإنشاؤه مرة واحدة على الـ scene يضع أيضًا model context (سياق النماذج) في الـ environment. الـ context هو مساحة عملك: يتتبّع النماذج المضافة والمعدّلة والمحذوفة ويكتبها على القرص. والـ context الرئيسي يحفظ تلقائيًا، فمعظم التطبيقات لا تستدعي save() يدويًا أبدًا.
أنشئ الـ container في مكان واحد بالضبط. الـ ModelContainer المبني داخل body أو مُهيِّئ أحد الـ views يُعاد إنشاؤه كلما أعاد SwiftUI بناء ذلك الـ view، وكل نسخة تفتح المخزن من جديد. ضعه على الـ scene كما هنا، وسيتشاركه كل view تحته.
struct ExpensesScreen: View {\n @Query(sort: \\Expense.date, order: .reverse) private var expenses: [Expense]\n @Environment(\\.modelContext) private var context\n\n var body: some View {\n NavigationStack {\n List {\n ForEach(expenses) { expense in\n NavigationLink(value: expense) {\n Text(expense.title)\n }\n }\n .onDelete { offsets in\n for index in offsets {\n context.delete(expenses[index])\n }\n }\n }\n .navigationTitle(\"Expenses\")\n .navigationDestination(for: Expense.self) { expense in\n EditExpenseView(expense: expense)\n }\n }\n }\n}يجلب @Query كل Expense، الأحدث أولًا، ويعيد التنفيذ كلما تغيّرت البيانات المخزّنة، فأي حذف أو إضافة في أي مكان في التطبيق يحدّث هذه القائمة من تلقاء نفسها. نتيجة الـ query للقراءة فقط: أنت تغيّر البيانات عبر الـ context. وفي نموذج الإضافة من قسم SwiftUI، صار زر Save يستدعي context.insert(Expense(title: title, amount: amount, category: category, date: date)) بدل store.add(...). لم تعد المصاريف تعيش في BudgetStore؛ فهو يحتفظ الآن بإعدادات التطبيق مثل الحدّ الشهري وأسعار الصرف.
النموذج class مراقَب، فيعطيك @Bindable bindings مباشرة إلى داخله:
struct EditExpenseView: View {\n @Bindable var expense: Expense\n\n var body: some View {\n Form {\n TextField(\"Title\", text: $expense.title)\n TextField(\"Amount\", value: $expense.amount, format: .currency(code: \"USD\"))\n DatePicker(\"Date\", selection: $expense.date, displayedComponents: .date)\n }\n .navigationTitle(expense.title)\n }\n}لا يوجد زر Save. الكتابة تغيّر النموذج، فيلاحظ الـ context ذلك ويحفظ تلقائيًا، وتتحدّث القائمة الموجودة خلف الشاشة أيضًا. وإن أردت سلوك Cancel بدلًا من ذلك، فانسخ القيم إلى مسوّدات @State كما يفعل نموذج الإضافة، واكتبها رجوعًا عند Save.
مرّر predicate (شرط تصفية) إلى @Query لجلب مجموعة جزئية. وحين يعتمد الفلتر على قيمة يستقبلها الـ view، ابنِ الـ query داخل init:
struct RecentExpensesView: View {\n @Query private var recent: [Expense]\n\n init(since start: Date) {\n _recent = Query(filter: #Predicate<Expense> { $0.date >= start },\n sort: \\.date, order: .reverse)\n }\n\n var body: some View {\n List(recent) { Text($0.title) }\n }\n}يُفحص #Predicate وقت الترجمة ويُترجم إلى query لقاعدة البيانات، فتحدث التصفية في التخزين لا في حلقة Swift. اقتصر في الـ predicates على الخصائص المخزّنة البسيطة مثل التواريخ والأرقام والنصوص. فالتصفية على خصائص من نوع enum داخل predicate لم تكن موثوقة تاريخيًا، لذلك صفِّ التصنيفات في Swift بعد الجلب، أو خزّن القيمة الخام للتصنيف كـ String إن احتجت إلى الاستعلام بها.
إضافة خاصية جديدة لاحقًا، مثل note أعلاه، تعمل دون كود إضافي حين يكون لها قيمة افتراضية: ينقل SwiftData المخزن تلقائيًا إلى الشكل الجديد. أما إعادة التسمية فتحتاج إلى تلميح، @Attribute(originalName: "oldName")، حتى ينتقل العمود القديم إلى الاسم الجديد؛ وتغيير نوع خاصية يحتاج إلى مخطّط بإصدارات (versioned schema) وخطة ترحيل (migration plan)، ويمكنك تأجيل ذلك حتى يكون لديك مستخدمون حقيقيون ببيانات حقيقية.
صار Pocket Budget الآن يصمد أمام إعادة التشغيل. والدرس الأخير يضمن أنه يستمر في العمل وأنت تغيّره، باستخدام Swift Testing، ويوصله إلى هواتف الآخرين عبر TestFlight.
\n","toc":[{"id":"sec-1","text":"تحويل Expense إلى نموذج","level":2},{"id":"sec-2","text":"container واحد للتطبيق","level":2},{"id":"sec-3","text":"القراءة بـ @Query، والكتابة عبر الـ context","level":2},{"id":"sec-4","text":"التعديل بـ @Bindable","level":2},{"id":"sec-5","text":"التصفية","level":2}],"takeaways":["@Model يحوّل الـ class إلى بيانات محفوظة بشكل دائم؛ ويبني SwiftData مخطّط التخزين من خصائصه المخزّنة.",".modelContainer(for:) على الـ scene الخاص بالتطبيق ينشئ قاعدة البيانات مرة واحدة ويضع model context في الـ environment.","@Query يجلب النماذج ويرتّبها ويصفّيها للـ view، ويُبقي النتيجة محدّثة كلما تغيّرت البيانات.","أضف واحذف عبر modelContext؛ أما التغييرات على خصائص النموذج فتُحفظ تلقائيًا، بما في ذلك التعديلات المربوطة عبر @Bindable.","استخدم container في الذاكرة (inMemory: true أو isStoredInMemoryOnly) للـ previews والاختبارات حتى لا تمسّ البيانات الحقيقية أبدًا."],"further":[{"title":"SwiftData","url":"https://developer.apple.com/documentation/swiftdata"},{"title":"Preserving your app's model data across launches","url":"https://developer.apple.com/documentation/swiftdata/preserving-your-apps-model-data-across-launches"},{"title":"Query","url":"https://developer.apple.com/documentation/swiftdata/query"}],"quiz":[{"q":"لماذا يتحوّل Expense من struct إلى final class حين يصبح نموذجًا في SwiftData؟
@Model يتطلّب class، لأن السجلّ المحفوظ له هوية واحدة تراقبها كل شاشة وتعدّلها.","why":"صحيح. عدّل مصروفًا في view واحد وسيرى التغيير كل view يعرضه، وهذا هو سلوك المرجع."},{"text":"الـ structs لا يمكن أن تحتوي خصائص من النوعين Decimal أو Date.","why":"الـ structs تحمل هذين النوعين طوال الوقت؛ والدروس السابقة استخدمتهما."}],"answer":1},{"q":"تستخدم قائمة @Query private var expenses: [Expense]. كيف تحذف مصروفًا سحبه المستخدم جانبًا؟
expenses.remove(at: index)","why":"نتيجة الـ query للقراءة فقط؛ إنها تعكس المخزن ولا تتحكّم فيه."},{"text":"اضبط خصائص المصروف على قيم فارغة.","why":"هذا يحفظ مصروفًا فارغًا؛ ولا يحذف شيئًا."},{"text":"context.delete(expenses[index])، باستخدام الـ model context من الـ environment.","why":"صحيح. التغييرات تمرّ عبر الـ context، والـ query يحدّث نفسه ليطابقها."}],"answer":2},{"q":"تربط شاشة تعديل حقل TextField بـ $expense.title عبر @Bindable var expense: Expense. متى يُحفظ التغيير؟
context.insert(expense) مرة أخرى.","why":"المصروف موجود في الـ context أصلًا؛ والإضافة مجدّدًا ليست طريقة عمل التحديثات."},{"text":"أبدًا، لأن الـ bindings تنشئ نسخة من النموذج.","why":"النموذج class، والـ binding يكتب مباشرة في الـ instance المشترك."}],"answer":0},{"q":"يجب أن تعرض الـ preview الخاصة بقائمة المصاريف بيانات تجريبية دون أن تمسّ قاعدة البيانات الحقيقية. ماذا تستخدم؟
","options":[{"text":"الـ.modelContainer(for: Expense.self) العادي الخاص بالتطبيق.","why":"هذا يشير إلى المخزن نفسه على القرص الذي يستخدمه التطبيق؛ فتقرأ الـ previews بيانات حقيقية وتكتب فيها."},{"text":".modelContainer(for: Expense.self, inMemory: true)، ثم تضيف مصاريف تجريبية.","why":"صحيح. البيانات تعيش في الذاكرة فقط وتختفي حين تنتهي الـ preview."},{"text":"مصفوفة عادية بدل @Query.","why":"هذا يعاين view مختلفًا عن الذي ستطلقه، فيُفسد الغرض كله."}],"answer":1}],"exercise":{"kind":"fill","language":"swift","template":"@{{0}}\nfinal class Expense {\n var title: String\n var amount: Decimal\n var date: Date\n\n init(title: String, amount: Decimal, date: Date = .now) {\n self.title = title\n self.amount = amount\n self.date = date\n }\n}\n\nstruct ExpensesList: View {\n @{{1}}(sort: \\Expense.date, order: .reverse) private var expenses: [Expense]\n @Environment(\\.modelContext) private var context\n\n var body: some View {\n List {\n ForEach(expenses) { expense in\n Text(expense.title)\n }\n .onDelete { offsets in\n for index in offsets {\n context.{{2}}(expenses[index])\n }\n }\n }\n .toolbar {\n Button(\"Add coffee\") {\n context.{{3}}(Expense(title: \"Coffee\", amount: 4.5))\n }\n }\n }\n}","blanks":[{"answers":["Model"]},{"answers":["Query"]},{"answers":["delete"]},{"answers":["insert"]}],"title":"احفظ المصاريف بـ SwiftData","prompt":"اجعل Expense نموذجًا في SwiftData وأكمل القائمة: يجب أن تجلب المصاريف الأحدث أولًا، وتحذف ما يسحبه المستخدم جانبًا، وتضيف مصروف قهوة عند النقر على الزر. الـ scene الخاص بالتطبيق فيه .modelContainer(for: Expense.self) أصلًا.
يحوّل @Model الـ class إلى نموذج SwiftData محفوظ بشكل دائم. ويجلب @Query(sort: \\Expense.date, order: .reverse) كل المصاريف الأحدث أولًا ويتحدّث حين تتغيّر البيانات. وعمليات الكتابة تمرّ عبر الـ context القادم من الـ environment: context.delete(_:) يحذف نموذجًا وcontext.insert(_:) يضيف واحدًا. الـ context الرئيسي يحفظ تلقائيًا، والـ query يحدّث القائمة من تلقاء نفسه، فلا توجد مصفوفة عليك إبقاؤها متزامنة يدويًا.