الأدوات

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

الأداة هي عنصر بسيط في واجهة المستخدم يوفر واحدًا أو أكثر من العناصر التالية:

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

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

استخدام مجموعة تصميمات إضافات Google Workspace

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

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

الحصول على حزمة التصميم

أنواع الأدوات

يتم تصنيف أدوات الإضافات عمومًا في ثلاث مجموعات: أدوات تنظيمية وأدوات معلوماتية وأدوات تفاعل المستخدمين.

الأدوات البنيوية

وتتيح الأدوات البنيوية حاويات وتنظيم للأدوات الأخرى المستخدمة في الذكاء الاصطناعي.

الأدوات البنيوية

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

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

يمكنك الآن إضافة صف ثابت من الأزرار إلى أسفل البطاقة. لا يتم نقل هذا الصف أو تصفّحه مع بقية محتوى البطاقة. يُظهر مقتطف الرمز التالي طريقة تحديد مثال لتذييل ثابت وإضافته إلى بطاقة:

var fixedFooter = CardService.newFixedFooter()
    .setPrimaryButton(
        CardService.newTextButton()
            .setText("help")
            .setOpenLink(CardService.newOpenLink()
                .setUrl("https://www.google.com")))
    .setSecondaryButton(
        CardService.newTextButton()
            .setText("submit")
            .setOnClickAction(
                CardService.newAction()
                    .setFunctionName(
                        "submitCallback")));

var card = CardService.newCardBuilder()
    // (...)
    .setFixedFooter(fixedFooter)
    .build();
      

 

مثال على أداة تذييل ثابتة

بطاقة سريعة

مثال على بطاقة سريعة

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

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

لتخصيص عنوان البطاقة السريعة، أضِف الطريقة .setPeekCardHeader() مع عنصر CardHeader عادي عند إنشاء بطاقة السياق. بشكل تلقائي، لا يحتوي عنوان بطاقة Peek إلا على اسم الإضافة.

يستند الرمز التالي، استنادًا إلى البدء السريع لإضافة القطط في Google Workspace، إلى محتوى حول المحتوى الجديد باستخدام بطاقة "نظرة سريعة" ويخصِّص عنوان Peek بطاقة لعرض سلسلة محادثات رسائل Gmail المحدّدة.

var peekHeader = CardService.newCardHeader()
    .setTitle('Contextual Cat')
    .setImageUrl('https://www.gstatic.com/images/
        icons/material/system/1x/pets_black_48dp.png')
    .setSubtitle(text);

. . .

var card = CardService.newCardBuilder()
    .setDisplayStyle(CardService.DisplayStyle.PEEK)
    .setPeekCardHeader(peekHeader);
      

 

مثال على بطاقة خاطفة مخصّصة

أدوات تتضمّن معلومات

أدوات تتضمّن معلومات

تقدّم الأدوات الإعلامية معلومات للمستخدم.

  • صورة: صورة تشير إلى عنوان URL مستضاف ويمكن الوصول إليه بشكل علني.
  • DecoatedText: سلسلة محتوى نصية يمكنك إقرانها بعناصر أخرى، مثل تصنيفات النصوص العلوية والسفلية وصورة أو رمز. ويمكن أيضًا أن تتضمن أدوات مزيّنة النص المزخرف أداة Button أو Switch. ويمكن أن تكون مفاتيح التبديل المُضافة أزرار بسيطة أو مربّعات اختيار. يمكن أن يستخدم نص المحتوى في أداة DeoratedText تنسيق HTML، ويجب أن يستخدم التصنيفان العلوي والسفلي نصًا عاديًا.
  • Text paragraph: هي عبارة عن فقرة نصية بسيطة يمكن أن تتضمّن عناصر بتنسيق HTML.




أدوات تفاعل المستخدمين

أداة إجراء البطاقة

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

أدوات تفاعل المستخدمين

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

مربّعات اختيار النص المزخرف

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

يُظهر مقتطف الرمز التالي طريقة تحديد أداة مربّع الاختيار DecoratedText، والتي يمكنك إضافتها بعد ذلك إلى البطاقة:

var decoratedText = CardService.newDecoratedText()
    // (...)
    .setSwitch(CardService.newSwitch()
        .setFieldName('form_input_switch_key')
        .setValue('switch_is_on')
        .setControlType(
            CardService.SwitchControlType.CHECK_BOX));
      

 

مثال على أداة مربّع اختيار النص المزخرف

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

يمكنك تحديد الأدوات التي تسمح للمستخدمين باختيار وقت أو تاريخ أو كليهما. يمكنك استخدام setOnChangeAction() لإسناد دالة معالج الأدوات لتنفيذها عند تغيير قيمة أداة الاختيار.

ويوضّح مقتطف الرمز التالي كيفية تحديد منتقي التاريخ فقط، وأداة اختيار الوقت فقط، ومنتقي التاريخ، والتي يمكنك إضافتها بعد ذلك إلى بطاقة:

var dateOnlyPicker = CardService.newDatePicker()
    .setTitle("Enter the date.")
    .setFieldName("date_field")
    // Set default value as May 24 2019. Either a
    // number or string is acceptable.
    .setValueInMsSinceEpoch(1558668600000)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleDateChange"));

var timeOnlyPicker = CardService.newTimePicker()
    .setTitle("Enter the time.")
    .setFieldName("time_field")
    // Set default value as 23:30.
    .setHours(23)
    .setMinutes(30)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleTimeChange"));

var dateTimePicker = CardService.newDateTimePicker()
    .setTitle("Enter the date and time in EDT time.")
    .setFieldName("date_time_field")
    // Set default value as May 24 2019 03:30 AM UTC.
    // Either a number or string is acceptable.
    .setValueInMsSinceEpoch(1558668600000)
    // EDT time is 4 hours behind UTC.
    .setTimeZoneOffsetInMins(-4 * 60)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleDateTimeChange"));
      

 

مثال على بطاقة خاطفة مخصّصة

إليك مثال على دالة معالج أداة اختيار التاريخ في الوقت المحدد. يعمل هذا المعالج على تنسيق السجلّ الذي يمثّل وقت التاريخ الذي اختاره المستخدم في أداة منتقي التاريخ والوقت باستخدام المعرّف "myDateTime PickerWidgetID"

function handleDateTimeChange(event) {
  var dateTimeInput =
    event.commonEventObject.formInputs["myDateTimePickerWidgetID"];
  var msSinceEpoch = dateTimeInput.msSinceEpoch;
  var hasDate = dateTimeInput.hasDate;
  var hasTime = dateTimeInput.hadTime;

  // The following requires you to configure the add-on to read user locale
  // and timezone.
  // See https://developers.google.com/apps-script/add-ons/how-tos/access-user-locale
  var userTimezoneId = event.userTimezone.id;

  // Format and log the date-time selected using the user's timezone.
  var formattedDateTime;
  if (hasDate && hasTime) {
    formattedDateTime = Utilities.formatDate(
      new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd hh:mm:ss");
  } else if (hasDate) {
    formattedDateTime = Utilities.formatDate(
      new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd")
      + ", Time unspecified";
  } else if (hasTime) {
    formattedDateTime = "Date unspecified, "
      + Utilities.formatDate(
          new Date(msSinceEpoch), userTimezoneId, "hh:mm a");
  }

  if (formattedDateTime) {
    console.log(formattedDateTime);
  }
}

 

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

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

أجهزة سطح المكتب الأجهزة الجوّالة
مثال على اختيار منتقي التاريخ مثال على اختيار منتقي التاريخ على الأجهزة الجوّالة
مثال على اختيار الوقت مثال على اختيار الوقت على الأجهزة الجوّالة

معرّف الإصدار العالمي (GRid)

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

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

var gridItem = CardService.newGridItem()
  .setIdentifier("item_001")
  .setTitle("A grid item")
  .setSubtitle("with a subtitle")
  .setImage(imageComponent);

var cropStyle = CardService.newImageCropStyle()
  .setImageCropType(CardService.ImageCropType.SQUARE);

var borderStyle = CardService.newBorderStyle()
  .setType(CardService.BorderType.STROKE)
  .setCornerRadius(8)
  .setStrokeColor("#00FF00FF");

var imageComponent = CardService.newImageComponent()
  .setImageUrl("https://cataas.com/cat?0.001")
  .setCropStyle(cropStyle)
  .setBorderStyle(borderStyle);

var grid = CardService.newGrid()
  .setTitle("My first grid")
  .addItem(gridItem)
  .setNumColumns(2)
  .setOnClickAction(CardService.newAction()
    .setFunctionName("handleGridItemClick"));
      

 

مثال على أداة الشبكة

تنسيق النص

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

التنسيق مثال النتيجة المعروضة
غامق <b>test</b> اختبار
مائل <i>test</i> اختبار
تسطير <u>test</u> اختبار
يتوسطه خط <s>test</s> اختبار
لون الخط <font color="#ea9999">test</font> اختبار
رابط تشعّبي <a href="http://www.google.com">google</a> google
الوقت <time>2020-02-16 15:00</time> 16-02-2020 15:00
سطر جديد test <br> test اختبار
اختبار
.