تكامل نموذج الاتصال React (تطبيقات Vite والصفحة الواحدة)
كيفية إضافة نماذج الاتصال والتعليقات إلى React Single-Page Applications (SPA) المبنية باستخدام Vite أو Create React App، والتي تتميز بالدفاع عن البريد العشوائي وإشعارات البريد الوارد الفورية.
1. مكون نموذج الاتصال القياسي مع Vite
يستخدم مكون React خفيف الوزن خطافات React القياسية (useState) وواجهة برمجة تطبيقات Fetch للمتصفح لإرسالها مباشرة إلى نقطة نهاية Lugatu العامة. لا توجد مكتبات نماذج خارجية أو خوادم خلفية مطلوبة.
import React, { useState } from 'react';
export function ContactForm() {
const [formData, setFormData] = useState({ name: '', email: '', message: '', _gotcha: '' });
const [status, setStatus] = useState<'idle' | 'submitting' | 'success' | 'error'>('idle');
const [errorMessage, setErrorMessage] = useState('');
const handleSubmit = async (e: React.FormEvent) => {
e.preventDefault();
if (formData._gotcha) return; // Silent discard for automated bot traps
setStatus('submitting');
setErrorMessage('');
try {
const response = await fetch('https://www.lugatu.com/api/v1/public/forms/YOUR_PUBLIC_FORM_ID/submissions', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
},
body: JSON.stringify({
fields: {
name: formData.name,
email: formData.email,
message: formData.message,
},
honeypot: formData._gotcha,
}),
});
if (!response.ok) {
throw new Error('Failed to deliver message');
}
setStatus('success');
setFormData({ name: '', email: '', message: '', _gotcha: '' });
} catch (err: any) {
setStatus('error');
setErrorMessage(err.message || 'Submission error. Please try again.');
}
};
return (
<form onSubmit={handleSubmit} className="space-y-4 max-w-md">
<div>
<label htmlFor="react-name" className="block text-sm font-semibold mb-1">Your Name</label>
<input
id="react-name"
type="text"
required
value={formData.name}
onChange={(e) => setFormData({ ...formData, name: e.target.value })}
className="w-full border rounded-xl p-2.5"
/>
</div>
<div>
<label htmlFor="react-email" className="block text-sm font-semibold mb-1">Email Address</label>
<input
id="react-email"
type="email"
required
value={formData.email}
onChange={(e) => setFormData({ ...formData, email: e.target.value })}
className="w-full border rounded-xl p-2.5"
/>
</div>
<div>
<label htmlFor="react-message" className="block text-sm font-semibold mb-1">Message</label>
<textarea
id="react-message"
rows={4}
required
value={formData.message}
onChange={(e) => setFormData({ ...formData, message: e.target.value })}
className="w-full border rounded-xl p-2.5"
/>
</div>
<!-- Honeypot spam defense -->
<input
type="text"
name="_gotcha"
value={formData._gotcha}
onChange={(e) => setFormData({ ...formData, _gotcha: e.target.value })}
style={{ display: 'none' }}
tabIndex={-1}
autoComplete="off"
/>
<button
type="submit"
disabled={status === 'submitting'}
className="btn-primary-editorial py-2.5 px-6"
>
{status === 'submitting' ? 'Sending...' : 'Send Message'}
</button>
{status === 'success' && (
<p className="text-sm text-green-700 font-medium">Thank you! Your message was delivered.</p>
)}
{status === 'error' && (
<p className="text-sm text-red-600">{errorMessage}</p>
)}
</form>
);
}
2. التكامل مع React Hook Form وFormik
يتكامل نموذج إرسال JSON القياسي من Lugatu بسهولة مع مكتبات التحقق من صحة النماذج مثل React Hook Form أو Formik أو Zod. قم بتمرير القيم المتسلسلة مباشرة إلى كائن حمولة الحقول.
// React Hook Form submission handler
const onSubmit = async (data: FormValues) => {
const res = await fetch(`https://www.lugatu.com/api/v1/public/forms/${import.meta.env.VITE_LUGATU_FORM_ID}/submissions`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ fields: data }),
});
return res.ok;
};
3. متغيرات البيئة والفصل السري في رد الفعل
في Vite، تكون المتغيرات العامة مسبوقة بـ VITE_. استخدم VITE_LUGATU_FORM_ID لمعرف النموذج العام. لا تعرض مطلقًا مفتاح واجهة برمجة التطبيقات من خادم إلى خادم (lug_live_...) داخل التعليمات البرمجية المصدر أو المستودعات من جانب العميل.
مفاتيح Live API التي تبدأ بـ lug_live_ محجوزة بشكل صارم للتنفيذ من خادم إلى خادم. يتم رفض أي طلب متصفح يتم إرساله باستخدام مفتاح واجهة برمجة التطبيقات المباشر باستخدام HTTP 403.
الأمن والمصادقة الثابتة
الأمان الثابت: لا تقم مطلقًا ببادئة مفاتيح API المباشرة بـ VITE_ أو REACT_APP_. يجب على عملاء المتصفح الإرسال حصريًا إلى نقاط النهاية العامة بدون مفاتيح API.
استكشاف الأخطاء وإصلاحها وأخطاء العرض الشائعة
تأكد من إرسالك إلى نقطة النهاية العامة (https://www.lugatu.com/api/v1/public/forms/YOUR_PUBLIC_FORM_ID/submissions). نقاط النهاية من خادم إلى خادم (POST /api/v1/forms/{id}/submissions) تمنع أصول المتصفح بشكل صريح.
الأسئلة المتداولة
هل يمكنني استخدام React Hook Form أو Formik مع Lugatu؟
نعم. يقبل Lugatu معيار JSON مع كائن الحقول. يمكن لأي مكتبة نماذج React إجراء تسلسل لقيمها وإرسالها إلى نقطة النهاية العامة.
هل أنت مستعد لإنشاء نقطة نهاية النموذج الخاص بك؟
ابدأ مجانًا في ثوانٍ. لا حاجة لبطاقة الائتمان.