الحفظ الدائم في Tiptap: JSON وHTML والحالة التعاونية

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

في Tiptap، ابدأ بصيغة JSON للمستند القابل للتحرير. استخدم HTML عندما يحتاج النظام المستهلك إلى محتوى معروض أو إلى تبادل المحتوى. وإذا كان المنتج يستخدم التعاون عبر Yjs، فاحفظ حالته الثنائية حفظًا دائمًا. إن التعامل مع هذه الصيغ بوصفها نسخًا احتياطية قابلة للتبادل يترك أسئلة كثيرة بلا إجابة.

السؤال الأصعب هو ما الذي يجب أن يبقى عند إعادة فتح المستند. فقد تبدو الملاحظة صحيحة رغم فقدان علاقة يعتمد عليها منتجك. يستخدم هذا الدليل الخاص بـ Tiptap 3.x جدول قرارات وقائمة التحقق 3R التي تقترحها Optijara لتحديد هذا العقد. تُجرى عمليات التحقق في بيئتك الخاصة؛ فهذا دليل لاتخاذ القرار يستند إلى الوثائق، ولم تُنفّذ فيه تجربة تثبيت أو تعاون.

اختر التمثيل الذي يحتاج إليه منتجك

JSON للمستندات القابلة للتحرير، وHTML للعرض والتبادل

توصي Tiptap بالحفظ الدائم بصيغة JSON لمرونتها وسهولة تحليلها. كما تتيح إجراء تعديلات خارجية دون الحاجة إلى محلل HTML آخر. ويمكن حفظ HTML أيضًا. لكن سهولة قراءته لا تخبرك كثيرًا عما إذا كان المحرر المستقبِل يستطيع استعادة المحتوى بأمانة.

وفقًا لـ واجهة برمجة مثيل المحرر، تُرجع editor.getJSON() وeditor.getHTML() المستند الحالي. تمنحك JSON شجرة المستند. وهي لا تلتقط جلسة المحرر كاملة، بما فيها التحديد أو سجل التراجع، ولا يمكن أن تحل محل الحالة التعاونية. وينطبق على HTML الفصل نفسه بين المستند والجلسة.

للعرض دون محرر، تحقق من الحزمة المستوردة. يوضح مرجع أدوات HTML أن generateHTML من @tiptap/core مخصص للمتصفح فقط. أما إصدار @tiptap/html فيدعم الخادم والمتصفح معًا. وكلاهما يتطلب الإضافات ذات الصلة. راجع سلامة المخرجات بصورة مستقلة؛ فتوليد HTML لا يقدم ضمانًا شاملًا لتنقيته من المحتوى غير الآمن.

حالة Yjs الثنائية للحفظ الدائم في التعاون

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

تعامل مع مخطط الإضافات بوصفه جزءًا من عقد المحتوى المحفوظ

تحقق من العقد المخصصة وعلامات التنسيق والمستندات الأقدم

تصف وثائق مخطط Tiptap عقدًا مبنيًا على الإضافات المسجلة. وتحدد تلك الإضافات العقد وعلامات التنسيق المسموح بها، إلى جانب سماتها وتداخلها. وقد يحتوي JSON صحيح على بنية لا يستطيع المحرر المستقبِل تمثيلها.

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

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

افهم ما يستطيع فحص المحتوى كشفه وما يعجز عنه

في مرجع المخطط، يتطلب enableContentCheck تفعيلًا اختياريًا، وقيمته الافتراضية false. فحص JSON أقوى؛ فقد يفوت فحص HTML علامات تنسيق غير مدعومة تُزال بعد ذلك. ضع هذا القيد ضمن معايير قبول الاستعادة.

تختلف معالجة التهيئة عبر onContentError عن خيار الأمر errorOnInvalidContent. يستخدم نمط معالجة أخطاء التعاون في الوثائق disableCollaboration() لإزالة إضافة التعاون. ويستخدم أيضًا editor.setEditable(false, false) لإيقاف الإدخال دون إصدار تحديث. يمنع ذلك مزامنة المحتوى الذي أُزيلت منه عناصر، لكنه لا يستطيع إعادة بناء ما فُقد.

احتفظ ببيانات المحتوى الأصلية خارج المحرر. يُعد schemaVersion الذي يديره التطبيق، مقرونًا بقواعد ترحيل خضعت للمراجعة، خيارًا مفيدًا في التصميم. لا توفر Tiptap هذا الضمان لإدارة إصدارات المستندات نيابة عنك. احتفظ بالأصل قبل قبول أي بديل ناتج عن تحويله.

منهج 3R: التمثيل والاستعادة وإقرار الحفظ

3R قائمة تحقق تحريرية تقترحها Optijara للحفظ الدائم دون تعاون. وهي ليست ميزة رسمية في Tiptap ولا طريقة نشر جرى التحقق من صحتها. استخدمها لطرح أسئلة مستقلة بشأن المحتوى الذي تخزنه وطريقة تحميله. ثم حدد ما يُعد حفظًا مقبولًا.

التمثيل: التقط المستند الذي تنوي حفظه حفظًا دائمًا

اختر تمثيلًا مرجعيًا وسجل إعدادات الإضافات المتوافقة معه. احتفظ بهوية المستند خارج شجرة Tiptap، ما لم يكن تطبيقك يمثل البيانات الوصفية داخلها صراحةً. وينتمي إصدار المخطط ومراجعة الخادم الخلفي إلى عقد التطبيق أيضًا. تؤدي مراجعة التطبيق وظيفة مختلفة عن سمة العقدة أو إصدار الحزمة.

بالنسبة إلى الملاحظات المبنية من مستندات مستخرجة، أبقِ هوية المصدر منفصلة عن النص القابل للتحرير. يتناول دليل Docling للمحتوى المنظم وأصل المصادر هذا الحد في مرحلة إدخال المحتوى السابقة. استخدمه لتحديد مراجع المصادر التي تحتاج إليها الملاحظات، وليس بوصفه مواصفة للحفظ الدائم في المحرر.

يلخص JSON التالي الخيارات المقترحة بصيغة قابلة للقراءة آليًا. وهو ملخص تحريري، لا يدل على وجود طلب حفظ قابل للتنفيذ أو اختبار مكتمل.

{
  "framework": "3r",
  "representation": "editable-json-compatible-extensions",
  "restore": "reject-incompatible-content-retain-original",
  "receipt": "acknowledge-applicable-backend-revision",
  "collaboration": "persist-yjs-binary-when-required"
}

الاستعادة: استبدل المحتوى عن قصد

يوضح مرجع أمر setContent أن الأمر يستبدل المستند. في 3.x، تكون القيمة الافتراضية لـ emitUpdate هي true؛ بينما كانت في v2 تساوي false. راجع مرجع هذا الأمر قبل نسخ الصيغة المختصرة من صفحة الحفظ الدائم العامة.

المثال أدناه توضيحي ولم يُنفّذ. وهو يفترض وجود editor في Tiptap 3.x يدعم المستندات والفقرات، إلى جانب النص. وتطابق بيانات المحتوى فيه تلك الإعدادات. ستظل بحاجة إلى تنفيذ العمل المتعلق بالشبكة وقاعدة البيانات.

const savedContent = {
  type: 'doc',
  content: [{
    type: 'paragraph',
    content: [{ type: 'text', text: 'saved-note' }],
  }],
}

editor.commands.setContent(savedContent, {
  emitUpdate: false,
  errorOnInvalidContent: true,
})

يمكن أن يمنع ضبط emitUpdate: false حفظًا تلقائيًا ينشأ عن التحديث أثناء استعادة المحتوى. وتظل مستمعات الأحداث الأخرى في التطبيق بحاجة إلى الفحص، كما تبقى مسؤولية ترتيب عمليات الكتابة غير المتزامنة على عاتقك. إذا رُفضت الاستعادة، فأبقِ بيانات المحتوى الأصلية متاحة للاسترداد. لا تستبدلها بمحتوى قُبل جزئيًا.

يحدد مرجع الأحداث معاني مختلفة لهذه الأحداث. يتعلق update بتغييرات المحتوى. ويتعلق selectionUpdate بالتحديد، بينما يغطي transaction تغييرات الحالة الناتجة عن أي عملية. استخدم update أو دالة رد النداء الموثقة onUpdate للحفظ الناتج عن تغييرات المحتوى، وتحقق مما تفعله مستمعات الأحداث الأخرى فعليًا.

إقرار الحفظ: ميّز بين التعديلات المحلية وعمليات الحفظ المقبولة

تقدم شارة «محفوظ» وعدًا. وبموجب عقد التطبيق المقترح هذا، ينبغي أن تعني أن الخادم الخلفي قبل المراجعة المعنية، وأنه لا يوجد تعديل محلي أحدث قيد الانتظار. تحويل المحتوى إلى صيغة قابلة للتخزين أو بدء طلب لا يكفي لتقديم هذا الوعد.

حدد كل انتقال قبل تنفيذ تدفق الحالات الموصى به.

يجب أن يترك إقرار حفظ لقطة أقدم أي تعديل أحدث موسومًا بأنه غير محفوظ. وإلا فستدّعي الواجهة قبول محتوى لم يقر الخادم الخلفي بحفظه.

استخدم عمليات التحقق من المراجعة المتوقعة في الخادم الخلفي، أو اختر سياسة أخرى صريحة للتعارضات. يساعد تجميع الطلبات عبر تأخيرها حتى تهدأ التغييرات في جدولة الطلبات؛ لكنه لا يستطيع تحديد المراجعة التي ينبغي للخادم قبولها. عند الفشل، احتفظ بالمحتوى المعلّق. أظهر التعارض، واشترط استردادًا مقصودًا قبل استبدال العمل المحلي بلقطة أقدم أُقر بحفظها. تخص هذه القرارات التطبيق، وتتجاوز واجهة أحداث Tiptap.

أبقِ حالة Yjs التعاونية منفصلة عن التمثيلات المشتقة بصيغة JSON

احفظ الحالة الثنائية حفظًا دائمًا، بدلًا من إعادة بناء مستند عند كل إعادة اتصال

تتطلب وثائق الحفظ الدائم في Hocuspocus تخزين حالة المستند المرمزة بـ Yjs بوصفها بيانات ثنائية من نوع Uint8Array. وتحذيرها محدد. قد يؤدي تخزين Y.Doc بصيغة JSON وإعادة إنشاء بيانات Yjs الثنائية عند اتصال مستخدم إلى إرباك الدمج وتكرار المحتوى عند الاتصالات الجديدة.

احتفظ بـ JSON بوصفه تمثيلًا مشتقًا إضافيًا إذا احتاج المنتج إليه. احفظ الحالة التعاونية الفعلية حفظًا دائمًا لإعادة الاتصال، وراعِ هذا التمييز في إجراءات النسخ الاحتياطي والاستعادة.

توثق Hocuspocus استخدام onStoreDocument للتخزين وonLoadDocument للتحميل. وتوفر إضافات قواعد البيانات طبقة تجريد أخرى. تحدد هذه الواجهات حد الحفظ الدائم؛ لكنها لا تمثل إعدادًا كاملًا للخادم. ولا يكفي تدفق الحفظ التلقائي غير التعاوني الموضح أعلاه لهذا المسار.

قرر ما إذا كان التعاون مطلوبًا بالفعل

إذا أُضيف التعاون لاحقًا، فخطط للتحويل الأولي صراحةً. احتفظ بالأصل واختبر سلوك إعادة الاتصال في بيئتك قبل استبدال صيغة الحفظ الحالية. لا يمنحك تغيير الصيغة بصمت معايير مفيدة لقبول الترحيل.

يظل حفظ الحالة الثنائية يترك قرارات تفويض الوصول والاحتفاظ بالبيانات للتطبيق. اختبر النسخ الاحتياطية بصورة مستقلة. وراجع ترحيلات الإضافات حتى بعد إعادة اتصال ناجحة، لأن إعادة الاتصال لا تثبت التوافق مع مخطط تغير.

أخطاء تقع فيها الفرق: قائمة تحقق للحفظ والاستعادة قبل الإطلاق

اختبر أمانة المحتوى وسلوك الاستعادة

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

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

استخدم الجدول قائمة تحقق للتنفيذ، وعيّن مسؤولًا عن الملاحظات التي لم تُحسم. قد ينتج الترحيل محتوى صحيحًا مع إسقاط علاقة يحتاج إليها المنتج. ينبغي أن تفشل هذه النتيجة في استيفاء معايير قبول المنتج.

اختبر تسابق عمليات الحفظ وإعادة الاتصال التعاوني

أخّر طلبات الحفظ وغيّر ترتيبها في بيئة الاختبار. إذا كان التطبيق يستخدم المراجعات المتوقعة، فتحقق من رفض عمليات الكتابة القديمة ومن إبلاغ الواجهة عن تعارض. وتأكد أيضًا من أن قبول لقطة سابقة يُبقي تعديلًا محليًا لاحقًا موسومًا بأنه غير محفوظ.

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

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

استخدم خطة القياس المقترحة هذه للاحتفاظ بأدلة ملموسة. وهي تحدد الملاحظات المطلوب جمعها، دون ادعاء درجة أداء أو عتبة دقة.

القيود والمفاضلات التشغيلية

صحة المستند لا تعني الأمان أو دوام التخزين

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

لا يثبت نجاح عرض HTML أمانة الحفظ والاستعادة دون فقد. ضع القيد الموثق لفحص المحتوى في الحسبان، إلى جانب التحذير المتعلق بالحالة الثنائية التعاونية. لا يستطيع تحويل المحتوى إلى صيغة قابلة للتخزين توفير سياسة التعارضات في الخادم الخلفي أو ضمان دوام التخزين.

حدد نطاق عمل التنفيذ بواقعية

تستلزم الإضافات المخصصة أعمال صيانة. وتحتاج المستندات الأقدم إلى قرارات ترحيل، كما تحتاج معالجة التعارضات إلى التنفيذ والاختبار. تعني إضافة التعاون أيضًا تشغيل بنيته التحتية. خصص الموارد لهذه المسؤوليات قبل اختيار التصميم الأكثر تعقيدًا.

لا يعرض هذا الدليل وفورات مقاسة أو تحسنًا في الأداء أو نتيجة نشر. ولم يُنفّذ المقتطف البرمجي. أجرِ عمليات التحقق المقترحة على تبعياتك وعينات اختبارك قبل ادعاء التحقق من السلوك، وسجل النتائج التي لم تُحسم. تمنحك مراجعة الوثائق أساسًا للاختبار؛ لكنها ليست اختبارًا ناجحًا للتطبيق.

اختر عقدًا للحفظ الدائم، ثم اختبر الحفظ والاستعادة

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