{"content":"\n### مقدمة\n\nاعتبارًا من الإصدار 3.2.0.beta3 من Discourse، يمكن لمكونات/سمات Discourse الاستفادة من ميزة الترحيل لتطوير وتعديل إعداداتها بسلاسة. تضمن هذه الميزة أن تحديثات السمات لا تعطل التثبيتات الحالية عن طريق التعامل مع التغييرات في الإعدادات بطريقة خاضعة للرقابة.\n\n### متى تستخدم الترحيلات\n\nالسيناريوهات الشائعة التي تكون فيها الترحيلات مفيدة بشكل خاص:\n\n- تغيير نوع الإعداد (على سبيل المثال، من سلسلة نصية مفصولة بفواصل إلى قائمة).\n- إعادة تسمية إعداد.\n- تعديل بنية أو تنسيق البيانات المخزنة في إعداد.\n\nفي هذه السيناريوهات، إذا تم تغيير نوع الإعداد أو اسمه في ملف `settings.yml` دون ترحيل مصاحب، فإن التثبيتات الحالية التي تم فيها تغيير الإعداد من القيمة الافتراضية، ستفقد التغيير الذي أجرته على الإعداد وقد تتعطل عند تحديث السمة.\n\nلضمان انتقال سلس عند تحديث إعداد سمة، يجب على مطوري السمات شحن ترحيل يوجه Discourse الأساسي حول كيفية ترحيل الحالة الحالية التي تتوافق مع الإصدار القديم من `settings.yml` إلى الإصدار الجديد.\n\n### ملفات الترحيل\n\nالترحيلات هي ملفات JavaScript موجودة في دليل `migrations/settings` الخاص بالسمة، باتباع اصطلاح التسمية `XXXX-migration-name.js`. البادئة `XXXX` هي رقم إصدار، تبدأ من `0001` وتزداد بشكل متسلسل، والتي تحدد ترتيب التنفيذ.\n\nيجب أن يكون الاسم وصفًا موجزًا لغرض الترحيل، ويقتصر على الأحرف الأبجدية الرقمية والشرطات، وأقل من 150 حرفًا. يتم تنفيذ الترحيلات بترتيب تصاعدي بناءً على القيمة الرقمية لإصداراتها.\n\nنوصي بالبدء بـ `0001` للترحيل الأول و `0002` للترحيل الثاني وما إلى ذلك. لاحظ أنه إذا كان إصدار الترحيل أقل من 1000، فيجب حشو الإصدار بأصفار بادئة لجعله 4 أرقام، حيث يجب أن يبدأ اسم ملف الترحيل بـ 4 أرقام. لنفس السبب، لا يمكن حاليًا أن يكون هناك أكثر من 9999 ترحيلًا في سمة، ولكن قد نغير ذلك في المستقبل.\n\n### دالة الترحيل\n\nميزات JavaScript القياسية [مثل](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference) الفئات والدوال والمصفوفات والخرائط وما إلى ذلك، كلها متاحة للاستخدام في الترحيلات. التوقع الوحيد من Discourse الأساسي هو أن كل ملف ترحيل يجب أن يصدر دالة افتراضية تعمل كنقطة دخول. تتلقى هذه الدالة كائن [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) يمثل إعدادات السمة المعدلة وتعيد كائن `Map` يعكس الحالة النهائية المرغوبة لجميع الإعدادات.\n\n### أمثلة\n\nإعادة تسمية إعداد سمة:\n\n```js\n// filename: 0001-rename-old-setting.js\n\nexport default function migrate(settings) {\n if (settings.has(\"old_setting_name\")) {\n settings.set(\"new_setting_name\", settings.get(\"old_setting_name\"));\n settings.delete(\"old_setting_name\");\n }\n return settings;\n}\n```\n\nيجب أن يصاحب هذا الترحيل إعادة تسمية الإعداد في ملف `settings.yml`.\n\n---\n\nتحويل إعداد سلسلة نصية مفصولة بفواصل إلى قائمة مناسبة:\n\n```js\n// filename: 0001-convert-string-setting-to-list.js\n\nexport default function migrate(settings) {\n if (settings.has(\"list_setting\")) {\n const list = settings.get(\"list_setting\").split(\",\");\n settings.set(\"list_setting\", list.join(\"|\"));\n }\n return settings;\n}\n```\n\nعلى غرار المثال السابق، يجب أن يصاحب هذا الترحيل تغيير نوع الإعداد من `string` إلى `list` في ملف `settings.yml`.\n\n---\n\nإعادة تسمية خيار إعداد تعداد:\n\n```js\n// filename: 0001-rename-enum-choice.js\n\nexport default function migrate(settings) {\n if (settings.get(\"enum_setting\") === \"old_option\") {\n settings.set(\"enum_setting\", \"new_option\");\n }\n return settings;\n}\n```\n\n---\n\nإضافة عنصر إلى إعداد قائمة:\n\n```js\n// filename: 0001-add-item-to-list.js\n\nexport default function migrate(settings) {\n if (settings.has(\"list_setting\")) {\n const list = settings.get(\"list_setting\").split(\"|\");\n list.push(\"new_item\");\n settings.set(\"list_setting\", list.join(\"|\"));\n } else {\n settings.set(\"list_setting\", \"new_item\");\n }\n return settings;\n}\n```\n\n### التنفيذ ومعالجة الأخطاء\n\nيتم تشغيل الترحيلات تلقائيًا أثناء تثبيت السمة وتحديثاتها. يتم تنفيذها مرة واحدة فقط؛ إذا تم تعديل ترحيل بعد تنفيذه بنجاح، فلن يتم تشغيله مرة أخرى. إذا فشل ترحيل، تتوقف عملية التحديث، ويتم تقديم رسالة خطأ توضح ما حدث.\n\nإذا كان هناك خطأ في ترحيل يؤدي إلى تلف حالة إعداد ما، فإن الطريقة الصحيحة لإصلاح المشكلة هي إنشاء ترحيل جديد يقوم بتصحيح الحالة التالفة بدلاً من تعديل الترحيل الأصلي.\n\n\n---\n\n\u003csmall\u003eThis document is version controlled - suggest changes [on github](https://github.com/discourse/discourse-developer-docs/blob/main/docs/05-themes-components/11-migrate-settings.md).\u003c/small\u003e","target_locale":"en"}
8 إعجابات