زر الدفع

مكون PaymentButton هو مكون React يوفر واجهة دفع كاملة لقبول مدفوعات سولانا. يتعامل مع ربط المحفظة واختيار الرمز المميز ومعالجة المعاملات وإدارة حالة واجهة المستخدم داخلياً. يأتي مع أزرار ونوافذ منبثقة قابلة للتخصيص:

زر الإكرامية

نافذة الدفع

نافذة رمز الاستجابة السريعة لـ Solana Pay

نافذة عربة التسوق

التثبيت

pnpm add @solana-commerce/kit

خصائص المكون

`PaymentButtonProps`

يقبل مكون PaymentButton الخصائص التالية:

الخصائص المطلوبة

config (SolanaCommerceConfig) - كائن الإعدادات الرئيسي لمكون الدفع. هذه هي الخاصية المطلوبة الوحيدة. راجع SolanaCommerceConfig أدناه.

الخصائص الاختيارية

paymentConfig (PaymentConfig) - إعدادات خاصة بالدفع تتضمن المنتجات وتجاوزات التسعير وأدوات جلب الأسعار المخصصة. راجع PaymentConfig أدناه.
onPayment ((amount: number, currency: string) => void) - يتم استدعاؤها عند بدء الدفع بعد أن يؤكد المستخدم المبلغ والعملة. تستقبل مبلغ الدفع (بوحدات الرمز المميز وليس lamports) ومعرف العملة.
onPaymentStart (() => void) - يتم استدعاؤها عند بدء عملية الدفع، قبل إرسال المعاملة الفعلية. استخدم هذا لعرض حالات التحميل أو تتبع التحليلات.
onPaymentSuccess ((signature: string) => void) - يتم استدعاؤها عندما يتم تأكيد المعاملة على السلسلة. تستقبل توقيع المعاملة. هنا يجب عليك تحديث حالة الطلب وإرسال رسائل التأكيد بالبريد الإلكتروني، إلخ.
onPaymentError ((error: Error) => void) - يتم استدعاؤها عند فشل الدفع في أي مرحلة (اتصال المحفظة أو إرسال المعاملة أو التأكيد). يحتوي كائن الخطأ على تفاصيل حول ما حدث من خطأ.
onCancel (() => void) - يتم استدعاؤها عندما يلغي المستخدم صراحةً عملية الدفع (يغلق النافذة المنبثقة أو ينقر على إلغاء).
children (React.ReactNode) - عنصر تشغيل مخصص اختياري. إذا تم توفيره، فإنه يحل محل زر الدفع الافتراضي. يجب أن يكون العنصر الفرعي قابلاً للنقر (على سبيل المثال، زر).
className (string) - اسم فئة CSS المطبق على زر التشغيل (يُستخدم فقط عندما لا يتم توفير عناصر فرعية مخصصة).
style (React.CSSProperties) - الأنماط المضمنة المطبقة على زر التشغيل (تُستخدم فقط عندما لا يتم توفير عناصر فرعية مخصصة).
variant ('default' | 'icon-only') - نوع الزر. الإعداد الافتراضي يعرض النص والأيقونة، 'icon-only' يعرض أيقونة الدفع فقط.

كائنات التكوين

`SolanaCommerceConfig`

كائن التكوين الرئيسي الذي يتم تمريره إلى الخاصية config.

الحقول المطلوبة

merchant (MerchantConfig) - معلومات التاجر وتفاصيل مستلم الدفع. راجع MerchantConfig.
mode ('cart' | 'tip' | 'buyNow') - وضع الدفع الذي يحدد نص عرض الزر وتدفق واجهة المستخدم:
- 'buyNow' - شراء منتج واحد بمبلغ ثابت
- 'cart' - سلة تسوق تحتوي على منتجات متعددة
- 'tip' - يختار المستخدم المبلغ الخاص به (التبرعات/الإكراميات)

الحقول الاختيارية

position ('inline' | 'overlay') - كيفية عرض واجهة الدفع. الإعداد الافتراضي هو 'overlay'.
- 'overlay' - يفتح في نافذة منبثقة/درج تراكبي
- 'inline' - مضمّن مباشرة في الصفحة
theme (ThemeConfig) - خيارات التخصيص المرئي. راجع ThemeConfig.
network ('mainnet' | 'devnet' | 'testnet') - شبكة سولانا المراد استخدامها. الإعداد الافتراضي هو 'mainnet'.
rpcUrl (string) - عنوان URL مخصص لنقطة نهاية RPC. إذا لم يتم توفيره، فسيتم استخدام نقطة نهاية عامة افتراضية للشبكة المحددة.
allowedMints (string[]) - مصفوفة من عناوين سك الرموز لتقييد طرق الدفع. إذا لم يتم توفيرها، فستكون جميع الرموز المدعومة (SOL وUSDC وUSDT) متاحة.
showQR (boolean) - ما إذا كان سيتم عرض خيار الدفع عبر رمز QR. مفيد للأجهزة المحمولة وتكامل Solana Pay.
enableWalletConnect (boolean) - ما إذا كان سيتم تمكين الاتصال بالمحفظة. اضبطه على false إذا كنت تتعامل مع الاتصال بالمحفظة خارجياً.
showMerchantInfo (boolean) - ما إذا كان سيتم عرض اسم التاجر والشعار في واجهة الدفع.
debug (boolean) - يتيح تسجيل وحدة التحكم التفصيلي لأغراض التصحيح.

`MerchantConfig`

يحدد مستلم الدفع ومعلومات النشاط التجاري.

الحقول المطلوبة

name (string) - اسم النشاط التجاري أو التاجر الذي يُعرض للمستخدمين أثناء الدفع.
wallet (string) - عنوان محفظة سولانا التي ستستقبل المدفوعات. يجب أن يكون عنوان سولانا صالحاً مشفراً بنظام base58.

الحقول الاختيارية

logo (string) - رابط URL لصورة شعار التاجر. يُعرض في واجهة الدفع عند تمكين showMerchantInfo.
description (string) - وصف النشاط التجاري الذي يُعرض للمستخدمين.

`ThemeConfig`

التخصيص المرئي لواجهة الدفع.

جميع الحقول اختيارية ولها قيم افتراضية معقولة.

primaryColor (string) - اللون الأساسي للعلامة التجارية المستخدم للأزرار والعناصر البارزة. القيمة الافتراضية: '#9945FF' (البنفسجي الخاص بسولانا).
secondaryColor (string) - اللون الثانوي البارز. القيمة الافتراضية: '#14F195' (الأخضر الخاص بسولانا).
backgroundColor (string) - لون خلفية النافذة المنبثقة/الحاوية. القيمة الافتراضية: '#ffffff'.
textColor (string) - لون النص الأساسي. القيمة الافتراضية: '#111827'.
borderRadius ('none' | 'sm' | 'md' | 'lg' | 'xl' | 'full') - نصف قطر الحدود المطبق على عناصر الواجهة. القيمة الافتراضية: 'lg'.
- 'none' = 0px
- 'sm' = 12px
- 'md' = 16px
- 'lg' = 20px
- 'xl' = 24px
- 'full' = مستدير بالكامل (حسب السياق)
fontFamily (string) - عائلة الخط لجميع النصوص. القيمة الافتراضية: 'system-ui, -apple-system, sans-serif'.
buttonShadow ('none' | 'sm' | 'md' | 'lg' | 'xl') - ظل منسدل للأزرار. القيمة الافتراضية: 'md'.
buttonBorder ('none' | 'black-10') - نمط الحدود للأزرار. القيمة الافتراضية: 'black-10' (حدود سوداء خفيفة).

`PaymentConfig`

إعدادات الدفع المتقدمة للتسعير والكسور العشرية والمنتجات.

جميع الحقول اختيارية.

products (Product[]) - مصفوفة المنتجات لأوضاع 'cart' أو 'buyNow'. مطلوب عند استخدام هذه الأوضاع. كل منتج يحتوي على:
- id (سلسلة نصية، مطلوب) - معرّف فريد للمنتج
- name (سلسلة نصية، مطلوب) - اسم المنتج المعروض للمستخدم
- quantity (رقم، مطلوب) - كمية هذا المنتج
- price (رقم، اختياري) - السعر لكل وحدة بالدولار الأمريكي
- unitAmount (رقم، اختياري) - بديل لحقل price
- description (سلسلة نصية، اختياري) - وصف المنتج
solPriceUsd (number) - سعر SOL ثابت بالدولار الأمريكي. استخدم هذا للاختبار أو عندما تريد تثبيت سعر SOL. إذا لم يتم تقديمه، يقوم المكوّن بجلب السعر الحالي من CoinGecko.
getSolPrice (() => Promise<number>) - دالة مخصصة لجلب سعر SOL. استخدم هذا لـ:
- أوراكل الأسعار الخاصة
- تجنب حدود معدل الاستخدام لواجهات برمجة التطبيقات العامة
- منطق التسعير المخصص
- التطبيقات المؤسسية
إذا لم يتم تقديمه، يتم استخدام واجهة برمجة التطبيقات العامة لـ CoinGecko افتراضيًا مع التخزين المؤقت لمدة دقيقة واحدة.
tokenDecimals ({ [currency: string]: number }) - تجاوز دقة الكسور العشرية للرمز المميز. مفيد للرموز المخصصة. مثال:
```
tokenDecimals: {
  'CUSTOM': 8,
  'USDC': 6  // Can override defaults
}
```
fallbackSolPriceUsd (number) - سعر SOL احتياطي في حالة فشل واجهة برمجة التطبيقات للسعر وعدم توفر ذاكرة تخزين مؤقت. بدون هذا، ستعرض واجهة الدفع خطأ إذا فشل جلب السعر.

الخطافات الداخلية

يستخدم مكوّن PaymentButton عدة خطافات داخلية لإدارة الحالة وحساب القيم:

`useTheme(theme?: ThemeConfig)`

يدمج إعدادات السمة المقدمة من المستخدم مع قيم السمة الافتراضية. يُرجع كائن ThemeConfig كاملاً مع جميع الحقول المملوءة.

قيم السمة الافتراضية:

primaryColor: '#9945FF'
secondaryColor: '#14F195'
backgroundColor: '#ffffff'
textColor: '#111827'
borderRadius: 'lg'
fontFamily: 'system-ui, -apple-system, sans-serif'
buttonShadow: 'md'
buttonBorder: 'black-10'

الخطاف محفوظ في الذاكرة ويعيد الحساب فقط عندما يتغير تكوين السمة.

`useTotalAmount(mode, paymentConfig?)`

يحسب إجمالي مبلغ الدفع بناءً على وضع التجارة والمنتجات.

السلوك حسب الوضع:

وضع 'tip' - يُرجع 0 (يحدد المستخدم المبلغ)
وضعي 'cart' و 'buyNow' - يجمع price * quantity لجميع المنتجات في paymentConfig.products

يتعامل الخطاف مع الحالات الاستثنائية:

الأسعار المفقودة أو غير الصالحة تُعين افتراضياً إلى 0
الكميات المفقودة أو غير الصالحة تُعين افتراضياً إلى 0
يضمن أن جميع القيم أرقام محدودة
يدعم حقول المنتج price و unitAmount

يُرجع المبلغ الإجمالي كرقم (بالدولار الأمريكي لـ cart/buyNow، 0 لـ tip).

`usePaymentUrl(merchant, amount, mode)`

يُنشئ رابط سولانا Pay للدفع. يمكن ترميز هذا الرابط كرمز QR لمسحه بواسطة المحفظة المحمولة.

يُرجع: رابط بروتوكول solana: مع معاملات استعلام لـ:

recipient - عنوان محفظة التاجر
amount - مبلغ الدفع
reference - مرجع دفع فريد (يتم إنشاؤه من الطابع الزمني + سلسلة عشوائية)
label - اسم التاجر (معقم لأمان الرابط)
message - رسالة سياقية بناءً على الوضع

يُرجع سلسلة نصية فارغة إذا كانت محفظة التاجر غير صالحة أو كان المبلغ <= 0.

الأمان: يتم تعقيم اسم التاجر باستخدام sanitizeString() لمنع هجمات XSS من خلال حقن الروابط.

التحقق والتعامل مع الأخطاء

يقوم المكون بالتحقق قبل العرض:

التحقق من المحفظة - يستخدم isAddress() من gill للتحقق من عنوان محفظة التاجر. إذا كان غير صالح، يعرض حالة خطأ بدلاً من واجهة الدفع.
التحقق من التسعير - يضمن تكوين تسعير صالح:
- لوضع 'tip': صالح دائماً (يختار المستخدم المبلغ)
- لوضعي 'cart' و 'buyNow': يتحقق من أن totalAmount > 0
أمان SSR - يستخدم الكشف من جانب العميل لمنع عدم تطابق الترطيب. تضمن حالة isClient أن الميزات الخاصة بالمتصفح فقط (مثل localStorage لاستمرارية المحفظة) تعمل فقط على جانب العميل.

بنية المكونات

يقوم PaymentButton بتغليف جميع العناصر الفرعية في موفري سياق اثنين:

AppProvider - يوفر حالة اتصال المحفظة وعميل الموصل
- الاتصال التلقائي: معطل افتراضياً
- التخزين: يستخدم localStorage عندما يكون متاحاً (جانب العميل فقط)
- وضع التصحيح: قابل للتكوين عبر الإعدادات
ArcProvider - يوفر عميل بلوكتشين سولانا واتصال RPC
- الشبكة: يتم تحديدها من config.network
- عنوان RPC: يستخدم الحل من جانب الخادم مع الاحتياطي إلى نقاط النهاية العامة

حل عنوان RPC

يتضمن المكون حلاً متطوراً لعنوان RPC:

إذا تم توفير config.rpcUrl، يتم استخدامه مباشرة
وإلا، يستدعي محللاً من جانب الخادم يختار نقاط النهاية الموثوقة
يرجع إلى https://api.mainnet-beta.solana.com في حالة فشل الحل
يحدث الحل بشكل غير متزامن عند التحميل ويحدث الحالة

أوضاع العرض

وضع التراكب (position: 'overlay' أو افتراضي):

يعرض زر تشغيل (مخصص أو افتراضي)
يفتح واجهة الدفع في نافذة منبثقة متجاوبة (سطح المكتب) أو درج (الجوال)
يستخدم مكون ResponsiveShell للتخطيطات التكيفية

الوضع المضمن (position: 'inline'):

يدمج واجهة الدفع مباشرة في الصفحة
لا حاجة لزر التشغيل
مفيد لصفحات الدفع المخصصة

يستخدم كلا الوضعين SecureIframeShell داخلياً لعرض واجهة الدفع في إطار iframe معزول لأغراض الأمان.

أمثلة الاستخدام

الدفع الأساسي

<PaymentButton
  config={{
    merchant: {
      name: "Coffee Shop",
      wallet: "your-wallet-address"
    },
    mode: "buyNow"
  }}
  paymentConfig={{
    products: [
      {
        id: "coffee-001",
        name: "Espresso",
        price: 4.5,
        quantity: 1
      }
    ]
  }}
  onPaymentSuccess={(sig) => {
    console.log("Payment confirmed:", sig);
  }}
/>

أداة الإكرامية مع جالب سعر مخصص

<PaymentButton
  config={{
    merchant: {
      name: "Content Creator",
      wallet: "creator-wallet"
    },
    mode: "tip"
  }}
  paymentConfig={{
    // Use your own price API to avoid rate limits
    getSolPrice: async () => {
      const res = await fetch("/custom-api/solana-price");
      const data = await res.json();
      return data.price;
    },
    // Fallback if your API fails
    fallbackSolPriceUsd: 200
  }}
/>

عربة التسوق مع سمة مخصصة

<PaymentButton
  config={{
    merchant: {
      name: "My Store",
      wallet: "store-wallet",
      logo: "/logo.png"
    },
    mode: "cart",
    theme: {
      primaryColor: "#FF6B6B",
      backgroundColor: "#1a1a1a",
      textColor: "#ffffff",
      borderRadius: "xl",
      buttonShadow: "lg"
    },
    showMerchantInfo: true
  }}
  paymentConfig={{
    products: [
      { id: "1", name: "T-Shirt", price: 25, quantity: 2 },
      { id: "2", name: "Hoodie", price: 45, quantity: 1 }
    ]
  }}
  onPaymentSuccess={(signature) => {
    // Verify transaction on your backend
    fetch("/api/verify-payment", {
      method: "POST",
      body: JSON.stringify({ signature })
    });
  }}
/>

زر تشغيل مخصص

<PaymentButton
  config={{
    merchant: { name: "Shop", wallet: "address" },
    mode: "buyNow"
  }}
  paymentConfig={{
    products: [{ id: "1", name: "Product", price: 10, quantity: 1 }]
  }}
>
  <button className="custom-button">🚀 Pay with Solana</button>
</PaymentButton>

جدول المحتويات