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

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

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

نص

اسم الإضافة

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

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

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

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

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

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

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

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

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

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

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

رسائل الخطأ

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

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

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

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

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

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

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

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

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

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

  • استخدِم عنوانًا وتصنيفات أزرار واضحة.
  • تجنَّب استخدام مجموعات نصية طويلة وصفية.

مربّعات حوار

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

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

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

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

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

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

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

الأزرار

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

  • تجنَّب عرض أكثر من زرّ أزرق أو أحمر أو أخضر في المرّة الواحدة. قد تظهر أزرارสีเทา بشكل متكرر.
  • يجب أن تكون معظم تصنيفات الأزرار بتنسيق الجملة وأن تبدأ بفعل. يجب استخدام الأحرف اللاتينية الكبيرة في buttons الحمراء، والتي تُستخدَم عادةً لإنشاء الإجراءات.
الإجراءات التي يجب تجنّبها الإجراءات المقترَحة

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

استخدِم مربّعات الاختيار عندما يمكن للمستخدمين اختيار خيارات متعددة أو عدم اختيار أي خيار على الإطلاق. استخدِم أزرار الاختيار (أو قائمة اختيار) عندما يكون عليك تحديد خيار واحد بالضبط.

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

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

إنّ ميزة "خيارات" هي طريقة رائعة لتقديم قائمة قصيرة بالبدائل.

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

مناطق النص

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

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

الحقول النصية

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

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

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

في الإضافة

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

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

في المتجر

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

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

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

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

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