جمع البيانات باستخدام متغيّر إدخال

يوضّح هذا الدليل كيفية إنشاء متغيّر إدخال.

لتنفيذ الخطوات، يجب توفير معلومات معيّنة. على سبيل المثال، يتطلّب إرسال رسالة إلكترونية توفُّر عنوان بريد إلكتروني. لتوفير هذه المعلومات الضرورية، حدِّد متغيّرات الإدخال. بعد تحديدها، يضبط المستخدم عادةً متغيرات الإدخال في بطاقة إعدادات الخطوة أثناء إعدادها.

حدِّد متغيّر الإدخال في مكانَين: ملف البيان الخاص بالإضافة، وفي الرمز باستخدام بطاقة إعداد حيث يمكن للمستخدمين إدخال قيم لمتغيّرات الإدخال.

تحديد متغيّر الإدخال في ملف البيان

في ملف البيان، حدِّد متغيّرات الإدخال باستخدام مصفوفة inputs[]. يحتوي كل عنصر في مصفوفة inputs[] على السمات التالية:

  • ‫id: معرّف فريد لمتغيّر إدخال. للسماح للتدفق بربط عنصر إدخال بطاقة الإعدادات بمتغيّر الإدخال هذا، يجب أن يتطابق مع اسم عنصر البطاقة المقابل.
  • ‫description: وصف لمتغيّر الإدخال سيتم عرضه للمستخدمين النهائيين.
  • cardinality: عدد القيم المسموح بها القيم المحتمَلة هي:
    • SINGLE: يُسمح بقيمة واحدة فقط.
  • ‫dataType: نوع القيم المقبولة تحتوي dataType على السمة basicType التي تحدّد نوع البيانات. تشمل القيم الصالحة ما يلي:
    • ‫STRING: سلسلة أبجدية رقمية
    • ‫INTEGER: رقم
    • ‫TIMESTAMP: طابع زمني بالتنسيق ISO 8601. على سبيل المثال، في معيار ISO 8601، يتم تمثيل 15 مارس 2025 على النحو التالي: 2025-03-15.
    • ‫BOOLEAN: إما true أو false.
    • ‫EMAIL_ADDRESS: عنوان بريد إلكتروني بالتنسيق dana@example.com

يحدّد المثال التالي ثلاثة متغيّرات إدخال لخطوة آلة حاسبة. المتغيران المدخلان الأولان هما أعداد صحيحة، والثالث هو عملية حسابية.

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Calculator",
      "logoUrl": "https://www.gstatic.com/images/branding/productlogos/calculator_search/v1/web-24dp/logo_calculator_search_color_1x_web_24dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "actionElement",
          "state": "ACTIVE",
          "name": "Calculate",
          "description": "Asks the user for two values and a math operation, then performs the math operation on the values and outputs the result.",
          "workflowAction": {
            "inputs": [
              {
                "id": "value1",
                "description": "value1",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              },
              {
                "id": "value2",
                "description": "value2",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              },
              {
                "id": "operation",
                "description": "operation",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "outputs": [
              {
                "id": "result",
                "description": "Calculated result",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              }
            ],
            "onConfigFunction": "onConfigCalculate",
            "onExecuteFunction": "onExecuteCalculate"
          }
        }
      ]
    }
  }
}

تحديد متغيّر الإدخال في الرمز

يتضمّن رمز الخطوة دالة باسم onConfigFunction() تعرض بطاقة إعدادات تحدّد عنصرًا واحدًا من عناصر واجهة المستخدم لبطاقة الإدخال لكل متغيّر إدخال محدّد في مصفوفة inputs[] بملف البيان.

تتضمّن التطبيقات المصغّرة للإدخال المحدّدة في بطاقة الإعداد المتطلبات التالية:

  • يجب أن تتطابق سمة name لكل أداة إدخال مع سمة id لمتغير الإدخال المقابل في ملف البيان.
  • يجب أن تتطابق قيمة cardinality لعنصر الإدخال مع قيمة cardinality لمتغير الإدخال في ملف البيان.
  • يجب أن يتطابق نوع بيانات أداة الإدخال مع dataType متغير الإدخال في ملف البيان. إذا كان متغيّر الإدخال يتضمّن dataType من نوع عدد صحيح، لا يمكنه الاحتفاظ بسلسلة.

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

يعرض المثال التالي بطاقة إعدادات لكل أداة إدخال محدّدة في تحديد متغير الإدخال في ملف البيان.

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

/**
 * Generates and displays a configuration card for the sample calculation step.
 *
 * This function creates a card with input fields for two values and a drop-down
 * for selecting an arithmetic operation. The card also includes a "Save"
 * button to save the step configuration for the workflow.
 *
 * The input fields are configured to let the user select outputs from previous
 * workflow steps as input values using the `hostAppDataSource` property.
 */
function onConfigFunction() {
  var card = {
    "sections": [
      {
        "header": "Step example: Calculate",
        "widgets": [
          {
            "textInput": {
              "name": "value1", // "name" must match an "id" in the manifest file's inputs[] array.
              "label": "First value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          },
          {
            "selectionInput": {
              "name": "operation", // "name" must match an "id" in the manifest file's inputs[] array.
              "label": "Operation",
              "type": "DROPDOWN",
              "items": [
                {
                  "text": "+",
                  "value": "+",
                },
                {
                  "text": "-",
                  "value": "-",
                },
                {
                  "text": "x",
                  "value": "x",
                },
                {
                  "text": "/",
                  "value": "/",
                }
              ]
            }
          },
          {
            "textInput": {
              "name": "value2", // "name" must match an "id" in the manifest file's inputs[] array.
              "label": "Second value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          }
        ]
      }
    ]
  };
  return {
    "action": {
      "navigations": [{
        "push_card": card
      }]
    }
  };
}

التحقّق من صحة متغيّر الإدخال

من أفضل الممارسات التحقّق من أنّ المستخدم يُدخل قيمة مناسبة. اطّلِع على مقالة التحقّق من صحة متغيّر إدخال.