الأزرار الديناميكية والمعاملات

الأزرار المضمّنة (inline) ليست دائماً ثابتة. يستطيع GetMyBot بناء لوحة مفاتيح من البيانات — زر لكل عنصر في القائمة — وإرفاق مجموعة معاملاته الخاصة بكل زر، محددة في لحظة إرسال الرسالة. هذا أساس سيناريوهات «اعرض الكتالوج → يختار المستخدم منتجاً محدداً → نكمل الطلب لذلك المنتج تحديداً». يُضبط كل شيء في كتلة الرسالة لإجراء «إرسال رسالة».

الأزرار الديناميكية من القائمة

كتلة «الأزرار الديناميكية من القائمة» تحوّل مصفوفة من ctx إلى لوحة مفاتيح: زر واحد لكل عنصر. تُضبط أربعة أمور:

  • القائمة — مفتاح المصفوفة في السياق (over)، مثلاً ctx.products. عادةً تضع المصفوفة هناك إجراءات «الاستعلام من المصدر» أو «طلب الويب» أو عمليات حسابية.
  • اسم مستعار للعنصر — الاسم الذي يكون تحته العنصر متاحاً في القالب (as، الافتراضي item).
  • أزرار في الصف — كم زراً يُوضع في السطر (columns، الافتراضي 1).
  • قالب الزر — زر عادي، لكن نصه وحقوله تدعم التعويضات بالاسم المستعار: {{item.name}}، {{item.price}} وما إلى ذلك.

عند الإرسال يُعرض القالب لكل عنصر، فتظهر أزرار بعدد عناصر القائمة. هكذا تُبنى الكتالوجات وقوائم سجلات المجموعات والقوائم من البيانات.

مثال

في ctx.products توجد مصفوفة كائنات بحقول id وname وprice. في قالب الزر حدّد النص {{item.name}} — {{item.price}} وفي Carry — المفتاح product_id بالقيمة {{item.id}}. ستحصل على زر لكل منتج، وعند النقر سيعرف البوت بالضبط أي منتج اختاره المستخدم.

معاملات النقر (Carry)

كتلة «Carry — لقطة البيانات في نقر الزر» ترفق بالزر مجموعة أزواج مفتاح → قيمة، محسوبة ومُثبَّتة في لحظة إرسال الرسالة. عند النقر تُستعاد هذه القيم في ctx — لذلك يحمل كل زر معاملاته الخاصة (per-invocation)، حتى لو كانت الأزرار عشرات وأُرسِلت في رسالة واحدة.

  • مفتاح carry — الاسم الذي ستعود تحته القيمة في ctx عند النقر.
  • قيمة carry — قالب بتعويضات ({{item.id}}، {{param.order_id}}، {{ctx.x}}), يُحسَب عند الإرسال.
  • للاستخدام مرة واحدة (single_use) — تُحذف الحمولة بعد أول نقر.
  • مدة صلاحية الحمولة (ttl_seconds) — مدة صلاحية اللقطة بالثواني (0 — القيمة الافتراضية).

هذه هي الميزة الجوهرية «المعاملات من الرابط المرتبطة بزر بعينه»: القيمة محفوظة في الزر لا في الحالة العامة للمستخدم، لذلك لا تتداخل النقرات المتزامنة.

ضبط المعاملات بالزر (set_params)

إضافةً إلى لقطة Carry، يستطيع الزر ضبط معاملات المشترك مباشرةً عند النقر — حقل «المعاملات» (set_params). بخلاف Carry (قيم مؤقتة في ctx)، يكتب set_params في معاملات المستخدم الدائمة ({{param.مفتاح}}), التي تبقى بين الجلسات. يوجد حقل مماثل في كتلة الرسالة — عندها تُضبط المعاملات عند الإرسال لا عند النقر.

عند النقر يستطيع الزر أيضاً إضافة علامات وإزالتها — بنفس الحقول المتوفرة في كتلة الرسالة.

الفرق بين الآليات الثلاث

  • Carry — لقطة في ctx، تعيش حتى النقر، مرتبطة بزر بعينه، مع TTL وخيار الاستخدام مرة واحدة.
  • set_params على الزر — يكتب معاملات دائمة للمشترك عند النقر.
  • set_params على الكتلة — يكتب معاملات دائمة عند إرسال الرسالة.

لسيناريو «اختار منتجاً — أكملنا طلبه» استخدم الأزرار الديناميكية + Carry: قائمة المنتجات تتحول إلى أزرار، وproduct_id لكل منتج يذهب في Carry الخاص بزره تحديداً.

الخطوات التالية