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

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

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

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

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

حدِّد بطاقة إعداد في كلّ من بيان Apps Script وفي الرمز البرمجي.

يوضّح المثال التالي كيفية إنشاء بطاقة إعدادات تطلب من المستخدمين اختيار مساحة في 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. يشير هذا الإعداد إلى دالة في "برمجة التطبيقات" تجلب اقتراحات الإكمال التلقائي.
  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 ...
}

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