Clipboard API: النسخ واللصق في React

تكتب navigator.clipboard.writeText(text) سلسلة نصية في حافظة النظام وتعيد Promise. وهي البديل الحديث لنهج execCommand القديم. استخدم await دائمًا مع Promise وتعامل مع احتمال رفضها، مثلما يحدث عندما يرفض المستخدم الوصول إلى الحافظة.

تقرأ navigator.clipboard.readText() محتوى الحافظة الحالي كسلسلة نصية، وتعيد Promise أيضًا. تتطلب القراءة إذن clipboard-read، ويطلب المتصفح من المستخدم منحه. عمليًا، تُستخدم قراءة الحافظة بوتيرة أقل من الكتابة إليها في تطبيقات React المعتادة.

تفرض المتصفحات ألا يُستدعى clipboard.writeText إلا داخل معالج لإيماءة من المستخدم، مثل حدث النقر أو keydown. وسيؤدي استدعاؤه داخل useEffect أو بشكل غير متزامن بعد الإيماءة إلى طرح خطأ أمني. شغّل الكتابة دائمًا مباشرةً من معالج onClick.

النمط المعتاد هو: ينقر المستخدم زر النسخ، ويستدعي المعالج لديك navigator.clipboard.writeText(value)، وعند النجاح تعيّن حالة copied إلى true، ويعرض الزر مؤقتًا علامة صح أو التسمية "تم النسخ!". بعد فترة قصيرة يعود الزر إلى حالته العادية.

غلّف المنطق في خطاف باسم useCopyToClipboard يعيد صفيفًا: [copied, copyFn]. تقود القيمة المنطقية copied ملاحظات واجهة المستخدم، بينما تقبل copyFn النص المراد نسخه. يتولى الخطاف عملية الكتابة غير المتزامنة وأي خطأ داخليًا، لتظل المكوّنات بسيطة.

داخل الخطاف، بعد نجاح النسخ، عيّن setCopied(true) وجدول إعادة الضبط باستخدام setTimeout(() => setCopied(false), 2000). خزّن معرّف المهلة وامسحه في تنظيف useEffect لمنع تحديثات الحالة بعد إلغاء التركيب. يتجنب هذا التحذير "cannot update state on an unmounted component".

لا تدعم المتصفحات القديمة والصفحات التي لا تستخدم HTTPS واجهة Clipboard API. ينشئ الخيار البديل القديم عنصر textarea مؤقتًا، ويعيّن قيمته، ويضيفه إلى body، ويستدعي document.execCommand('copy')، ثم يزيل العنصر. هذا النهج متزامن ويعمل في كل مكان، لكنه مهجور.

قبل استخدام Clipboard API، تحقّق من: navigator.clipboard && typeof navigator.clipboard.writeText === 'function'. إذا لم تكن متوفرة، فاستخدم نهج execCommand القديم. يمنع هذا التحقق الوقائي أخطاء وقت التشغيل في البيئات التي لا تدعم الواجهة.

تتطلب قراءة الحافظة إذن المستخدم عبر Permissions API. يمكنك الاستعلام عن الحالة الحالية: navigator.permissions.query({ name: 'clipboard-read' }) يعيد PermissionStatus بحالة granted أو denied أو prompt. سيطلب المتصفح الإذن تلقائيًا عند استدعاء readText().

لا تتوفر Clipboard API إلا في السياقات الآمنة، مثل HTTPS أو localhost. في صفحات HTTP تكون navigator.clipboard مساوية لـ undefined. هذا قيد أمني لأن محتوى الحافظة قد يكون حساسًا. تحقّق دائمًا من توفر الواجهة قبل الرجوع إلى أساليبها لتجنب أخطاء المرجع الفارغ.

لا يطبّق jsdom (الذي يستخدمه Jest) Clipboard API. أنشئ له محاكاة في إعداد الاختبارات: Object.assign(navigator, { clipboard: { writeText: jest.fn().mockResolvedValue(undefined) } }). يتيح لك ذلك اختبار أن المكوّن يستدعي writeText بالوسيط الصحيح دون الحاجة إلى بيئة متصفح حقيقية.

متى يمكن استدعاء navigator.clipboard.writeText() بأمان في المتصفح؟

استخدم navigator.clipboard.writeText() داخل معالج النقر لنسخ النص. أنشئ hook باسم useCopyToClipboard يعيد [copied, copyFn] مع إعادة ضبط مؤقتة. تحقّق دائمًا من توفر API، ووفر بديلًا باستخدام execCommand للمتصفحات الأقدم، وأنشئ محاكاة لـ navigator.clipboard في اختبارات Jest.