إنشاء بطاقة إعداد لخطوة

يوضّح هذا الدليل كيفية إنشاء بطاقة إعدادات تتيح للمستخدمين تخصيص إحدى الخطوات في Google Workspace Studio وتقديم بيانات الإدخال لها.

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

تتضمّن بعض أدوات البطاقات وظائف وميزات خاصة بـ Workspace Studio، كما هو موضّح بالتفصيل في هذا الدليل.

تحديد بطاقة إعدادات

حدِّد بطاقة إعدادات في بيان "برمجة تطبيقات Google" وفي الرمز البرمجي.

يوضّح المثال التالي كيفية إنشاء بطاقة إعدادات تطلب من المستخدمين اختيار مساحة في Google Chat.

تعديل ملف البيان

في ملف البيان، حدِّد workflowElements.

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Chat space selector",
      "logoUrl": "https://www.gstatic.com/images/branding/productlogos/gsuite_addons/v6/web-24dp/logo_gsuite_addons_color_1x_web_24dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "actionElement",
          "state": "ACTIVE",
          "name": "Chat space selector",
          "description": "Lets the user select a space from Google  Chat",
          "workflowAction": {
            "inputs": [
              {
                "id": "chooseSpace",
                "description": "Choose a Chat space",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfigSpacePicker",
            "onExecuteFunction": "onExecuteSpacePicker"
          }
        }
      ]
    }
  }
}

تعديل الرمز البرمجي

في الرمز البرمجي للتطبيق، اعرض بطاقة.

برمجة التطبيقات

/**
 * Generates and displays a configuration card to choose a Chat space
 */
function onConfigSpacePicker() {

  const selectionInput = CardService.newSelectionInput()
    .setTitle("First Value")
    .setFieldName("chooseSpace")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.SPACE)
            )
        )
    );

  const cardSection = CardService.newCardSection()
    .setHeader("Select Chat Space")
    .setId("section_1")
    .addWidget(selectionInput)

  var card = CardService.newCardBuilder()
    .addSection(cardSection)
    .build();

  return card;
}

function onExecuteSpacePicker(e) {
}

إعداد ميزة الإكمال التلقائي لأدوات الإدخال

يمكنك إعداد ميزة الإكمال التلقائي لأدوات SelectionInput لمساعدة المستخدمين في الاختيار من قائمة الخيارات. على سبيل المثال، إذا بدأ المستخدم بكتابة Atl لقائمة تتضمّن مدنًا في الولايات المتحدة، يمكن أن تقترح الأداة تلقائيًا Atlanta قبل أن ينتهي المستخدم من الكتابة. يمكنك إكمال ما يصل إلى 100 عنصر تلقائيًا.

يمكن أن تأتي اقتراحات الإكمال التلقائي من مصادر البيانات التالية:

  • الإكمال التلقائي من جهة الخادم: يتم ملء الاقتراحات من مصدر بيانات خارجي أو تابع لجهة خارجية تحدّده أنت.
  • بيانات Google Workspace: يتم ملء الاقتراحات من مصادر Google Workspace، مثل مستخدمي Google Workspace أو مساحات Google Chat.

الإكمال التلقائي من جهة الخادم

يمكنك إعداد أداة SelectionInput لإكمال الاقتراحات تلقائيًا من مصدر بيانات خارجي. على سبيل المثال، يمكنك مساعدة المستخدمين في الاختيار من قائمة العملاء المحتملين من نظام إدارة علاقات العملاء (CRM).

لتنفيذ ميزة الإكمال التلقائي من جهة الخادم، اتّبِع الخطوات التالية:

  1. تحديد مصدر البيانات: في أداة SelectionInput، أضِف DataSourceConfig تحدّد RemoteDataSource. يشير هذا الإعداد إلى دالة في "برمجة تطبيقات Google" تجلب اقتراحات الإكمال التلقائي.
  2. تنفيذ دالة الإكمال التلقائي: يتم تشغيل هذه الدالة عندما يكتب المستخدم في حقل الإدخال. يجب أن تستعلم الدالة عن مصدر البيانات الخارجي استنادًا إلى ما أدخله المستخدم وتعرض قائمة بالاقتراحات.

يوضّح المثال التالي كيفية إعداد أداة SelectionInput لميزة الإكمال التلقائي من جهة الخادم:

برمجة التطبيقات

// In your onConfig function:
var multiSelect1 =
  CardService.newSelectionInput()
    .setFieldName("value1")
    .setTitle("Server Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .addDataSourceConfig(
      CardService.newDataSourceConfig()
        .setRemoteDataSource(
          CardService.newAction().setFunctionName('getAutocompleteResults')
        )
    )
    .addDataSourceConfig(
      CardService.newDataSourceConfig()
        .setPlatformDataSource(
          CardService.newPlatformDataSource()
            .setHostAppDataSource(
              CardService.newHostAppDataSource()
                .setWorkflowDataSource(
                  CardService.newWorkflowDataSource()
                    .setIncludeVariables(true)
                ))
        )
    );

// ... add widget to card ...

التعامل مع طلب الإكمال التلقائي

تتلقّى الدالة المحدّدة في setFunctionName (مثل getAutocompleteResults) كائن حدث عندما يكتب المستخدم في الحقل. يجب أن تنفّذ هذه الدالة ما يلي:

  1. التحقّق من event.workflow.elementUiAutocomplete.invokedFunction للتأكّد من تطابقه مع اسم الدالة المتوقّع
  2. الحصول على ما أدخله المستخدم من event.workflow.elementUiAutocomplete.query
  3. الاستعلام عن مصدر البيانات الخارجي باستخدام الاستعلام
  4. عرض ما يصل إلى 100 اقتراح بالتنسيق المطلوب

يوضّح المثال التالي كيفية تنفيذ الدالة handleAutocompleteRequest لعرض الاقتراحات استنادًا إلى استعلام المستخدم:

برمجة التطبيقات

function handleAutocompleteRequest(event) {
  var invokedFunction = event.workflow.elementUiAutocomplete.invokedFunction;
  var query = event.workflow.elementUiAutocomplete.query;

  if (invokedFunction != "getAutocompleteResults" || query == undefined || query == "") {
    return {};
  }

  // Query your data source to get results based on the query
  let autocompleteResponse = AddOnsResponseService.newUpdateWidget()
    .addSuggestion(
      query + " option 1",
      query + "_option1",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 1 bottom text"
    )
    .addSuggestion(
      query + " option 2",
      query + "_option2",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 2 bottom text"
    ).addSuggestion(
      query + " option 3",
      query + "_option3",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 3 bottom text"
    );

  const modifyAction = AddOnsResponseService.newAction()
    .addModifyCard(
      AddOnsResponseService.newModifyCard()
        .setUpdateWidget(autocompleteResponse)
    );

  return AddOnsResponseService.newRenderActionBuilder()
    .setAction(modifyAction)
    .build();
}

// In your onConfig function, handle the autocomplete event
function onConfigAutocompleteTest(event) {
  // Handle autocomplete request
  if (event.workflow && event.workflow.elementUiAutocomplete) {
    return handleAutocompleteRequest(event);
  }

  // ... rest of your card building logic ...
}

اعتبارات وقيود البطاقات