# مؤقت Live Activity في Expo

By Tarik Pinarci (https://tarikpinarci.com). Published 2025-05-01. Canonical: https://tarikpinarci.com/ar/blog/expo-live-activity-timer

# بناء مؤقت Live Activity في Expo

الـ Live Activities في iOS نقلة نوعية، فهي تتيح للتطبيقات عرض تحديثات لحظية مباشرة على شاشة القفل أو في Dynamic Island. وبطبيعة الحال بدأت أتخيل كم سيكون رائعًا أن يعمل مؤقت التمارين هناك، فيحافظ على حماس المستخدمين من دون أن يفتحوا قفل هواتفهم أصلًا. لكن كانت هناك عقبة: تُبنى الـ Live Activities بأدوات Apple الـ native، مثل Swift وActivityKit. عندها اكتشفت أداة اسمها [expo-apple-targets](https://github.com/EvanBacon/expo-apple-targets) أغنتني عن كتابة وحدات كاملة من الصفر، وجعلت العملية أسهل بكثير مما توقعت. في هذا المقال سأشرح لك كيف بنيت Live Activity قائمة على مؤقت في iOS، والخطوات التي اتبعتها، وما تعلمته على الطريق.

## لماذا أصبحت مهووسًا بالـ Live Activities

الـ Live Activities ليست مجرد حيلة لطيفة، بل نقلة نوعية في تفاعل المستخدمين. تصفها [إرشادات الواجهات البشرية (Human Interface Guidelines)](https://developer.apple.com/design/human-interface-guidelines/live-activities) من Apple بأنها طريقة لتقديم "معلومات حالية يمكن استيعابها بنظرة" للمهام الحساسة للوقت. تخيّل تطبيق لياقة يعرض مدة تمرين البلانك أثناء التمرين، أو تطبيق توصيل طعام يتتبع رحلة البيتزا، أو تطبيق مشاركة رحلات يحدّث الوقت المتوقع لوصول السائق، كل ذلك مباشرة على شاشة القفل، أو في Dynamic Island على iPhone 14 Pro وما بعده. الأمر أشبه بمنح المستخدمين بطاقة VIP لأهم تحديثات تطبيقك من دون أن يحتاجوا إلى فتح قفل هواتفهم.

أردت أن يرى المستخدمون مؤقت التمرين وهو يعدّ أثناء الجولة، فيبقون مركّزين من دون أن يُجبروا على فتح التطبيق. هذا النوع من اللمسات يجعل التطبيق يبدو احترافيًا، وكنت متحمسًا تمامًا. لكن لا يمكنك التعامل مع كل هذا من دون لمس أي طبقة native، لذا كنت أعرف أنني سأغوص في Swift وأصارع Xcode. ثم اكتشفت [expo-apple-targets](https://github.com/EvanBacon/expo-apple-targets)، وهي حزمة تسد الفجوة بين عالم JavaScript في Expo والميزات الـ native في iOS. شكر كبير لـ [Evan Bacon](https://x.com/Baconbrix)، فهذه الأداة حوّلت مهمة مخيفة إلى لغز صعب لكنه قابل للحل.

## الصورة الكبيرة: Live Activities في تطبيق Expo

الـ Live Activities حفلة خاصة بـ iOS فقط. تعمل بواسطة ActivityKit، وهو إطار عمل مبني على Swift، ما يعني أنك ستكتب كودًا native شئت أم أبيت. وبالنسبة لتطبيق Expo، هذا أشبه بمحاولة إقناع سمكة بتسلق شجرة: ممكن، لكنه سيتطلب بعض الجهد. هنا تتدخل expo-apple-targets كمرشد متمرس، فتوفر إطارًا لإنشاء وحدات native وامتدادات widget من دون البدء من الصفر. وهي مبنية على نظام الوحدات في Expo ([Expo Modules API](https://docs.expo.dev/modules/module-api/))، الذي يتيح لك كتابة كود native بلغة Swift وإتاحته لـ JavaScript، فتصبح العملية كلها أقل إيلامًا من علاج قناة الجذر عند طبيب الأسنان.

## إعداد المشروع

لم تكن البداية نزهة تمامًا، لكن expo-apple-targets جعلتها ممكنة. هكذا بدأت:

- **تثبيت expo-apple-targets**: أمر سريع npm install expo-apple-targets كان كافيًا للانطلاق. ملف README الخاص بالحزمة كنز حقيقي، يرشدك إلى إضافة امتداد widget في Xcode وتحديث app.json بصلاحية الـ Live Activity (com.apple.developer.activitykit).

- **إعداد الوحدة الـ Native**: استخدمت نظام الوحدات في Expo لإنشاء وحدة Swift تتواصل مع ActivityKit. يركز [توثيق Expo Modules](https://docs.expo.dev/modules/module-api/) على تعريف توقيعات دوال وأحداث واضحة، وهذا ساعدني على إتاحة دوال مثل startActivity لـ JavaScript من دون عناء.

- **امتداد الـ Widget**: هنا جاء دور SwiftUI، إذ أتاح لي تصميم شكل الـ Live Activity لشاشة القفل وDynamic Island. توفر expo-apple-targets قالبًا للـ widget، لكن كان عليّ تخصيصه ليعرض مؤقتًا يعدّ وأزرارًا تفاعلية.

- **الـ Intents**: تتيح للمستخدمين الضغط على أزرار في الـ widget لإيقاف المؤقت مؤقتًا أو استئنافه. تبسّط expo-apple-targets إعداد الـ intents، لكن ما زال عليّ تتبع بعض الإخفاقات حتى تتدفق الإشعارات بشكل صحيح.

## مؤقت يُحدَّث كل ثانية؟

![مطور ينفذ بحماس تحديث المؤقت كل ثانية، فيؤدي ذلك إلى إنهاك فوضوي للنظام بينما يعيث المؤقت فسادًا. ([مولّدة بواسطة gpt-4o](https://openai.com/index/hello-gpt-4o/))](https://cdn-images-1.medium.com/max/2048/1*Nq1a3rqsEIBCgTsAWdvgNQ.png)_مطور ينفذ بحماس تحديث المؤقت كل ثانية، فيؤدي ذلك إلى إنهاك فوضوي للنظام بينما يعيث المؤقت فسادًا. ([مولّدة بواسطة gpt-4o](https://openai.com/index/hello-gpt-4o/))_

عندما بدأت العمل على المؤقت لأول مرة، قال لي عقلي: "_حدّث الـ Live Activity كل ثانية بالوقت الحالي وحسب_". يبدو بسيطًا، أليس كذلك؟ خطأ. صادفت [نقاشًا على Reddit](https://www.reddit.com/r/iOSProgramming/comments/18n12wh/how_does_this_app_achieve_to_update_its_live/?rdt=52173) كان المطورون فيه يتحدثون عن إمكانية تحديث مؤقت الـ Live Activity. وكان الحكم بالإجماع: التحديث كل ثانية كارثة. الأمر أشبه بمحاولة تشغيل مركبة فضائية بعجلة هامستر: ستتحرك، لكنها ستحترق بسرعة. التحديثات المستمرة تُثقل المعالج وتستنزف البطارية وتجعل تطبيقك بطيئًا.

كان ذلك النقاش على Reddit جرس إنذار. وجدت Text(timerInterval:) في SwiftUI ضمن [توثيق SwiftUI](<https://developer.apple.com/documentation/swiftui/text/init(timerinterval:pausetime:countsdown:showshours:)>) من Apple، وكان اكتشافًا مذهلًا. هذا العرض يتعامل مع تحديثات المؤقت بشكل native، فيعدّ من دون الحاجة إلى تحديث الـ Live Activity كلها. الأمر أشبه بإسناد الأعمال المملة إلى iOS لتتفرغ أنت للأجزاء الممتعة.

لذا تخليت عن خطة التحديث كل ثانية واعتمدت نهج startedAt/pausedAt. وإليك لماذا هو الخيار الرابح:

- **الأداء**: بدل إطلاق تحديثات كل ثانية، أخزّن وقت بدء المؤقت (startedAt) ووقت إيقافه المؤقت (pausedAt، إذا كان متوقفًا). يستخدم الـ widget العرض Text(timerInterval:) ليعرض مؤقتًا حيًا بناءً على startedAt، وعند الإيقاف المؤقت يعرض وقتًا ثابتًا باستخدام pausedAt. هذا يقلّص استدعاءات الـ API إلى ما يقارب الصفر.

- **كفاءة البطارية**: التحديثات المتكررة مصاص دماء للبطارية. ترك SwiftUI يتولى العدّ يبقي التطبيق خفيفًا وهواتف المستخدمين سعيدة.

- **الالتزام بالـ API**: واجهات Live Activity من Apple ليست مصممة لسيل لحظي من التحديثات. إعداد startedAt/pausedAt يتوافق مع توقعات iOS، ويقلل احتمال تقييد معدل الطلبات (rate-limiting).

- **بساطة الكود**: إدارة طابعين زمنيين (timestamps) أسهل بكثير من التعامل مع سيل من التحديثات. يبقى الكود نظيفًا ومستوى التوتر عندي تحت السيطرة.

بدا هذا النهج كأنني وجدت طريقًا مختصرًا سريًا في لعبة فيديو. يعمل المؤقت بسلاسة، ويبدو رائعًا، ولا يستهلك الموارد. ونقاش Reddit ([ها هو مرة أخرى](https://www.reddit.com/r/iOSProgramming/comments/18n12wh/how_does_this_app_achieve_to_update_its_live/?rdt=52173)) يستحق ميدالية لأنه دلّني على الاتجاه الصحيح.

## قلب الـ Live Activity

لن أملّك بكل سطر من الكود، لنركز على المقتطفات الأساسية التي تجعل هذا المؤقت يعمل. سأشارك الكود المصدري الكامل على GitHub في نهاية المقال.

### الـ Struct المسمى LiveActivityAttributes

هذا الـ struct هو العمود الفقري للـ Live Activity، فهو يعرّف بياناتها وطريقة تطورها.

```swift
    struct LiveActivityAttributes: ActivityAttributes {
      public struct ContentState: Codable, Hashable {
        var startedAt: Date
        var pausedAt: Date?

        func getElapsedTimeInSeconds() -> TimeInterval {
          if let pausedAt = pausedAt {
            return pausedAt.timeIntervalSince(startedAt)
          } else {
            return Date().timeIntervalSince(startedAt)
          }
        }
        func isRunning() -> Bool {
          return pausedAt == nil
        }
        func getFormattedElapsedTime() -> String {
          let elapsed = getElapsedTimeInSeconds()
          let totalSeconds = Int(elapsed)
          let hours = totalSeconds / 3600
          let minutes = (totalSeconds % 3600) / 60
          let seconds = totalSeconds % 60
          if hours > 0 {
            return String(format: "%d:%02d:%02d", hours, minutes, seconds)
          } else {
            return String(format: "%d:%02d", minutes, seconds)
          }
        }
        func getFutureDate() -> Date {
          return Date().addingTimeInterval(365 * 24 * 60 * 60)
        }
      }
      var activityName: String
      var activityIcon: String
    }
```

هذا أشبه بالحمض النووي للـ Live Activity. يحتوي LiveActivityAttributes الخارجي على البيانات الثابتة: activityName (مثل "Workout") وactivityIcon (مثل "RUNNING")، وتُضبط عند بدء النشاط. أما ContentState الداخلي فهو مكان الحدث، إذ يتتبع startedAt (وقت بدء المؤقت) وpausedAt (وقت إيقافه المؤقت، إن حدث). والدوال المساعدة هي النجوم الحقيقية هنا:

- getElapsedTimeInSeconds() تحسب المدة التي عمل فيها المؤقت، فتتوقف عند pausedAt إذا كان متوقفًا، أو تستخدم الوقت الحالي إذا كان نشطًا. هذا يبقي المنطق محكمًا وقابلًا لإعادة الاستخدام.

- isRunning() فحص بسيط: إذا كانت قيمة pausedAt تساوي null، فالمؤقت يعمل. طريقة نظيفة لتجنب فحوصات حالة فوضوية في أماكن أخرى.

- getFormattedElapsedTime() تحوّل الثواني إلى نص جميل بصيغة "MM:SS" أو "HH:MM:SS" للـ widget. أضفت دعم الساعات بعد أن أدركت أن بعض المستخدمين قد يقومون بتمارين طويلة جدًا مثل الماراثون.

- getFutureDate() تضبط تاريخًا بعد عام من الآن، وأمرره إلى Text(timerInterval:) ليعمل المؤقت إلى أجل غير محدد من دون القلق بشأن تاريخ نهاية.

أحب كيف يبقي هذا الـ struct الأمور منظمة. إنه أشبه بحقيبة ظهر محزومة جيدًا: كل ما تحتاج إليه، ولا شيء لا تحتاج إليه. والتوافق مع Codable وHashable يسهّل تحويله إلى صيغة قابلة للنقل (serialize) من أجل التحديثات واستخدامه في SwiftUI، وكان ذلك منقذًا عند مزامنة الحالة بين الوحدة والـ widget.

### بدء الـ Live Activity

الدالة startActivity هي حيث يبدأ السحر، فهي تطلق Live Activity جديدة.

```swift
    AsyncFunction("startActivity") { (activityName: String, activityIcon: String) -> String in
        if #available(iOS 16.2, *) {
            await self.endAllActivities()
            self.startedAt = Date()
            self.pausedAt = nil
            if !ActivityAuthorizationInfo().areActivitiesEnabled {
                return ""
            }
            let attributes = LiveActivityAttributes(activityName: activityName, activityIcon: activityIcon)
            let contentState = LiveActivityAttributes.ContentState(startedAt: self.startedAt!, pausedAt: nil)
            do {
                let activity = try Activity.request(attributes: attributes, content: .init(state: contentState, staleDate: nil), pushType: nil)
                self.currentActivityId = activity.id
                self.sendTimerUpdateEvent()
                return activity.id
            } catch {
                throw error
            }
        }
        return ""
    }
```

هذه الدالة هي الشرارة التي تشعل النار. تُتاح لـ JavaScript عبر نظام الوحدات في Expo، فيستطيع تطبيق React Native استدعاءها مع اسم وأيقونة. وإليك ما تفعله:

- تتحقق من أن الإصدار iOS 16.2 أو أحدث، فالـ Live Activities غير موجودة قبله.

- تستدعي endAllActivities() لإزالة أي أنشطة موجودة. يسمح iOS بعدة Live Activities، لكنني أردت نشاطًا واحدًا في كل مرة لتجنب الالتباس.

- تضبط startedAt على الوقت الحالي وتمسح pausedAt، استعدادًا لتشغيل المؤقت.

- تتحقق من أن الـ Live Activities مفعّلة (يستطيع المستخدمون تعطيلها من الإعدادات، وهذا أربكني في البداية).

- تبني LiveActivityAttributes بالاسم والأيقونة المقدّمين، وContentState بوقت البدء.

- تطلب نشاطًا جديدًا عبر Activity.request، فتعطيني كائن Activity بمعرّف فريد.

- تخزّن المعرّف، وتطلق حدث تحديث إلى JavaScript، وتعيد المعرّف ليتمكن التطبيق من تتبعه.

### إيقاف المؤقت مؤقتًا

تتولى الدالة performPause الإيقاف المؤقت للمؤقت، فتحدّث حالة الـ Live Activity.

```swift
    private func performPause(activityId: String?) async -> Bool {
        guard #available(iOS 16.2, *), self.pausedAt == nil else {
            return false
        }
        let targetId = activityId ?? self.currentActivityId
        guard let targetId = targetId else {
            return false
        }
        guard let activity = await self.findActivityById(targetId) else {
            return false
        }
        guard let currentStartedAt = self.startedAt else {
            return false
        }
        let now = Date()
        self.pausedAt = now
        let contentState = LiveActivityAttributes.ContentState(startedAt: currentStartedAt, pausedAt: self.pausedAt)
        await activity.update(using: contentState)
        self.sendTimerUpdateEvent()
        return true
    }
```

هنا يتألق نهج startedAt/pausedAt. عندما يوقف المستخدم المؤقت (من التطبيق أو من الـ widget)، تقوم هذه الدالة بما يلي:

- تتحقق من أننا على iOS 16.2 وأن المؤقت ليس متوقفًا أصلًا (لا يُسمح بالإيقاف المزدوج).

- تأخذ معرّف النشاط، وتعود إلى currentActivityId إذا لم يُقدَّم معرّف.

- تجد النشاط باستخدام findActivityById التي تبحث بين الأنشطة النشطة.

- تضبط pausedAt على الوقت الحالي، فيتجمد المؤقت.

- تنشئ ContentState جديدًا بقيمة startedAt الأصلية وقيمة pausedAt الجديدة.

- تحدّث النشاط عبر activity.update، فتخبر الـ widget بعرض الوقت المتوقف.

- ترسل حدثًا إلى JavaScript لإبقاء واجهة التطبيق متزامنة.

المنطق هنا كله يدور حول الدقة. كل فحص (مثل pausedAt == nil) موجود لمنع حالات حدّية غريبة، مثل إيقاف نشاط غير موجود. اعتمدت على [توثيق Expo Modules](https://docs.expo.dev/modules/overview/) في التعامل مع الأحداث، مستخدمًا sendEvent لدفع التحديثات إلى JavaScript. النسخ الأولى من هذه الدالة لم تكن تتحقق من startedAt، ما أدى إلى عرض غريب للمؤقت. والدرس المستفاد: احمِ حالتك دائمًا.

## عرض شاشة القفل

الـ LockScreenLiveActivityView هو ما يراه المستخدمون عندما تكون هواتفهم مقفلة، ولا بد أن يبدو أنيقًا.

![Live Activity على شاشة القفل](https://cdn-images-1.medium.com/max/2000/1*IZ1ZSG7_99jfTMBJosePGQ.png)_Live Activity على شاشة القفل_

```swift
    struct LockScreenLiveActivityView: View {
        let context: ActivityViewContext<LiveActivityAttributes>
        var body: some View {
            ZStack {
                Color.black.opacity(0.8)
                    .clipShape(RoundedRectangle(cornerRadius: 16))
                HStack(spacing: 16) {
                    VStack(alignment: .leading, spacing: 12) {
                        HStack(spacing: 8) {
                            ActivityIcon(activityIcon: mapJSIconToSFSymbol(context.attributes.activityIcon),
                                        themeColor: .white,
                                        size: 18)
                            Text(context.attributes.activityName)
                                .font(.headline)
                                .foregroundColor(.white)
                        }
                        VStack(alignment: .leading, spacing: 4) {
                            if !context.state.isRunning() {
                                Text(context.state.getFormattedElapsedTime())
                                    .font(.system(size: 34, weight: .semibold, design: .rounded))
                                    .foregroundColor(.white)
                                    .fontWeight(.medium)
                                    .monospacedDigit()
                            } else {
                                Text(timerInterval: context.state.startedAt...context.state.getFutureDate(),
                                     pauseTime: nil,
                                     countsDown: false,
                                     showsHours: false)
                                    .font(.system(size: 34, weight: .semibold, design: .rounded))
                                    .foregroundColor(.white)
                                    .fontWeight(.medium)
                                    .monospacedDigit()
                            }
                        }
                    }
                    .frame(maxHeight: .infinity, alignment: .center)
                    Spacer()
                    VStack {
                        Spacer()
                        if context.state.isRunning() {
                            Button(intent: PauseIntent()) {
                                ZStack {
                                    Circle()
                                        .fill(Color(hex: "#007bff"))
                                        .frame(width: 44, height: 44)
                                    Image(systemName: "pause.fill")
                                        .font(.system(size: 18, weight: .bold))
                                        .foregroundColor(.white)
                                }
                            }
                            .buttonStyle(PlainButtonStyle())
                        } else {
                            HStack(spacing: 8) {
                                Button(intent: CompleteIntent()) {
                                    ZStack {
                                        Circle()
                                            .fill(Color(hex: "#28a745"))
                                            .frame(width: 44, height: 44)
                                        Image(systemName: "checkmark")
                                            .font(.system(size: 16, weight: .bold))
                                            .foregroundColor(.white)
                                    }
                                }
                                .buttonStyle(PlainButtonStyle())
                                Button(intent: ResumeIntent()) {
                                    ZStack {
                                        Circle()
                                            .fill(Color(hex: "#007bff"))
                                            .frame(width: 44, height: 44)
                                        Image(systemName: "play.fill")
                                            .font(.system(size: 18, weight: .bold))
                                            .foregroundColor(.white)
                                    }
                                }
                                .buttonStyle(PlainButtonStyle())
                            }
                        }
                        Spacer()
                    }
                }
                .padding(16)
            }
        }
    }
```

هذا هو القلب المرئي للـ Live Activity، وهنا تستعرض SwiftUI قوتها فعلًا. ينقسم العرض إلى جانبين:

- **الجانب الأيسر**: يعرض اسم النشاط وأيقونته والمؤقت. إذا كان المؤقت يعمل، يتولى Text(timerInterval:) العمل الثقيل، فيعدّ تصاعديًا من startedAt حتى عام من الآن (بفضل getFutureDate). وإذا كان متوقفًا، يعرض وقتًا ثابتًا من getFormattedElapsedTime. يبقي المعدّل .monospacedDigit() الأرقام واضحة، وعدّلت الخط ليكون عريضًا وسهل القراءة.

- **الجانب الأيمن**: يتولى الأزرار. عندما يعمل المؤقت يظهر زر إيقاف مؤقت أزرق. وعندما يتوقف تحصل على علامة صح خضراء لفتح التطبيق وزر تشغيل أزرق للاستئناف. كل زر يطلق intent تلتقطه الوحدة الـ native وتعالجه.

## الغوص في [Dynamic Island](https://developer.apple.com/design/human-interface-guidelines/live-activities#The-Dynamic-Island)

![عرض Dynamic Island](https://cdn-images-1.medium.com/max/2000/1*iqy0d6FZe9UU0Tce7qCDug.png)_عرض Dynamic Island_

يعرّف هذا المقتطف طريقة ظهور الـ Live Activity في أوضاع Dynamic Island الثلاثة: الموسّع (العرض الكامل)، والمضغوط (compact)، والأدنى (minimal).

```swift
    dynamicIsland: { context in
      DynamicIsland {
        DynamicIslandExpandedRegion(.leading) {
          VStack(alignment: .leading, spacing: 8) {
            HStack(spacing: 8) {
              ActivityIcon(activityIcon: mapJSIconToSFSymbol(context.attributes.activityIcon),
                          themeColor: .white,
                          size: 18)

              Text(context.attributes.activityName)
                .foregroundColor(.white)
                .font(.system(size: 16, weight: .semibold))
            }

            if !context.state.isRunning() {
              Text(context.state.getFormattedElapsedTime())
                .font(.system(size: 32, weight: .bold, design: .rounded))
                .foregroundColor(.white)
                .fontWeight(.medium)
                .monospacedDigit()
            } else {
              Text(timerInterval: context.state.startedAt...context.state.getFutureDate(),
                   pauseTime: nil,
                   countsDown: false,
                   showsHours: false)
                .font(.system(size: 32, weight: .bold, design: .rounded))
                .foregroundColor(.white)
                .fontWeight(.medium)
                .monospacedDigit()
            }
          }
          .padding(.leading, 8)
        }

        DynamicIslandExpandedRegion(.trailing) {
          VStack {
            Spacer()

            if context.state.isRunning() {
              Button(intent: PauseIntent()) {
                ZStack {
                  Circle()
                    .fill(Color(hex: "#007bff"))
                    .frame(width: 44, height: 44)
                  Image(systemName: "pause.fill")
                    .font(.system(size: 18, weight: .bold))
                    .foregroundColor(.white)
                }
              }
              .buttonStyle(PlainButtonStyle())
              .padding(.horizontal, 8)
            } else {
              HStack(spacing: 8) {
                Button(intent: CompleteIntent()) {
                  ZStack {
                    Circle()
                      .fill(Color(hex: "#28a745"))
                      .frame(width: 44, height: 44)
                    Image(systemName: "checkmark")
                      .font(.system(size: 16, weight: .bold))
                      .foregroundColor(.white)
                  }
                }
                .buttonStyle(PlainButtonStyle())

                Button(intent: ResumeIntent()) {
                  ZStack {
                    Circle()
                      .fill(Color(hex: "#007bff"))
                      .frame(width: 44, height: 44)
                    Image(systemName: "play.fill")
                      .font(.system(size: 18, weight: .bold))
                      .foregroundColor(.white)
                  }
                }
                .buttonStyle(PlainButtonStyle())
              }
            }
          }
          .frame(maxHeight: .infinity)
        }
      } compactLeading: {
        HStack(spacing: 4) {
          ActivityIcon(activityIcon: mapJSIconToSFSymbol(context.attributes.activityIcon),
                      themeColor: .white,
                      size: 16)

          Text(context.attributes.activityName)
            .foregroundColor(.white)
            .font(.system(size: 12))
            .lineLimit(1)
            .truncationMode(.tail)
        }
      } compactTrailing: {
        if !context.state.isRunning() {
          Text(context.state.getFormattedElapsedTime())
            .foregroundColor(.white)
            .monospacedDigit()
            .font(.system(size: 12, weight: .medium))
        } else {
          Text(timerInterval: context.state.startedAt...context.state.getFutureDate(),
               pauseTime: nil,
               countsDown: false,
               showsHours: false)
            .foregroundColor(.white)
            .monospacedDigit()
            .font(.system(size: 12, weight: .medium))
        }
      } minimal: {
        ActivityIcon(activityIcon: mapJSIconToSFSymbol(context.attributes.activityIcon),
                    themeColor: .white,
                    size: 12)
      }
    }
```

- [\*\*الوضع الموسّع](https://developer.apple.com/design/human-interface-guidelines/live-activities#Expanded-presentation)\*\*: يظهر عند الضغط المطوّل، وينقسم إلى .leading و.trailing. يرصّ الجانب الأول الأيقونة (مثل شكل شخص يجري) والاسم ("Workout") مع مؤقت كبير، ثابت عند الإيقاف (getFormattedElapsedTime) ويعدّ عند النشاط (Text(timerInterval:)). ويحتوي الجانب الآخر على الأزرار: زر إيقاف مؤقت أزرق أثناء التشغيل، أو علامة صح خضراء (فتح التطبيق) وزر تشغيل أزرق (استئناف) عند الإيقاف. عدّلت الخطوط والهوامش لتناسب انحناءات الـ Island.

- [\*\*الوضع المضغوط](https://developer.apple.com/design/human-interface-guidelines/live-activities#Compact-presentation)\*\*: عندما تضيق المساحة، يعرض compactLeading أيقونة صغيرة واسمًا مختصرًا، بينما يعرض compactTrailing المؤقت (ثابتًا أو يعدّ). يبقي .lineLimit(1) الاسم مرتبًا، ويضمن خط بحجم 12 نقطة سهولة القراءة.

- [\*\*الوضع الأدنى](https://developer.apple.com/design/human-interface-guidelines/live-activities#Minimal-presentation)\*\*: ضيق للغاية، فهو مجرد أيقونة بحجم 12 نقطة، مثل دمبل، لتقول "المؤقت ما زال هنا". بسيط لكنه فعّال.

## المجلد \_shared: لماذا هو مهم

![نظرة عامة على المجلد _shared](https://cdn-images-1.medium.com/max/2000/1*OdZlqw2AXJeTakpTlghLDQ.png)_نظرة عامة على المجلد \_shared_

المجلد \_shared في [expo-apple-targets](https://github.com/EvanBacon/expo-apple-targets?tab=readme-ov-file#_shared) مجلد في المستوى الأعلى صُمم لربط الكود الأساسي بكل من الـ target الرئيسي لتطبيقك والـ targets الفرعية، مثل widget الـ Live Activity.

الامتدادات، مثل الـ widgets، تعمل في عمليات (processes) منفصلة، وتحتاج إلى ربط ملفات معينة بالـ target الخاص بها وبالـ target الخاص بالتطبيق الرئيسي معًا. يضمن المجلد \_shared ربط هذه الملفات تلقائيًا بالاثنين، فيلغي الحاجة إلى الإعداد اليدوي. وفي حالة المؤقت، وضعت الـ struct المسمى LiveActivityAttributes هنا، فضمنت أن يتشارك التطبيق والـ widget حالة المؤقت نفسها (startedAt وpausedAt) من دون مشكلات في المزامنة.

## فتح التطبيق من widget الـ Live Activity

يتيح CompleteIntent للمستخدمين الضغط على زر علامة الصح في widget الـ Live Activity لفتح التطبيق، إشارةً إلى أنهم انتهوا من المؤقت. تفاعل بسيط لكنه حاسم لإنهاء التمرين.

```swift
    import AppIntents
    import WidgetKit

    @available(iOS 16.2, *)
    struct CompleteIntent: AppIntent, LiveActivityIntent {
        static var title: LocalizedStringResource = "Complete Exercise"
        static var description: IntentDescription = "Opens the app to complete the exercise"
        static var openAppWhenRun: Bool = true

        init() {}
        func perform() async throws -> some IntentResult {
            NotificationCenter.default.post(name: Notification.Name("completeActivityFromWidget"), object: nil)

            return .result()
        }
    }
```

عندما يضغط المستخدم على علامة الصح الخضراء، يُطلق هذا الـ intent وينشر إشعار completeActivityFromWidget. تلتقطه الوحدة الـ native، فتطلق الحدث onWidgetCompleteActivity إلى JavaScript، ويفتح iOS التطبيق بفضل [openAppWhenRun](https://developer.apple.com/documentation/appintents/openurlintent/openappwhenrun): true.

## التعامل مع ضغطات المستخدم عبر الـ Intents

الـ PauseIntent واحد من الـ intents التي تجعل الـ widget تفاعليًا.

![الـ Intents في Live Activity على شاشة القفل](https://cdn-images-1.medium.com/max/2000/1*k2nzvHgwgqj6tFESIFcmbw.png)_الـ Intents في Live Activity على شاشة القفل_

```swift
    import AppIntents
    import WidgetKit

    @available(iOS 16.2, *)
    struct PauseIntent: AppIntent, LiveActivityIntent {
      static var title: LocalizedStringResource = "Pause Timer"
      static var description: IntentDescription = "Pauses the current timer."

      init() {}

      func perform() async throws -> some IntentResult {
        NotificationCenter.default.post(name: Notification.Name("pauseTimerFromWidget"), object: nil)
        return .result()
      }
    }
```

يُطلق هذا الـ intent عندما يضغط المستخدم على زر الإيقاف المؤقت في الـ widget. إنه بسيط جدًا لكنه قوي:

- ينشر إشعارًا (pauseTimerFromWidget) تلتقطه الوحدة الـ native عبر setupNotificationObservers.

- ثم تشغّل الوحدة performPause، فتحدّث حالة الـ Live Activity وتُبلغ JavaScript.

الجميل هنا كيف تنشئ الـ intents حلقة سلسة: المستخدم يضغط، فيُطلق الـ intent، فتحدّث الوحدة الحالة، فيبقى التطبيق متزامنًا. جعلت expo-apple-targets إعداد الـ intents سهلًا جدًا بتوفير قالب، لكن ما زال عليّ تتبع حالة لم تُسجَّل فيها الضغطات، واتضح أنني أخطأت في كتابة اسم إشعار. كلاسيكي. ساعدني [توثيق Expo Modules](https://docs.expo.dev/modules/overview/) على فهم كيفية التعامل مع الأحداث التي تطلقها إجراءات native، وكان ذلك أساسيًا لنجاح الأمر.

## أحداث تتحدث مع JavaScript

![](https://cdn-images-1.medium.com/max/2000/1*F5GUBNYqWxbZbLU8-LZ0Ug.png)

الأحداث في القسم التالي هي الطريقة التي تبقي بها الوحدة الـ native تطبيق React Native متزامنًا مع حالة الـ Live Activity، باستخدام نظام الأحداث في Expo.

### onWidgetCompleteActivity

يُطلق هذا الحدث عندما يضغط المستخدم على علامة الصح لإكمال النشاط، ويطلقه CompleteIntent.

```swift
    @objc func completeIntentHandler(_ notification: Notification) {
        guard let currentId = self.currentActivityId, self.startedAt != nil else {
            return
        }

        let elapsed = self.calculateElapsedTime()

        sendEvent("onWidgetCompleteActivity", [
            "activityId": currentId,
            "elapsedTime": Int(elapsed)
        ])
    }
```

يلتقط completeIntentHandler إشعار completeActivityFromWidget، ويحسب الوقت المنقضي، ويرسل الحدث onWidgetCompleteActivity إلى JavaScript مع معرّف النشاط والثواني المنقضية. ويستطيع JavaScript بعد ذلك تحديث واجهة التطبيق أو تسجيل اكتمال التمرين.

### onLiveActivityUpdate

يُطلق هذا الحدث كلما تغيّرت حالة المؤقت (مثل الإيقاف المؤقت أو الاستئناف).

```swift
    private func sendTimerUpdateEvent() {
        guard let currentId = self.currentActivityId else { return }
        guard self.startedAt != nil else { return }

        let state = self.pausedAt == nil ? "active" : "paused"
        let elapsed = self.calculateElapsedTime()

        sendEvent("onLiveActivityUpdate", [
            "state": state,
            "elapsedTime": Int(elapsed),
            "activityId": currentId
        ])
    }
```

يُستدعى بعد تغيّر الحالة (كما في performPause أو performResume)، ويرسل الحدث onLiveActivityUpdate مع الحالة الحالية ("active" أو "paused") والوقت المنقضي ومعرّف النشاط. ويستمع JavaScript لهذا الحدث لإبقاء واجهة المؤقت في التطبيق متزامنة مع الـ widget.

ينشئ الحدثان معًا حلقة تغذية راجعة محكمة بين الوحدة الـ native وJavaScript.

## لماذا يهم كل هذا

هذه الـ Live Activity ليست مجرد مؤقت، بل ميزة تجعل تطبيقي يبدو كمواطن أصيل في iOS. وإليك لماذا هي مهمة:

- **تفاعل المستخدمين**: عرض مؤقت على شاشة القفل أو في Dynamic Island يبقي المستخدمين مرتبطين بالتطبيق من دون قطع تركيزهم. وهذا مثالي للتمارين، حيث كل ثانية مهمة.

- **لمسة native**: التصميم النظيف للـ widget وأزراره التفاعلية تجعل التطبيق يبدو جزءًا أصيلًا من iOS، لا فكرة لاحقة من تطبيق متعدد المنصات.

- **الأداء**: نهج startedAt/pausedAt، المدعوم بـ Text(timerInterval:)، يضمن عمل المؤقت بسلاسة من دون استنزاف البطارية أو بلوغ حدود الـ API.

كانت expo-apple-targets و[Expo Modules API](https://docs.expo.dev/modules/module-api/) البطلين المجهولين هنا، إذ وفرتا إطارًا متينًا للربط بين JavaScript وSwift. وتركيز التوثيق على تعريفات دوال نظيفة والتعامل مع الأحداث أبقى الكود الخاص بي منظمًا وسهل الصيانة.

## أفكار أخيرة

تضيف هذه الـ Live Activity إحساسًا سلسًا وnative إلى التطبيق، إذ تعرض تحديثات لحظية مباشرة على شاشة القفل وفي Dynamic Island. وبفضل expo-apple-targets وExpo Modules API ورؤى المجتمع (نعم، بما فيها نقاشات Reddit)، كان تحويلها إلى واقع مباشرًا إلى حد كبير. الـ Live Activities طريقة قوية لجعل التطبيقات تبدو أكثر ارتباطًا وحيوية.

إليك رابط GitHub للمستودع الكامل للكود المصدري 👉🏻 [https://github.com/tarikfp/expo-live-activity-timer](https://github.com/tarikfp/expo-live-activity-timer)

