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

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

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

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

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

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

• ‫id: معرّف فريد لمتغيّر إدخال. للسماح للوكيل بربط عنصر إدخال بطاقة الإعدادات بمتغيّر الإدخال هذا، يجب أن يتطابق مع اسم عنصر البطاقة المقابل.
• ‫description: وصف لمتغيّر الإدخال سيتم عرضه للمستخدمين النهائيين.
• cardinality: عدد القيم المسموح بها القيم المحتمَلة هي:
  • SINGLE: يُسمح بقيمة واحدة فقط.
• ‫dataType: نوع القيم المقبولة تحتوي dataType على السمة basicType التي تحدّد نوع البيانات. تشمل القيم الصالحة ما يلي:
  • ‫STRING: سلسلة أبجدية رقمية
  • ‫INTEGER: رقم
  • ‫TIMESTAMP: طابع زمني بتنسيق "ملّي ثانية منذ بدء حساب الفترة" على سبيل المثال، يتم تمثيل 27 نوفمبر 2025، الساعة 16:49:02 بالتوقيت العالمي المنسّق على النحو التالي: 1764262142988.
  • ‫BOOLEAN: إما true أو false.
  • ‫EMAIL_ADDRESS: عنوان بريد إلكتروني بالتنسيق [e-mail]

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

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 عدد صحيح، لا يمكنه الاحتفاظ بسلسلة.

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

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

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

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

/**
* 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 input fields are configured to let the user select outputs from previous
* workflow steps as input values using the `hostAppDataSource` property.
*/
function onConfigCalculate() {
  const firstInput = CardService.newTextInput()
    .setFieldName("value1") // "FieldName" must match an "id" in the manifest file's inputs[] array.
    .setTitle("First Value")
    .setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    );

  const secondInput = CardService.newTextInput()
    .setFieldName("value2") // "FieldName" must match an "id" in the manifest file's inputs[] array.
    .setTitle("Second Value")
    .setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    );

  const selectionInput = CardService.newSelectionInput()
    .setTitle("operation")
    .setFieldName("operation") // "FieldName" must match an "id" in the manifest file's inputs[] array.
    .setType(CardService.SelectionInputType.DROPDOWN)
    .addItem("+", "+", false)
    .addItem("-", "-", true)
    .addItem("x", "x", false)
    .addItem("/", "/", false);

  const sections = CardService.newCardSection()
    .setHeader("Action_sample: Calculate")
    .setId("section_1")
    .addWidget(firstInput)
    .addWidget(selectionInput)
    .addWidget(secondInput)

  let card = CardService.newCardBuilder()
    .addSection(sections)
    .build();

  return card;
}

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

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

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

• التحقّق من صحة متغيّر إدخال
• متغيّرات الإخراج
• المتغيّرات الديناميكية
• تسجيل النشاط والأخطاء
• عناصر أحداث Workspace Studio