Swift Academy · درس

إنشاء Widget باستخدام WidgetKit

أنشئوا Widget للشاشة الرئيسية باستخدام مخطط زمني

إنشاء Widget باستخدام WidgetKit درس مجاني في Swift Academy على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Swift Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Swift Academy 4 دروس في المجموع.

ما هي الودجة

الودجة هي عرض صغير يمكن إلقاء نظرة سريعة عليه، ويظهر على الشاشة الرئيسية أو شاشة القفل أو في وضع StandBy. وهي ليست تطبيقًا مصغرًا، إذ لا يمكنها التمرير أو تشغيل تعليمات برمجية عشوائية. بل تعرض لقطة من البيانات يحدّثها النظام وفق جدول زمني تحدّدونه عبر WidgetKit.

import WidgetKit
import SwiftUI
// A widget = configuration + timeline of entries
// + a SwiftUI view that renders one entry

هدف Widget Extension

تُضمَّن الودجات في هدف منفصل من نوع Widget Extension، وليس في التطبيق الرئيسي. ولها حزمة خاصة بها وتعمل في عملية مستقلة. وتضيفونها من خلال قالب Widget Extension في Xcode، الذي ينشئ هيكل الإعداد والموفّر تلقائيًا.

import WidgetKit
// File > New > Target > Widget Extension
// The extension declares one or more widgets
// in a WidgetBundle if you have several.

نوع الودجة

تلتزم الودجة بالبروتوكول Widget وتوفّر قيمة body تعيد إعدادًا. يربط هذا الإعداد بين معرّف kind، وprovider للخط الزمني، وview الذي يعرض كل إدخال.

import WidgetKit
import SwiftUI
struct WeatherWidget: Widget {
    var body: some WidgetConfiguration {
        StaticConfiguration(
            kind: "WeatherWidget",
            provider: WeatherProvider()) { entry in
            WeatherView(entry: entry)
        }
        .configurationDisplayName("Weather")
        .description("Shows the current forecast.")
    }
}

إعداد Static أم AppIntent

يُستخدم StaticConfiguration للودجات التي لا تتضمن خيارات للمستخدم. أما AppIntentConfiguration فيتيح للمستخدمين تخصيص الودجة، مثل اختيار مدينة أو حساب، من خلال App Intent. اختاروا الإعداد الثابت للمحتوى المحدد مسبقًا، والإعداد القائم على intent للودجات القابلة للتهيئة.

import WidgetKit
// StaticConfiguration     -> no user choices
// AppIntentConfiguration  -> user-editable parameters
let kinds = "static vs configurable"
_ = kinds

إدخال الخط الزمني

كل نقطة زمنية يمكن للودجة عرضها هي TimelineEntry، وهي بنية تتضمن date بالإضافة إلى أي بيانات يحتاج إليها العرض. ويزوّد الموفّر النظام بتسلسل من هذه الإدخالات.

import WidgetKit
struct WeatherEntry: TimelineEntry {
    let date: Date
    let temperature: Int
    let condition: String
}

عرض الودجة

العرض هو SwiftUI عادي، لكنه يخضع لقيود: لا تمرير، وتفاعل محدود، ويجب أن يبدو مناسبًا في عدة أحجام ثابتة. اقرأوا الإدخال ورتّبوا ملخصًا واضحًا يمكن إلقاء نظرة سريعة عليه.

import SwiftUI
import WidgetKit
struct WeatherView: View {
    let entry: WeatherEntry
    var body: some View {
        VStack {
            Text(entry.condition)
            Text("\(entry.temperature) degrees")
                .font(.title)
        }
    }
}

الأحجام المدعومة

أعلنوا عن الأحجام التي تدعمونها باستخدام supportedFamilies: .systemSmall و.systemMedium و.systemLarge، وأحجام شاشة القفل مثل .accessoryRectangular/.accessoryCircular، وغير ذلك. كيّفوا التخطيط لكل عائلة باستخدام بيئة عائلة الودجة.

import WidgetKit
import SwiftUI
// .configurationDisplayName(...)
// .supportedFamilies([.systemSmall, .systemMedium,
//                     .accessoryRectangular])
let families = "declare supported sizes"
_ = families

التكيّف مع الحجم

اقرؤوا @Environment(\.widgetFamily) داخل العرض لتغيير التخطيطات، مثل التمييز بين ودجة صغيرة مدمجة وأخرى متوسطة غنية بالمعلومات، من دون كتابة ودجات منفصلة.

import SwiftUI
import WidgetKit
struct AdaptiveView: View {
    @Environment(\.widgetFamily) var family
    let entry: WeatherEntry
    var body: some View {
        if family == .systemSmall {
            Text("\(entry.temperature)")
        } else {
            Text("\(entry.condition) \(entry.temperature)")
        }
    }
}

خلفية الحاوية

يجب على الودجات الحديثة إعلان خلفيتها باستخدام containerBackground(for: .widget) حتى يتمكن النظام من عرضها بشكل صحيح في سياقات مثل StandBy وشاشة القفل. ومن دون ذلك، قد يرفض النظام الودجة أو يعرضها بشكل غير صحيح.

import SwiftUI
import WidgetKit
struct Bg: View {
    var body: some View {
        Text("Hi")
            .containerBackground(for: .widget) {
                Color.blue
            }
    }
}

مشاركة البيانات مع التطبيق

تعمل عملية الودجة بشكل منفصل، ولذلك لا يمكنها قراءة الحالة الموجودة في ذاكرة التطبيق. شاركوا البيانات عبر App Group، وهو حاوية مشتركة يمكن للهدفين الوصول إليها، وعادةً ما تكون مجموعة UserDefaults مشتركة أو ملفًا في حاوية المجموعة.

import Foundation
let shared = UserDefaults(
    suiteName: "group.com.example.app")
// App writes; widget reads the same suite.
_ = shared

إعادة تحميل الودجة

عند تغيّر بيانات التطبيق، أخبروا WidgetKit بتحديث الودجة من خلال استدعاء WidgetCenter.shared.reloadTimelines(ofKind:) (أو reloadAllTimelines()). فهذا يحفّز النظام على طلب خط زمني جديد من الموفّر.

import WidgetKit
func refreshWidget() {
    WidgetCenter.shared.reloadTimelines(
        ofKind: "WeatherWidget")
}

اختبار سريع

تذكّروا كيفية مشاركة الودجة للبيانات مع التطبيق المضيف.

مراجعة

أنشأتم ودجة باستخدام WidgetKit:

توجد الودجات في امتداد منفصل، وتلتزم بـ Widget الذي يعيد WidgetConfiguration.
استخدموا StaticConfiguration أو AppIntentConfiguration، وTimelineEntry، وعرض SwiftUI مقيّدًا.
أعلنوا عن supportedFamilies، وكيّفوا العرض عبر widgetFamily، وأضيفوا containerBackground.
شاركوا البيانات عبر App Group، وأعيدوا التحميل باستخدام WidgetCenter.reloadTimelines.

الأسئلة الشائعة

هل درس «إنشاء Widget باستخدام WidgetKit» مجاني؟

نعم — نص درس «إنشاء Widget باستخدام WidgetKit» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Swift Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Swift Academy 4 دروس في المجموع.

ماذا ستتعلم في «إنشاء Widget باستخدام WidgetKit»؟

أنشئوا Widget للشاشة الرئيسية باستخدام مخطط زمني تتمرن على Swift Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Swift Academy؟

لا تُشترط خبرة سابقة. Swift Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.

كم من الوقت يستغرق درس «إنشاء Widget باستخدام WidgetKit»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Swift Academy هذا؟

نعم. كل درس في Swift Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Swift Academy