الأدوات

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

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

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

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

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

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

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

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

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

بالإضافة إلى هذه التطبيقات المصغّرة الأساسية للبنية، يمكنك في إحدى إضافة 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، يمكنك عرض المحتوى السياقي الجديد فورًا (السلوك التلقائي) أو عرض إشعار سريع في بطاقة أسفل الشريط الجانبي. إذا نقر المستخدم على زر الرجوع للعودة إلى صفحتك الرئيسية عندما يكون هناك عامل تشغيل سياقي مفعَّل، ستظهر بطاقة لمحة سريعة لمساعدة المستخدمين في العثور على المحتوى السياقي مرة أخرى.

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

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

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

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

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

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

يمكنك تحديد تطبيق DecoratedText المصغّر الذي يحتوي على مربّع اختيار مرتبط به، بدلاً من استخدام زرّ أو مفتاح تبديل ثنائي. كما هي الحال في مفاتيح التبديل، يتم تضمين قيمة مربّع الاختيار في كائن event event (الإجراء) الذي يتم تمريره إلى 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 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"));

في ما يلي مثال على دالة معالج التطبيقات المصغّرة لأداة اختيار التاريخ والوقت. يقوم هذا المعالج بتنسيقات وتسجيل سلسلة تمثل التاريخ والوقت الذي اختاره المستخدم في التطبيق المصغَّر لاختيار التاريخ والوقت الذي يحمل المعرّف "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("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 المقابلة.

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

التنسيق مثال النتيجة المعروضة
غامق "This is <b>bold</b>." هذا الخط غامق.
مائل "This is <i>italics</i>." هذا التنسيق هو مائل.
تسطير "This is <u>underline</u>." هذا هو التسطير.
مشطوب "This is <s>strikethrough</s>." هذا يتوسطه خط.
لون الخط "This is <font color=\"#FF0000\">red font</font>." هذا هو الخط الأحمر.
رابط تشعّبي "This is a <a href=\"https://www.google.com\">hyperlink</a>." هذا رابط تشعّبي.
الوقت "This is a time format: <time>2023-02-16 15:00</time>." هذا تنسيق الوقت: .
سطر جديد "This is the first line. <br> This is a new line. بوصة هذا هو السطر الأول.
هذا سطر جديد.