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

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

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

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

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

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

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

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

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

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

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

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Sample add-on",
      "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": "onExecuteCalculate"
          }
        }
      ]
    }
  }
}

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

في رمز التطبيق، أعِد بطاقة.

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

/**
* Generates and displays a configuration card to choose a Chat space
  */
function onConfigSpacePicker() {
  var card = {
    "sections": [
      {
        "header": "Choose a Chat space",
        "widgets": [
          {
            "selectionInput": {
              "name": "value1",
              "label": "First value",
              "type": "MULTI_SELECT",
              "platformDataSource": {
                "hostAppDataSource": {
                  "workflowDataSource": {
                    "includeVariables": true,
                    "type": "SPACE"
                  }
                }
              }
            }
          }
        ]
      }
    ]
  };
  return {
    "action": {
      "navigations": [{
        "push_card": card
      }]
    }
  };
}

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

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

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

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

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

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

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

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

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

تحقَّق من event.workflow.elementUiAutocomplete.invokedFunction للتأكّد من تطابقه مع اسم الدالة المتوقّع.
احصل على إدخال المستخدم من event.workflow.elementUiAutocomplete.query.
أرسِل طلب بحث إلى مصدر البيانات الخارجي باستخدام طلب البحث.
عرض ما يصل إلى 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
  var autocompleteResponse = [
    {
      "text": query + " option 1",
      "value": query + "_option1",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    },
    {
      "text": query + " option 2",
      "value": query + "_option2",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "bottom_text": "subtitle of option 2"
    },
    {
      "text": query + " option 3",
      "value": query + "_option3",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    }
  ];

  var response = {
    "action": {
      "modify_operations": [
        {
          "update_widget": {
            "selection_input_widget_suggestions": {
              "suggestions": autocompleteResponse
            }
          }
        }
      ]
    }
  };
  return response;
}

// 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 ...
}

الإكمال التلقائي لبيانات Google Workspace

يمكنك أيضًا ملء اقتراحات الإكمال التلقائي من البيانات المتوفرة في بيئة Google Workspace الخاصة بالمستخدم:

مستخدمو Google Workspace: يتم ملء قائمة المستخدمين ضمن مؤسسة Google Workspace نفسها.
مساحات Google Chat: يتم ملء مساحات Google Chat التي يكون المستخدم عضوًا فيها.

لضبط هذا الإعداد، عليك ضبط PlatformDataSource في أداة SelectionInput ، مع تحديد WorkflowDataSourceType على أنّه USER أو SPACE.

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

// User Autocomplete
var multiSelect2 =
  CardService.newSelectionInput()
    .setFieldName("value2")
    .setTitle("User Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.USER)
            ))
    );

// Chat Space Autocomplete
var multiSelect3 =
  CardService.newSelectionInput()
    .setFieldName("value3")
    .setTitle("Chat Space Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.SPACE)
            ))
    );

مثال: الجمع بين أنواع الإكمال التلقائي

يوضّح المثال التالي دالة onConfig تنشئ بطاقة تتضمّن ثلاثة عناصر واجهة مستخدم SelectionInput، ما يوضّح ميزة الإكمال التلقائي من جهة الخادم ومن جهة المستخدم ومن جهة المساحة:

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

function onConfigAutocompleteTest(event) {
  // Handle autocomplete request
  if (event.workflow && event.workflow.elementUiAutocomplete) {
    return handleAutocompleteRequest(event);
  }

  // Server-side autocomplete widget
  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)
                  ))
          )
      );

  // User autocomplete widget
  var multiSelect2 =
    CardService.newSelectionInput()
      .setFieldName("value2")
      .setTitle("User Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .setPlatformDataSource(
        CardService.newPlatformDataSource()
          .setHostAppDataSource(
            CardService.newHostAppDataSource()
              .setWorkflowDataSource(
                CardService.newWorkflowDataSource()
                  .setIncludeVariables(true)
                  .setType(CardService.WorkflowDataSourceType.USER)
              ))
      );

  // Space autocomplete widget
  var multiSelect3 =
    CardService.newSelectionInput()
      .setFieldName("value3")
      .setTitle("Chat Space Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .setPlatformDataSource(
        CardService.newPlatformDataSource()
          .setHostAppDataSource(
            CardService.newHostAppDataSource()
              .setWorkflowDataSource(
                CardService.newWorkflowDataSource()
                  .setIncludeVariables(true)
                  .setType(CardService.WorkflowDataSourceType.SPACE)
              ))
      );

  var sectionBuilder =
    CardService.newCardSection()
      .addWidget(multiSelect1)
      .addWidget(multiSelect2)
      .addWidget(multiSelect3);

  var card =
    CardService.newCardBuilder()
      .addSection(sectionBuilder)
      .build();
  return card;
}

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
  var autocompleteResponse = [
    {
      "text": query + " option 1",
      "value": query + "_option1",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    },
    {
      "text": query + " option 2",
      "value": query + "_option2",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "bottom_text": "subtitle of option 2"
    },
    {
      "text": query + " option 3",
      "value": query + "_option3",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    }
  ];

  var response = {
    "action": {
      "modify_operations": [
        {
          "update_widget": {
            "selection_input_widget_suggestions": {
              "suggestions": autocompleteResponse
            }
          }
        }
      ]
    }
  };
  return response;
}

الميزات الخاصة بـ Workspace Flows

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

TextInput وSelectionInput

تتضمّن أدوات TextInput وSelectionInput الميزات التالية الخاصة بـ "مهام سير عمل Workspace":

includeVariables: سمة منطقية تتيح للمستخدمين اختيار متغيرات من الخطوات السابقة.
‫type: قيمة مُعدَّدة تُكمل الاقتراحات تلقائيًا. تشمل القيم المسموح بها ما يلي:
- ‫USER: تقدّم اقتراحات للإكمال التلقائي للأشخاص في جهات اتصال المستخدم.
- ‫SPACE: يقدّم اقتراحات إكمال تلقائي لمساحات Google Chat التي يكون المستخدم عضوًا فيها.

عند ضبط كل من includeVariables وtype، يجمع حقل الإدخال بين تجارب كل منهما. يمكن للمستخدمين اختيار متغيّر من type المطابق من قائمة منسدلة، والاطّلاع على اقتراحات الإكمال التلقائي الخاصة به.

الشكل 1: يراجع المستخدم اقتراحات الإكمال التلقائي عند اختيار مساحة.
الشكل 2: يختار المستخدم متغيّر الإخراج لخطوة سابقة من القائمة المنسدلة ➕المتغيّرات.

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

لا تتوافق ميزة التنقّل بين البطاقات، مثل popCard() و pushCard() و updateCard()، مع الإضافات التي توسّع نطاق ميزة "التنقل".
عند استخدام SelectionInput في أداة اختيار المتغيّرات، لا تتوافق التطبيقات المصغّرة إلا مع "type": "MULTI_SELECT". في مواضع أخرى من بطاقات الإعداد، تتوافق SelectionInput مع جميع قيم SelectionType.

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

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

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

JSON

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

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

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

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

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

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

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

الإكمال التلقائي لبيانات Google Workspace

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

مثال: الجمع بين أنواع الإكمال التلقائي

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

الميزات الخاصة بـ Workspace Flows

TextInput وSelectionInput

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

مواضيع ذات صلة

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