الأدوات

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

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

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

أنواع التطبيقات المصغَّرة

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

التطبيقات المصغّرة الهيكلية

توفّر الأدوات الهيكلية حاويات وتنظيمًا للأدوات الأخرى المستخدَمة في واجهة المستخدم.

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

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

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

التذييل الثابت

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

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

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

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

بطاقة المعاينة

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

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

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

استنادًا إلى دليل البدء السريع الخاص بإضافة Cats Google Workspace، يُعلم الرمز التالي المستخدمين بالمحتوى السياقي الجديد باستخدام بطاقة "نظرة سريعة" ويخصّص عنوان بطاقة "نظرة سريعة" لعرض موضوع سلسلة رسائل 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 مستضاف ومتاح للجميع.
• DecoratedText: سلسلة محتوى نصي يمكنك إقرانها بعناصر أخرى، مثل التصنيفات العلوية والسفلية، وصورة أو رمز. يمكن أن تتضمّن التطبيقات المصغّرة DecoratedText أيضًا تطبيقًا مصغّرًا من نوع Button أو Switch. يمكن أن تكون المفاتيح المضافة مفاتيح تبديل أو مربّعات اختيار. يمكن أن يستخدم نص المحتوى تنسيق HTML، بينما يجب أن تستخدم التصنيفات العلوية والسفلية نصًا عاديًا.
• فقرة نصية: فقرة نصية يمكن أن تتضمّن عناصر منسّقة باستخدام HTML.

التطبيقات المصغّرة التي تتطلّب تفاعل المستخدم

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

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

مربّعات الاختيار DecoratedText

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

يوضّح مقتطف الرمز التالي كيفية تحديد أداة مربّع اختيار 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 a 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 a 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 a date and 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"));

في ما يلي مثال على دالة معالجة أداة اختيار التاريخ والوقت. يعمل معالج الأحداث هذا على تنسيق وتسجيل سلسلة تمثّل التاريخ والوقت اللذين اختارهما المستخدم في أداة اختيار التاريخ والوقت التي تحمل المعرّف myDateTimePickerWidgetID:

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/workspace/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 دقيقة. يمكن للمستخدم أيضًا كتابة وقت معيّن. على الأجهزة الجوّالة، يؤدي اختيار أداة اختيار الوقت إلى فتح أداة اختيار الوقت المضمّنة في "ساعة" الجهاز الجوّال.

أجهزة الكمبيوتر المكتبي	الجهاز الجوّال

شبكة

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

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

var gridItem = CardService.newGridItem()
  .setIdentifier("item_001")
  .setTitle("Lucian R.")
  .setSubtitle("Chief Information Officer")
  .setImage(imageComponent);

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

var imageComponent = CardService.newImageComponent()
  .setImageUrl("https://developers.google.com/workspace/
      images/cymbal/people/person1.jpeg")
  .setCropStyle(cropStyle)

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

تنسيق النص

تتيح بعض الأدوات المستندة إلى النصوص تنسيق HTML الأساسي للنصوص. عند ضبط المحتوى النصي لهذه الأدوات، يجب تضمين علامات HTML المناسبة.

يتم عرض العلامات المتوافقة والغرض منها في الجدول التالي: