تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

الأدوات

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

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

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

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

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

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

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

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

بالإضافة إلى التطبيقات المصغّرة الأساسية هذه، يمكنك استخدام خدمة البطاقة في إضافة 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 ويخصِّص عنوان بطاقة Peek لعرض موضوع سلسلة الرسائل المحدَّدة في Gmail، وذلك استنادًا إلى Cats Google Workspace Add-up (البدء السريع لإضافة القطط في Google Workspace).

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

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

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

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

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

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

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"));

فيما يلي مثال على دالة معالج الأداة لأداة اختيار التاريخ والوقت. يقوم هذا المعالج ببساطة بتنسيق وتسجيل سلسلة تمثل التاريخ والوقت الذي اختاره المستخدم في الأداة

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>."`	وهذا هو تنسيق الوقت: 2023-02-16 15:00.
سطر جديد	`"This is the first line. <br> This is a new line.` بوصة	هذا هو السطر الأول. هذا سطر جديد.

الأدوات

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

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

تذييل ثابت

بطاقة "نظرة سريعة"

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

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

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

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

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

تنسيق النص

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