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

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

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

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

أداة إنشاء البطاقات: هي أداة تفاعلية تساعدك في إنشاء البطاقات وتحديدها.
البطاقة في المستندات المرجعية لواجهة برمجة التطبيقات لإضافات Google Workspace
Card Service: هي خدمة في Apps Script تتيح للنصوص البرمجية إعداد البطاقات وإنشائها.
واجهات مستندة إلى البطاقات في مستندات المطوّرين الخاصة بإضافات 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).

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

تحديد مصدر البيانات: في أداة 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
  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 ...
}

الإكمال التلقائي لبيانات 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، ما يوضّح ميزة الإكمال التلقائي من جهة الخادم ومن جهة المستخدم ومن جهة المساحة:

JSON

json { "timeZone": "America/Los_Angeles", "exceptionLogging": "STACKDRIVER", "runtimeVersion": "V8", "addOns": { "common": { "name": "Autocomplete Demo", "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png", "useLocaleFromApp": true }, "flows": { "workflowElements": [ { "id": "autocomplete_demo", "state": "ACTIVE", "name": "Autocomplete Demo", "description": "Provide autocompletion in input fields", "workflowAction": { "inputs": [ { "id": "value1", "description": "A multi-select field with autocompletion", "cardinality": "SINGLE", "dataType": { "basicType": "STRING" } } ], "onConfigFunction": "onConfigAutocomplete", "onExecuteFunction": "onExecuteAutocomplete" } } ] } } }

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

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
  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();
}

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

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

‫TextInput وSelectionInput

تتضمّن أدوات TextInput وSelectionInput الميزات التالية الخاصة بـ Workspace Studio:

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

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

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

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

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

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

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

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

JSON

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

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

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

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

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

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

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

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

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

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

JSON

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

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

‫TextInput وSelectionInput

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

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

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