رفتن به محتوای اصلی

پشتیبانی iCal

وضعیتِ فعلی

فیلد ical از پاسخ‌های همگام‌سازی حذف شده است و کدِ تولیدکنندهٔ آن (apps/api/src/utils/icalGenerator.ts) نیز از repo پاک شده است. هیچ مسیری خروجیِ text/calendar ندارد. این صفحه نقشهٔ راهِ آیندهٔ خروجی iCal را نگه می‌دارد.

وقتی فعال شود، سرور برای هر رویداد یک رشتهٔ کاملِ VEVENT مطابق RFC 5545 تولید و در فیلد ical برمی‌گرداند. این رشته برای خروجی به تقویم‌های خارجی — Google Calendar، تقویم اندروید، Outlook و مانند آن‌ها — است.

چه چیزی در ical هست؟​

  • UID، SUMMARY، DESCRIPTION، LOCATION
  • DTSTART و DTEND (UTC؛ برای رویدادهای تمام‌روز به‌صورت VALUE=DATE)
  • CREATED و LAST-MODIFIED
  • RRULE برای رویدادهای تکرارشونده و EXDATE برای استثناها
  • STATUS (CONFIRMED/CANCELLED) و CLASS (PUBLIC/PRIVATE) و COLOR
  • ویژگی‌های سفارشیِ X-TAGHVIMAM-* برای حفظِ متادیتای اختصاصی (نوع تقویم، منبع، وضعیت همگام‌سازی و…) هنگام خروج به سیستم‌های خارجی

فیلد ical فقط در پاسخ‌های رویداد تولید می‌شود و سرور مالکِ آن است؛ کلاینت نباید آن را بنویسد.

نمونهٔ یک رشتهٔ ical​

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Taghvimam//Calendar Sync API//EN
CALSCALE:GREGORIAN
METHOD:PUBLISH
X-WR-TIMEZONE:Asia/Tehran
X-WR-CALNAME:My Calendar
BEGIN:VEVENT
UID:event-123@taghvimam.com
SUMMARY:Team Meeting
DESCRIPTION:Weekly team sync
LOCATION:Conference Room A
DTSTART:20240115T100000Z
DTEND:20240115T110000Z
CREATED:20240101T000000Z
LAST-MODIFIED:20240101T000000Z
STATUS:CONFIRMED
CLASS:PUBLIC
X-TAGHVIMAM-SOURCE:LOCAL
X-TAGHVIMAM-CALENDAR-ID:123
X-TAGHVIMAM-SYNC-STATUS:SYNCED
END:VEVENT
END:VCALENDAR

پشتیبانی از RFC 5545 شامل این‌هاست: کانتینر VCALENDAR با متادیتای مناسب، VEVENT با property‌های استاندارد، RRULE برای تکرارها (DAILY/WEEKLY/MONTHLY/YEARLY)، EXDATE برای استثناها، منطقهٔ زمانی و رویدادهای تمام‌روز.

پسوندهای اختصاصیِ Taghvimam (X-TAGHVIMAM-*)​

Propertyکاربرد
X-TAGHVIMAM-SOURCEمنبع رویداد (LOCAL/GOOGLE/ANDROID_PROVIDER/SERVER)
X-TAGHVIMAM-SOURCE-IDنگاشت ID خارجی برای همگام‌سازی
X-TAGHVIMAM-CALENDAR-IDرابطهٔ تقویم
X-TAGHVIMAM-CALENDAR-NAMEنام تقویم
X-TAGHVIMAM-CALENDAR-TYPEJALALI یا GREGORIAN
X-TAGHVIMAM-SYNC-STATUSوضعیت همگام‌سازی (SYNCED/PENDING/CONFLICT)

یکپارچگیِ کلاینت (ical4j)​

برای خواندن ical در اندروید، کتابخانهٔ ical4j را پیشنهاد می‌کنیم:

// event از پاسخِ JSON می‌آید؛ فیلد ical را بگیرید
val icalString = event.ical

val calendar = CalendarBuilder().build(ByteArrayInputStream(icalString.toByteArray()))
for (component in calendar.components) {
    (component as? VEvent)?.let { e ->
        val summary    = e.summary?.value
        val start      = e.startDate?.date
        val end        = e.endDate?.date
        // property‌های اختصاصی:
        val source     = e.getProperty<Property>("X-TAGHVIMAM-SOURCE")?.value
        val calendarId = e.getProperty<Property>("X-TAGHVIMAM-CALENDAR-ID")?.value
        val syncStatus = e.getProperty<Property>("X-TAGHVIMAM-SYNC-STATUS")?.value
    }
}

وابستگیِ لازم: implementation 'org.mnode.ical4j:ical4j:3.2.14' (یا جدیدتر).

بهترین رویه‌ها​

وضعیتِ فعلی

این توصیه‌ها برای زمانی هستند که خروجی iCal در آینده فعال شود.

  1. از JSON و فیلد ical استفاده کنید — نیازی به مذاکرهٔ Accept نیست.
  2. ical را فقط وقتی به قابلیت‌های خاصِ iCal نیاز دارید parse کنید؛ در غیرِ این صورت مستقیماً از property‌های JSON استفاده کنید.
  3. برای تقویم‌های بزرگ، با start/end بازهٔ تاریخ را فیلتر کنید.
  4. پاسخ‌ها (و فیلد ical) را cache کنید.

رفرنس‌ها​