الأدوات

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

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

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

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

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

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

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

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

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

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

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

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

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

يمكنك تحديد 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() لتحديد دالة معالِج التطبيق المصغّر ل ejecutan عند تغيُّر قيمة أداة الاختيار.

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

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 المقابلة.

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