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

الأدوات

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

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

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

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

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

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

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

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

بالإضافة إلى هذه الأدوات الهيكلية الأساسية، في إضافة 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 عادية عند إنشاء بطاقة سياقية بشكل افتراضي، يتم عرض عنوان بطاقة نظرة سريعة يحتوي على اسم إضافتك فقط.

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

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

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

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

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

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

التطبيق المصغَّر للإجراءات المتعلقة بالبطاقة

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

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

في ما يلي مثال على دالة معالِج التطبيق المصغّر لأداة اختيار التاريخ والوقت. هذا النمط يقوم المعالج بتنسيق والسجلات سلسلة تمثل التاريخ والوقت المختار بواسطة المستخدِم في أداة اختيار التاريخ والوقت باستخدام المعرّف "myDateTimeChooseerWidgetID":

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

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

التنسيق	مثال	النتيجة المعروضة
غامق	`"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>."`	هذا الخط الأحمر.
Hyperlink	`"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 مربّع اختيار

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

شبكة

تنسيق النص

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