كيفية تخصيص مستندات ONLYOFFICE بشعارك وألوانك

باختصار: استخدم شعار Docs API، ونمط واجهة مستخدم مخصص للألوان.

إذا كان هدفك هو جعل محرر ONLYOFFICE Docs يبدو كجزء من منتجك، فإن أفضل إعداد هو تخصيص ثنائي الطبقات: قم بتكوين editorConfig.customization.logoشعار رأس الصفحة في تكامل واجهة برمجة تطبيقات المستندات، ثم أضف ملف JSON مخصصًا للثيم على خادم المستندات لألوان المحرر. هاتان آليتان منفصلتان، ولكل منهما قواعد توفر مختلفة.

بحسب ما تم التحقق منه في وثائق ONLYOFFICE بتاريخ 7 أكتوبر 2026، فإنّ مُعامل editor-header logoمُتاح فقط لمطوري ONLYOFFICE Docs. تُحدد واجهة برمجة التطبيقات الرسمية صورًا بحجم 300×20 بكسل لـ image، imageDarkو ، و imageLight، مع ارتفاع شعار مُوصى به يبلغ 20 بكسل. في الوقت نفسه، تُدعم سمات واجهة المستخدم المُخصصة منذ إصدار ONLYOFFICE Docs v7.0، ويتم تثبيتها كملفات JSON للسمات على خادم المستندات. المرجع الرسمي الحالي هو وثائق العلامة التجارية القياسية لـ ONLYOFFICE Docs ، ويتم توثيق آلية عمل ملفات السمات في قسم "تغيير سمات واجهة المستخدم في ONLYOFFICE Docs" .

يناسب هذا الأسلوب الفرق التي تُدمج ONLYOFFICE Docs في تطبيقات الويب الخاصة بها وتتحكم في خادم المستندات. وهو يختلف عن تغيير سمة بوابة DocSpace أو Workspace. إذا كان هدفك هو البوابة المحيطة وليس المحرر نفسه، فاستخدم إعدادات العلامة التجارية للمنتج.

الخطوة الأولى: تأكد مما تحتاجه فعلاً لوضع علامتك التجارية

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

• شعار رأس الصفحة: استخدم editorConfig.customization.logo. يشير ONLYOFFICE إلى أن هذه المعلمة مخصصة للمطورين فقط.
• ألوان واجهة المستخدم: قم بتثبيت ملف JSON الخاص بالثيم المخصص على خادم المستندات. هذه هي الآلية الصحيحة لألوان العلامة التجارية.
• عناصر تحكم إضافية للعلامة التجارية الخاصة: راجع وثائق العلامة التجارية الخاصة الموسعة . تشير ONLYOFFICE إلى أن هذه المعلمات تتطلب ترخيص العلامة التجارية الخاصة الموسع لبرنامج Docs Developer.

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

الخطوة الثانية: تجهيز ملفات الشعار للرؤوس الفاتحة والداكنة

صمّم شعارًا عريضًا وبسيطًا يظل واضحًا حتى عند ارتفاع 20 بكسل في رأس الصفحة. تشير وثائق واجهة برمجة التطبيقات (API) إلى أن حجم الصورة القياسي لرأس الصفحة هو 300×20 بكسل. استخدم تصميمات منفصلة للخلفيات الداكنة والفاتحة عندما يفقد شعار علامتك التجارية تباينه. على سبيل المثال، قد يبدو شعار مكتوب باللون الأزرق الداكن مناسبًا لرأس صفحة فاتح اللون، ولكنه قد يختفي في تصميم داكن؛ لذا يُنصح باستخدام تصميم أبيض أو فاتح اللون.

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

الخطوة 3: أضف الشعار إلى إعدادات واجهة برمجة تطبيقات المستندات الخاصة بك

const config = {
  editorConfig: {
    customization: {
      logo: {
        image: "https://app.example.com/branding/logo.png",
        imageDark: "https://app.example.com/branding/logo-dark.png",
        imageLight: "https://app.example.com/branding/logo-light.png",
        url: "https://www.example.com",
        visible: true
      }
    }
  }
};

const docEditor = new DocsAPI.DocEditor("placeholder", config);

imageهو شعار وضع العمل الشائع. imageDarkيُستخدم لعرض رأس داكن أو ملون، ويُستخدم imageLightلعرض رأس فاتح مثل سمة Gray. urlيتحكم في موضع النقر على الشعار؛ اضبطه على سلسلة فارغة أو nullإذا كان الشعار غير قابل للنقر. visibleيتحكم في عرض الشعار من عدمه.

الخطوة الرابعة: التحقق من الشعار في ظروف الإضاءة والظلام

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

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

الخطوة 5: إنشاء ملف JSON مخصص لنمط الألوان

بالنسبة لألوان واجهة المستخدم، أنشئ ملف سمة idيبدأ بـ theme-. يدعم هذا الملف ألوان المستندات فقط light، darkبما في ذلك المستندات التي تستخدم نظام الألوان الست عشري أو RGBA. لا تخلط بين هذا وبين نظام ألوان المستند: فهذا الملف JSON يُغير واجهة المحرر نفسها، وليس ألوان السمة المخزنة داخل ملفات DOCX أو XLSX أو PPTX.

{
  "name": "Northstar Light",
  "id": "theme-northstar-light",
  "type": "light",
  "colors": {
    "toolbar-header-document": "#1E3A8A",
    "toolbar-header-spreadsheet": "#166534",
    "toolbar-header-presentation": "#B45309",
    "background-normal": "#FFFFFF",
    "background-accent-button": "#1E3A8A",
    "text-normal": "#1F2937",
    "icon-normal": "#374151"
  }
}

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

الخطوة 6: ضع ملف السمة في دليل سمات خادم المستندات

يوثق برنامج ONLYOFFICE هذه المواقع لملفات السمات المخصصة:

• لينكس: /var/www/onlyoffice/documentserver/web-apps/apps/common/main/resources/themes
• ويندوز: %ProgramFiles%\ONLYOFFICE\DocumentServer\web-apps\apps\common\main\resources\themes
• Docker: انسخ ملف JSON إلى نفس المسار داخل حاوية Docs.

sudo docker cp northstar-theme.json onlyoffice:/var/www/onlyoffice/documentserver/web-apps/apps/common/main/resources/themes/

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

الخطوة 7: قم بتحديث الصفحة، وانتظر حتى يتم تحميل البيانات من ذاكرة التخزين المؤقت، ثم حدد المظهر المخصص.

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

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

الخطوة 8: التحقق من صحة العلامة التجارية النهائية كنظام، وليس مجرد لقطة شاشة

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

كيفية معرفة أن التخصيص يعمل

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

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

الحدود والأخطاء الشائعة

لا يُعدّ تخصيص العلامة التجارية للمحرر مماثلاً لتخصيص العلامة التجارية لـ DocSpace أو Workspace

يحتوي ONLYOFFICE على واجهات تخصيص منفصلة. يختص هذا الدليل بتخصيص العلامة التجارية لمحرر مستندات ONLYOFFICE. أما عناصر التحكم في العلامة التجارية للبوابة، وأسماء المستأجرين، وأيقونات المواقع، وعناصر التنقل المحيطة بها، فهي تابعة لإعدادات DocSpace أو Workspace، وليست تابعة لعنصر شعار رأس واجهة برمجة تطبيقات المستندات (Docs API).

نظام ألوان المستند ليس سمة واجهة المستخدم

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

لا تفترض أن كل عنصر تحكم ذي علامة تجارية بيضاء مضمن في العلامة التجارية القياسية

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

قائمة التحقق من النشر العملي

• قم بتأكيد طلب مطور ONLYOFFICE Docs إذا كنت بحاجة إلى تخصيص شعار رأس الصفحة الموضح هنا.
• قم بإنشاء أصول شعار بحجم 300×20، بما في ذلك النسخ الفاتحة والداكنة حيثما يتطلب التباين ذلك.
• قم بالتكوين editorConfig.customization.logoفي طبقة التكامل.
• أنشئ ملف JSON صالحًا لسمة مخصصة بمعرف يبدأ بـ theme-.
• ضع ملف السمة في دليل سمات خادم المستندات الموثق.
• بالنسبة لعمليات النشر باستخدام Docker أو عمليات النشر غير القابلة للتغيير، اجعل تثبيت السمة قابلاً للتكرار ودائمًا.
• اسمح بتأخير التخزين المؤقت الموثق، ثم قم بتحديث الصفحة واختيار السمة.
• اختبر التباين، والحالات، وأنواع المحررين، وظروف الإضاءة والظلام قبل طرحها على نطاق واسع.

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

المراجع الرسمية

• واجهة برمجة تطبيقات ONLYOFFICE Docs: التخصيص – العلامة التجارية القياسية
• مركز مساعدة ONLYOFFICE: تغيير سمات واجهة المستخدم في مستندات ONLYOFFICE
• واجهة برمجة تطبيقات ONLYOFFICE Docs: التخصيص – العلامة التجارية الخاصة