دليل أسلوب واجهة المستخدم لإضافات المحرّر

إضافات المحرِّر إنشاء واجهات مستخدم (القوائم والأشرطة الجانبية ومربعات الحوار) باستخدام خدمة HTML: نظرًا لأن الواجهات بلغة HTML وCSS، فهي قابلة للتخصيص بدرجة عالية. ومع ذلك، عندما في إنشاء واجهة الإضافة، يجب أن تصممها لتوفير تجربة مستخدم رائع المستخدم.

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

النص

اسم الإضافة

يجب ضبط اسم الإضافة عند النشر. بها. يظهر الاسم في عدة أماكن، مثل متجر الإضافات وضمن القوائم.

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

أسلوب الكتابة

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

عند كتابة نص في واجهة المستخدم:

  • استخدِم حالة أحرف الجملة (خاصةً للأزرار والتسميات وعناصر القائمة).
  • تفضيل النصوص القصيرة والبسيطة بدون المصطلحات أو الاختصارات.
ما ننصحك بتجنّبه: الإجراءات المقترَحة

نصيحة ما بعد التثبيت

ستظهر نصيحة ما بعد التثبيت مباشرةً بعد أن يثبّت أحد الأشخاص الإضافة تظهر في المساعدة. لديك جملتان لمساعدة المستخدمين على البدء بسرعة.

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

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

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

رسائل الخطأ

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

  • عدم السماح للمستخدم بالاطّلاع على أي استثناءات يطرحها الرمز بدلاً من ذلك، استخدم try...catch لاعتراض الاستثناءات، ثم عرض رسالة خطأ سهلة الاستخدام مع نص مضمّن في نمط الفئة error من CSS للإضافات حزمة أو مربّع حوار تنبيه.
  • قبل النشر، تأكَّد من أنّ الإضافة لا تسجِّل معلومات تصحيح الأخطاء في وحدة تحكم JavaScript؛ استخدام تسجيل Stackdriver بدلاً من ذلك.
ما ننصحك بتجنّبه: الإجراءات المقترَحة
رسالة خطأ سيئة رسالة خطأ جيدة

محتوى المساعدة

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

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

واجهات المستخدم المخصصة

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

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

نص واجهة المستخدم

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

  • استخدم تسميات عنوان وأزرار مستقلة بذاتها.
  • تجنَّب استخدام قوالب طويلة من النص الوصفي.

مربّعات حوار

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

  • لا تفتح مربع حوار (بما في ذلك تنبيه أو طلب) من مربّع حوار آخر فقط تعرض واحدًا تلو الآخر.
  • بالنسبة إلى عنوان مربع الحوار، استخدم كلمة أو عبارة قصيرة تبدأ كلمة مهمة.
  • يجب أن تكون تسميات الأزرار مرتبطة بعنوان مربع الحوار.
  • يُفضَّل استخدام زرَّين، يكونان عادةً إجراءً أساسيًا و"إلغاء". للحالات الخاصة التي تتطلب زرًا ثالثًا، ضع في اعتبارك الزاوية السفلية اليمنى.
  • ضع الأزرار في أسفل الجانب الأيمن من مربع الحوار. الزر الأساسي الأزرق على اليسار، مع أي أزرار ثانوية رمادية على اليمين.
ما ننصحك بتجنّبه: الإجراءات المقترَحة
عنوان مربع حوار سيئ عنوان مربّع حوار جيد

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

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

عناصر التحكّم

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

مستندات حزمة CSS للإضافات يوفّر نموذج ترميز لكل نوع من أنواع عناصر التحكّم أدناه.

الأزرار

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

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

مربّعات الاختيار وأزرار الاختيار

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

  • عدم تغيير مربّعات الاختيار" لمحاكاة أزرار الاختيار.
  • ويجب عدم اتخاذ أي إجراء على الفور بعد وضع علامة عليه. الناس يرتكبون الأخطاء. الانتظار إلى أن ينقر المستخدمون على زر لتأكيد اختياراتهم.

اختيار القوائم

تُعد الاختيارات طريقة رائعة لتقديم قائمة قصيرة من البدائل.

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

مناطق النص

إذا كان المستخدمون بحاجة إلى كتابة أكثر من بضع كلمات، استخدِم مربّع نص.

  • اجعل مناطق النص بطول سطرين على الأقل حتى تكون أسهل في الاستخدام وليست تشبه الحقول النصية.
  • ضَع تسميات في الأعلى.

حقول النص

استخدم الحقول النصية إذا كان الأشخاص بحاجة إلى كتابة كلمة أو كلمتين فقط.

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

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

في الإضافة

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

  • يجب أن تتبع جميع جوانب الإضافة إرشادات بناء هوية العلامة التجارية
  • لا تُدرِج كلمة "Google" أو تستخدِم رموز منتجات Google.
  • يجب ألا يزيد النص عن بضع كلمات وأن يكون نمطًا في الفئة gray من CSS للإضافات طرد.
  • يجب أن تكون الرسومات على خلفية بيضاء وألا يزيد حجمها عن 200 × 60 بكسل.
  • بالنسبة لمربعات الحوار، يجب أن تكون العلامة التجارية في الركن الأيمن السفلي.
  • بالنسبة إلى الأشرطة الجانبية، يمكن أن تكون العلامة التجارية في الجزء العلوي أو السفلي.

في المتجر

لنشر إضافة "محرِّر"، يجب عدد مواد عرض الصور: تُستخدَم مواد العرض هذه لإنشاء بطاقة بيانات المتجر الخاصة بالإضافة.

تسهيل الاستخدام

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

  • تأكَّد من إمكانية الانتقال إلى جميع عناصر التحكّم في واجهة المستخدم باستخدام لوحة المفاتيح. إضافة tabindex=0 إلى عناصر التحكّم المخصّصة (مثل تلك التي تم إنشاؤها باستخدام <div>) كي يتمكّن المستخدمون من اضغط على مفتاح التبويب (Tab) معه. ضَع في اعتبارك ما إذا كان يجب دعم مفاتيح أخرى أيضًا، مثل الأسهم للحصول على قائمة.
  • قد يستخدم بعض الأشخاص قارئ شاشة مع إضافتك. وبالتالي، يجب أن لديهم السمة alt، وعناصر التحكم المخصصة يجب أن سمات ARIA لوصف استخدامها
  • لا تعتمد فقط على اللون لتوصيل الحالة. استخدم الأيقونات والنص أيضًا.

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